Author: markh
Date: Wed May 21 04:46:37 2008
New Revision: 658636
URL: http://svn.apache.org/viewvc?rev=658636&view=rev
Log:
Added some documentation
Added:
maven/shared/trunk/maven-runtime/src/site/
maven/shared/trunk/maven-runtime/src/site/apt/
maven/shared/trunk/maven-runtime/src/site/apt/examples/
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class-loader.apt
(with props)
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class.apt
(with props)
maven/shared/trunk/maven-runtime/src/site/apt/index.apt (with props)
maven/shared/trunk/maven-runtime/src/site/apt/usage.apt (with props)
maven/shared/trunk/maven-runtime/src/site/fml/
maven/shared/trunk/maven-runtime/src/site/fml/faq.fml (with props)
maven/shared/trunk/maven-runtime/src/site/site.xml (with props)
Added:
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class-loader.apt
URL:
http://svn.apache.org/viewvc/maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class-loader.apt?rev=658636&view=auto
==============================================================================
---
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class-loader.apt
(added)
+++
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class-loader.apt
Wed May 21 04:46:37 2008
@@ -0,0 +1,81 @@
+ ------
+ Introspecting a class loader
+ ------
+ Mark Hobson
+ <[EMAIL PROTECTED]>
+ ------
+ 19 May 2008
+ ------
+
+
+Introspecting a class loader
+
+ Maven Runtime can introspect a class loader to obtain metadata for each Maven
project accessible within it.
+
+* Using project properties
+
+ To obtain a list of
+
<<<{{{../apidocs/org/apache/maven/shared/runtime/MavenProjectProperties.html}MavenProjectProperties}}>>>
+ instances for each Maven project accessible within a specified class loader:
+
+---
+/**
+ * @component
+ */
+private MavenRuntime runtime;
+
+public void processProjects() throws MavenRuntimeException
+{
+ ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+ List<MavenProjectProperties> projects = runtime.getProjectsProperties(
classLoader );
+
+ // process projects
+}
+---
+
+* Using project XML
+
+ To obtain a list of
+
<<<{{{http://maven.apache.org/ref/current/maven-project/apidocs/org/apache/maven/project/MavenProject.html}MavenProject}}>>>
+ instances for each Maven project accessible within a specified class loader:
+
+---
+/**
+ * @component
+ */
+private MavenRuntime runtime;
+
+public void processProjects() throws MavenRuntimeException
+{
+ ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+ List<MavenProject> projects = runtime.getProjects( classLoader );
+
+ // process projects
+}
+---
+
+* Sorting projects by dependency order
+
+ When obtaining Maven metadata using project XML, the resultant
<<<MavenProject>>> instances can be sorted by dependency
+ order. To obtain a list of <<<MavenProject>>> instances for each Maven
project accessible within a specified class
+ loader ordered by their dependencies:
+
+---
+/**
+ * @component
+ */
+private MavenRuntime runtime;
+
+public void processProjects() throws MavenRuntimeException
+{
+ ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+ List<MavenProject> projects = runtime.getSortedProjects( classLoader );
+
+ // process projects
+}
+---
+
+ Note that project properties cannot be sorted by dependency order since they
do not contain any dependency information.
Propchange:
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class-loader.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class-loader.apt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Added:
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class.apt
URL:
http://svn.apache.org/viewvc/maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class.apt?rev=658636&view=auto
==============================================================================
---
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class.apt
(added)
+++
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class.apt
Wed May 21 04:46:37 2008
@@ -0,0 +1,60 @@
+ ------
+ Introspecting a class
+ ------
+ Mark Hobson
+ <[EMAIL PROTECTED]>
+ ------
+ 19 May 2008
+ ------
+
+
+Introspecting a class
+
+ Maven Runtime can introspect a class to obtain its related Maven project's
metadata.
+
+ Note that this relies on the Maven descriptor files being unique relative to
the class being introspected. For
+ example, this is true within a jar produced by the
+ {{{http://maven.apache.org/plugins/maven-jar-plugin/}Maven Jar Plugin}}, and
also within a jar inside a war. This does
+ not hold within a jar built by
+ {{{http://maven.apache.org/plugins/maven-assembly-plugin/}Maven Assembly
Plugin's}}
+
{{{http://maven.apache.org/plugins/maven-assembly-plugin/descriptor-refs.html#jar-with-dependencies}jar-with-dependencies}}
+ descriptor, since there are multiple Maven descriptors relative to a given
class, resulting in an ambiguity.
+
+* Using project properties
+
+ To obtain a
<<<{{{../apidocs/org/apache/maven/shared/runtime/MavenProjectProperties.html}MavenProjectProperties}}>>>
+ instance for a class's Maven project:
+
+---
+/**
+ * @component
+ */
+private MavenRuntime runtime;
+
+public void processProject() throws MavenRuntimeException
+{
+ MavenProjectProperties project = runtime.getProjectProperties(
MyClass.class );
+
+ // process project
+}
+---
+
+* Using project XML
+
+ To obtain a
+
<<<{{{http://maven.apache.org/ref/current/maven-project/apidocs/org/apache/maven/project/MavenProject.html}MavenProject}}>>>
+ instance for a class's Maven project:
+
+---
+/**
+ * @component
+ */
+private MavenRuntime runtime;
+
+public void processProject() throws MavenRuntimeException
+{
+ MavenProject project = runtime.getProject( MyClass.class );
+
+ // process project
+}
+---
Propchange:
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
maven/shared/trunk/maven-runtime/src/site/apt/examples/introspecting-a-class.apt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Added: maven/shared/trunk/maven-runtime/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/maven/shared/trunk/maven-runtime/src/site/apt/index.apt?rev=658636&view=auto
==============================================================================
--- maven/shared/trunk/maven-runtime/src/site/apt/index.apt (added)
+++ maven/shared/trunk/maven-runtime/src/site/apt/index.apt Wed May 21 04:46:37
2008
@@ -0,0 +1,39 @@
+ ------
+ Introduction
+ ------
+ Mark Hobson
+ <[EMAIL PROTECTED]>
+ ------
+ 19 May 2008
+ ------
+
+
+Maven Runtime
+
+ Maven Runtime allows introspection of Maven project metadata at runtime.
Basic artifact information or full Maven
+ project metadata can be obtained for all projects within a given class
loader, optionally sorted into dependency order,
+ and also for a given class within a project. These techniques can used by
tools wishing to utilize Maven metadata at
+ runtime.
+
+ Maven metadata is obtained from one of the two
+
{{{http://maven.apache.org/shared/maven-archiver/index.html#class_archive}Maven
descriptor files}} automatically
+ generated by the {{{http://maven.apache.org/shared/maven-archiver/}Maven
Archiver}}: <<<pom.properties>>> and
+ <<<pom.xml>>> in the <<<META-INF/<groupId>/<artifactId>>>> directory. The
project properties file provides basic
+ artifact information (group id, artifact id and version), whereas the project
XML file provides full Maven metadata
+ contained within the project's POM.
+
+ Note that since Maven Runtime uses resources generated by the Maven Archiver,
it can only successfully introspect the
+ runtime environment when executed from within the packaged project, as
opposed to running within an IDE.
+
+* Usage
+
+ Instructions on how to use Maven Runtime can be found on the
{{{usage.html}usage page}}.
+
+* Examples
+
+ To provide you with better understanding of some usages of Maven Runtime, you
can take a look into the following
+ examples:
+
+ * {{{examples/introspecting-a-class-loader.html}Introspecting a class loader}}
+
+ * {{{examples/introspecting-a-class.html}Introspecting a class}}
Propchange: maven/shared/trunk/maven-runtime/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/shared/trunk/maven-runtime/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Added: maven/shared/trunk/maven-runtime/src/site/apt/usage.apt
URL:
http://svn.apache.org/viewvc/maven/shared/trunk/maven-runtime/src/site/apt/usage.apt?rev=658636&view=auto
==============================================================================
--- maven/shared/trunk/maven-runtime/src/site/apt/usage.apt (added)
+++ maven/shared/trunk/maven-runtime/src/site/apt/usage.apt Wed May 21 04:46:37
2008
@@ -0,0 +1,35 @@
+ ------
+ Usage
+ ------
+ Mark Hobson
+ <[EMAIL PROTECTED]>
+ ------
+ 19 May 2008
+ ------
+
+
+Usage
+
+ Maven Runtime allows introspection of Maven project metadata at runtime. The
main entry point is the
+ {{{apidocs/org/apache/maven/shared/runtime/MavenRuntime.html}MavenRuntime}}
Plexus component. The following example
+ describes the basic usage of the component:
+
+---
+/**
+ * @component
+ */
+private MavenRuntime runtime;
+
+public void printProjects() throws MavenRuntimeException
+{
+ ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
+
+ for ( MavenProjectProperties properties : runtime.getProjectsProperties(
classLoader ) )
+ {
+ System.out.println( properties );
+ }
+}
+---
+
+ This method will display the group id, artifact id and version of every Maven
project within the current thread's
+ context class loader.
Propchange: maven/shared/trunk/maven-runtime/src/site/apt/usage.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/shared/trunk/maven-runtime/src/site/apt/usage.apt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Added: maven/shared/trunk/maven-runtime/src/site/fml/faq.fml
URL:
http://svn.apache.org/viewvc/maven/shared/trunk/maven-runtime/src/site/fml/faq.fml?rev=658636&view=auto
==============================================================================
--- maven/shared/trunk/maven-runtime/src/site/fml/faq.fml (added)
+++ maven/shared/trunk/maven-runtime/src/site/fml/faq.fml Wed May 21 04:46:37
2008
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<faqs id="FAQ" title="Frequently Asked Questions">
+
+ <part id="General">
+
+ <faq id="question1">
+ <question>Why is Maven Runtime returning no information when
introspecting?</question>
+ <answer>
+ <p>
+ This may be for one of the following reasons:
+ <ul>
+ <li>
+ Maven Runtime is being run within an IDE. This is because the
Maven descriptor files created by Maven
+ Archiver are not present, and these files are used to obtain
Maven project metadata. Maven Runtime
+ will return the correct information when run within the
project's normal packaging.
+ </li>
+ <li>
+ Maven Archiver has been configured to not generate Maven
descriptors. If the
+ <a
href="http://maven.apache.org/shared/maven-archiver/index.html#class_archive";>addMavenDescriptor</a>
+ configuration parameter has been set to <code>false</code>, then
Maven Runtime will not be able to access
+ project's Maven metadata at runtime. This parameter must be set
to <code>true</code> in order to use
+ Maven Runtime.
+ </li>
+ </ul>
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="question2">
+ <question>Why is Maven Runtime returning the wrong project for a given
class?</question>
+ <answer>
+ <p>
+ This can happen if multiple Maven descriptors are present relative
to the class. Typically this occurs when
+ multiple Maven projects are merged into a single archive. For
example, when using
+ <a
href="http://maven.apache.org/plugins/maven-assembly-plugin/";>Maven Assembly
Plugin's</a>
+ <a
href="http://maven.apache.org/plugins/maven-assembly-plugin/descriptor-refs.html#jar-with-dependencies";>jar-with-dependencies</a>.
+ </p>
+ </answer>
+ </faq>
+
+ </part>
+
+</faqs>
Propchange: maven/shared/trunk/maven-runtime/src/site/fml/faq.fml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/shared/trunk/maven-runtime/src/site/fml/faq.fml
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Added: maven/shared/trunk/maven-runtime/src/site/site.xml
URL:
http://svn.apache.org/viewvc/maven/shared/trunk/maven-runtime/src/site/site.xml?rev=658636&view=auto
==============================================================================
--- maven/shared/trunk/maven-runtime/src/site/site.xml (added)
+++ maven/shared/trunk/maven-runtime/src/site/site.xml Wed May 21 04:46:37 2008
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+-->
+
+<project>
+ <body>
+ <menu name="Overview">
+ <item name="Introduction" href="index.html"/>
+ <item name="Usage" href="usage.html"/>
+ <item name="FAQ" href="faq.html"/>
+ </menu>
+ <menu name="Examples">
+ <item name="Introspecting a class loader"
href="examples/introspecting-a-class-loader.html"/>
+ <item name="Introspecting a class"
href="examples/introspecting-a-class.html"/>
+ </menu>
+ <menu ref="reports"/>
+ </body>
+</project>
Propchange: maven/shared/trunk/maven-runtime/src/site/site.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/shared/trunk/maven-runtime/src/site/site.xml
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
