Author: mcconnell
Date: Sun Jun 20 06:43:18 2004
New Revision: 21507
Added:
avalon/trunk/central/site/src/xdocs/central/tools/magic/model/imports.xml
Removed:
avalon/trunk/central/site/magic.properties
avalon/trunk/central/site/magic.sequence
Modified:
avalon/trunk/central/site/src/xdocs/central/tools/magic/model/index.xml
avalon/trunk/central/site/src/xdocs/central/tools/magic/model/navigation.xml
avalon/trunk/central/site/src/xdocs/central/tools/magic/model/plugins.xml
avalon/trunk/central/site/src/xdocs/central/tools/magic/model/projects.xml
avalon/trunk/central/site/src/xdocs/central/tools/magic/model/resources.xml
avalon/trunk/central/system/index.xml
Log:
magic doc updates
Added: avalon/trunk/central/site/src/xdocs/central/tools/magic/model/imports.xml
==============================================================================
--- (empty file)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/model/imports.xml Sun Jun 20 06:43:18 2004
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+
+ <properties>
+ <author email="[email protected]">Avalon Documentation Team</author>
+ <title>Avalon Central</title>
+ </properties>
+
+ <body>
+ <section name="Imports">
+ <p>
+ An index.xml can import the definitions from another index.xml.
+ Importing an index results in the creation of resource
+ defintions - in particular, project and plugin definitions
+ are converted to resource defintions.
+ </p>
+
+ <p><i>Example import.</i></p>
+
+<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<system>
+
+ <import index="../central/system/index.xml"/>
+
+ <project basedir="tutorials/hello" key="avalon-tutorial-hello">
+ <info>
+ <group>avalon/tutorial</group>
+ <name>hello</name>
+ </info>
+ <dependencies>
+ <include key="avalon-framework-api"/>
+ </dependencies>
+ <plugins>
+ <include key="avalon-meta-tools"/>
+ </plugins>
+ </project>
+
+ <project basedir="tutorials/dynamics" key="avalon-tutorial-dynamics">
+ <info>
+ <group>avalon/tutorial</group>
+ <name>dynamics</name>
+ </info>
+ <dependencies>
+ <include key="avalon-framework-api"/>
+ <include key="avalon-framework-impl"/>
+ <include key="avalon-composition-api"/>
+ <include key="avalon-meta-api"/>
+ </dependencies>
+ <plugins>
+ <include key="avalon-meta-tools"/>
+ </plugins>
+ </project>
+
+</system>
+]]></source>
+
+ </section>
+ </body>
+
+</document>
+
Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/model/index.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/model/index.xml (original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/model/index.xml Sun Jun 20 06:43:18 2004
@@ -7,201 +7,67 @@
</properties>
<body>
- <section name="Magic's Project Model">
+ <section name="Magic's System Model">
<p>
- The notion of a POM (Project Object Model) is familiar to
- Maven users. Magic extends this concepts through complete support
- for transitive inheritance of dependency information together with
- build, test and runtime scopes.
+ Magic provides complete support for transitive inheritance of dependency
+ information together with build, test and runtime scoping. This
+ information enables the automation of path construction for compilation,
+ unit-testing, and build tasks the use runtime path information.
</p>
<p>
The magic system defintion is based on one or more index.xml files.
- The index.xml file contains resource, project, and plugin defintions.
+ The index.xml file may contain any number of the following elements:
</p>
- <p>
- A resource can be viewed as a logical artifact accessible from
- a repository cache using group, name and version information.
- Resources are resolved to file paths using the following convention:
- </p>
-
-<source><![CDATA[
- [cache]/[group]/[type]s/[name]-[version].[type]
-]]></source>
+ <ul>
+ <li><a href="resources.html">resource</a></li>
+ <li><a href="projects.html">project</a></li>
+ <li><a href="plugins.html">plugin</a></li>
+ <li><a href="imports.html">import</a></li>
+ </ul>
- <p><i>Example resource descriptor:</i></p>
+ <p>The following xml is an example of a magic index.xml.</p>
<source><![CDATA[
<?xml version="1.0" encoding="ISO-8859-1"?>
<system>
- <resource>
- <info>
- <group>log4j</group>
- <name>log4j</name>
- <version>1.2.8</version>
- <type>jar</type>
- </info>
- </resource>
-
- ....
-
-</system>
-]]></source>
-
- <p>
- A project extends the concept of a resource to include a local basedir
- reference (the root of the project sources) and a set of dependencies.
- </p>
+ <import index="../central/system/index.xml"/>
- <p><i>
- Example of two project defintions:
- </i></p>
-<source><![CDATA[
- <project basedir="../../runtime/util/env">
+ <project basedir="tutorials/hello" key="avalon-tutorial-hello">
<info>
- <group>avalon/util</group>
- <name>avalon-util-env</name>
- <version>1.1.1</version>
- </info>
- </project>
-
- <project basedir="../../runtime/util/defaults">
- <info>
- <group>avalon/util</group>
- <name>avalon-util-defaults</name>
- <version>1.2.1</version>
+ <group>avalon/tutorial</group>
+ <name>hello</name>
</info>
<dependencies>
- <include key="avalon-util-env"/>
+ <include key="avalon-framework-api"/>
</dependencies>
+ <plugins>
+ <include key="avalon-meta-tools"/>
+ </plugins>
</project>
-]]></source>
-
- <p>
- In the above example Magic locates the project sources using the
- declared basedir. The name element is used as the default key
- that is used when referencing the project - as is the case in the
- second project defintions dependency declaration.
- </p>
-
- <p>
- Dependendency declarations within a project refernence the name of another
- another project within the scope of an index.xml file or imported file. As such, a
- dependency declaration can be resolved to an artifact group, name, version
- and type, and from this information, a repository based resource can be
- resolved, or in the case of a project or plugin reference, a target can be
- built as part of a higher-level build scenario.
- </p>
-
- <p>
- The declaration of dependendency implicitly introduced a dependency
- by the dependee on the dependent of the dependency. In other words, dependency
- declarations are transative. Magic provides support for the qualification of
- transativate dependency inheritance relative to the following three policies:
- </p>
- <ul>
- <li>BUILD</li>
- <li>TEST</li>
- <li>RUNTIME</li>
- </ul>
-
- <p><i>Example of scoped dependency.</i></p>
-
-<source><![CDATA[
- <project basedir="../../runtime/meta/api">
+ <project basedir="tutorials/dynamics" key="avalon-tutorial-dynamics">
<info>
- <group>avalon/meta</group>
- <name>avalon-meta-api</name>
- <version>1.4.0</version>
+ <group>avalon/tutorial</group>
+ <name>dynamics</name>
</info>
<dependencies>
<include key="avalon-framework-api"/>
- <include key="avalon-framework-impl" build="false" test="true" runtime="false"/>
+ <include key="avalon-framework-impl"/>
+ <include key="avalon-composition-api"/>
+ <include key="avalon-meta-api"/>
</dependencies>
+ <plugins>
+ <include key="avalon-meta-tools"/>
+ </plugins>
</project>
-]]></source>
-
- <p>
- In the above example the avalon-framework-impl artifact will be included
- in path constructs for unit testing, but will be including in compile
- classpaths or classpaths dealing with runtime information.
- </p>
-
- <p>
- A set of ant tasks use magic dependency information to construct respective
- classpaths and classloaders when executing classic ant tasks such as
- javac, junit, or custom tasks dealing with runtime artifacts (e.g. dynamic plugin
- loading, plugin data generators, deployment meta-data, etc., etc. )
- </p>
-
- <p>
- In the case of RUNTIME dependencies, Magic differntiates between the following
- classloader categories.
- </p>
-
- <ul>
- <li>API</li>
- <li>SPI</li>
- <li>IMPL</li>
- </ul>
-
- <p>
- A dependency declared as RUNTIME enabled with a tag API
- will result in the aggreggation of all of the dependents of the dependant within
- an API path scope. The same principal holds true for SPI and IMPL tags with
- the exception of non-repition of path entires in lower-level path declarations.
- In the impication of the term "lower-level" is realtive to the ordering of classloaders
- resolved from API, SPI and IMPL path declarations. An IMPL classloader has a SPI
- classloader as parent, and in turn an SPI classloader has an API as parent. This
- chaining of classloaders provides the posibility for embedded applications to
- control which classloader is supplied to their runtime sub-systems. For example,
- a plugin executing withing a particular environment can cotrol which classloader is
- used (typically an API or SPI loader) when deployed child units (plugins, components,
- etc.).
- </p>
-
- <p><i>Example of tagged dependencies.</i></p>
-<source><![CDATA[
- <project basedir="../../runtime/merlin/impl">
- <info>
- <group>avalon/merlin</group>
- <name>avalon-merlin-impl</name>
- <version>3.3.0</version>
- </info>
- <dependencies>
- <include key="avalon-framework-api" tag="api"/>
- <include key="avalon-util-lifecycle" tag="api"/>
- <include key="avalon-util-extension-api" tag="spi"/>
- <include key="avalon-merlin-api" tag="spi"/>
- <include key="avalon-repository-api" tag="spi"/>
- <include key="avalon-meta-spi" tag="spi"/>
- <include key="avalon-repository-spi" tag="spi"/>
- <include key="avalon-logging-spi" tag="spi"/>
- <include key="avalon-composition-spi" tag="spi"/>
- <include key="avalon-composition-impl" tag="impl"/>
- <include key="avalon-util-configuration" tag="impl"/>
- <include key="avalon-repository-main" runtime="false"/>
- <include key="avalon-activation-impl"
- build="false" test="false" runtime="false"/>
- </dependencies>
- </project>
+</system>
]]></source>
-
- <p>
- The above classloader chaining strategy delivers
- the potential for applications to take control over the management of resourse
- isolation - a fundamental security principal in component-based-development.
- Secondly, the actual implementation of classloader chaining becomes
- strait-forward once a declarative model is put in place (in fact the
- classloader creation can be totally automated as in the case with the
- magic plugin task and several Avalon repository-enabled systems).
- </p>
</section>
Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/model/navigation.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/model/navigation.xml (original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/model/navigation.xml Sun Jun 20 06:43:18 2004
@@ -23,11 +23,10 @@
<body>
<menu>
- <!--
- <item name="Resource" href="resources.html"/>
- <item name="Project" href="projects.html"/>
- <item name="Plugin" href="plugins.html"/>
- -->
+ <item name="Resources" href="resources.html"/>
+ <item name="Projects" href="projects.html"/>
+ <item name="Plugins" href="plugins.html"/>
+ <item name="Imports" href="imports.html"/>
</menu>
</body>
Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/model/plugins.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/model/plugins.xml (original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/model/plugins.xml Sun Jun 20 06:43:18 2004
@@ -9,7 +9,60 @@
<body>
<section name="Plugins">
<p>
- </p>
+ A plugin is a special type of project that generates a one of
+ dynamically loadable ant tasks that are managed by Magic's plugin
+ task.
+ </p>
+
+ <p><i>Example plugin definition.</i></p>
+
+<source><![CDATA[
+ <plugin basedir="../../runtime/meta/tools">
+ <info>
+ <group>avalon/meta</group>
+ <name>avalon-meta-tools</name>
+ <version>1.4.0</version>
+ </info>
+ <dependencies>
+ <include key="avalon-meta-impl"/>
+ <include key="qdox"/>
+ </dependencies>
+ <tasks>
+ <taskdef name="meta" class="org.apache.avalon.meta.info.ant.MetaTask"/>
+ </tasks>
+ <listeners>
+ <listener class="org.apache.avalon.meta.info.ant.MetaBuildListener"/>
+ </listeners>
+ </plugin>
+]]></source>
+
+ <p>
+ The above plugin defintion demonstrates the two additional features
+ of a plugin over a regual project defintion. Firstly, a plugin can
+ declare the set of task it defines, and secondly, a plugin can declare
+ build listeners. Magic's plugin task will automatically load plugins
+ declared on project defintions.
+ </p>
+ <p>
+ The following project defintion declares a plugin dependency to the
+ above plugin.
+ </p>
+
+<source><![CDATA[
+ <project basedir="../../runtime/test/dynamics">
+ <info>
+ <group>avalon/test</group>
+ <name>avalon-test-dynamics</name>
+ </info>
+ <dependencies>
+ <include key="avalon-framework-impl"/>
+ </dependencies>
+ <plugins>
+ <include key="avalon-meta-tools"/>
+ </plugins>
+ </project>
+]]></source>
+
</section>
</body>
Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/model/projects.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/model/projects.xml (original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/model/projects.xml Sun Jun 20 06:43:18 2004
@@ -8,8 +8,159 @@
<body>
<section name="Projects">
+
+ <p>
+ A project extends the concept of a resource to include a local basedir
+ reference (the root of the project sources relative to the directory
+ containing the index.xml) and a set of dependencies.
+ </p>
+
+ <p><i>
+ Example of two project defintions:
+ </i></p>
+<source><![CDATA[
+ <project basedir="../../runtime/util/env">
+ <info>
+ <group>avalon/util</group>
+ <name>avalon-util-env</name>
+ <version>1.1.1</version>
+ </info>
+ </project>
+
+ <project basedir="../../runtime/util/defaults">
+ <info>
+ <group>avalon/util</group>
+ <name>avalon-util-defaults</name>
+ <version>1.2.1</version>
+ </info>
+ <dependencies>
+ <include key="avalon-util-env"/>
+ </dependencies>
+ </project>
+]]></source>
+
<p>
- </p>
+ In the above example Magic locates the project sources using the
+ declared basedir. The name element is used as the default key
+ that is used when referencing the project - as is the case in the
+ second project defintions dependency declaration.
+ </p>
+
+ <p>
+ Dependendency declarations within a project refernence the name of another
+ another project within the scope of an index.xml file or imported file. As such, a
+ dependency declaration can be resolved to an artifact group, name, version
+ and type, and from this information, a repository based resource can be
+ resolved, or in the case of a project or plugin reference, a target can be
+ built as part of a higher-level build scenario.
+ </p>
+
+ <p>
+ The declaration of dependendency implicitly introduced a dependency
+ by the dependee on the dependent of the dependency. In other words, dependency
+ declarations are transative. Magic provides support for the qualification of
+ transativate dependency inheritance relative to the following three policies:
+ </p>
+
+ <ul>
+ <li>BUILD</li>
+ <li>TEST</li>
+ <li>RUNTIME</li>
+ </ul>
+
+ <p><i>Example of scoped dependency.</i></p>
+
+<source><![CDATA[
+ <project basedir="../../runtime/meta/api">
+ <info>
+ <group>avalon/meta</group>
+ <name>avalon-meta-api</name>
+ <version>1.4.0</version>
+ </info>
+ <dependencies>
+ <include key="avalon-framework-api"/>
+ <include key="avalon-framework-impl" build="false" test="true" runtime="false"/>
+ </dependencies>
+ </project>
+]]></source>
+
+ <p>
+ In the above example the avalon-framework-impl artifact will be included
+ in path constructs for unit testing, but will be including in compile
+ classpaths or classpaths dealing with runtime information.
+ </p>
+
+ <p>
+ A set of ant tasks use magic dependency information to construct respective
+ classpaths and classloaders when executing classic ant tasks such as
+ javac, junit, or custom tasks dealing with runtime artifacts (e.g. dynamic plugin
+ loading, plugin data generators, deployment meta-data, etc., etc. )
+ </p>
+
+ <p>
+ In the case of RUNTIME dependencies, Magic differntiates between the following
+ classloader categories.
+ </p>
+
+ <ul>
+ <li>API</li>
+ <li>SPI</li>
+ <li>IMPL</li>
+ </ul>
+
+ <p>
+ A dependency declared as RUNTIME enabled with a tag API
+ will result in the aggreggation of all of the dependents of the dependant within
+ an API path scope. The same principal holds true for SPI and IMPL tags with
+ the exception of non-repition of path entires in lower-level path declarations.
+ In the impication of the term "lower-level" is realtive to the ordering of classloaders
+ resolved from API, SPI and IMPL path declarations. An IMPL classloader has a SPI
+ classloader as parent, and in turn an SPI classloader has an API as parent. This
+ chaining of classloaders provides the posibility for embedded applications to
+ control which classloader is supplied to their runtime sub-systems. For example,
+ a plugin executing withing a particular environment can cotrol which classloader is
+ used (typically an API or SPI loader) when deployed child units (plugins, components,
+ etc.).
+ </p>
+
+ <p><i>Example of tagged dependencies.</i></p>
+
+<source><![CDATA[
+ <project basedir="../../runtime/merlin/impl">
+ <info>
+ <group>avalon/merlin</group>
+ <name>avalon-merlin-impl</name>
+ <version>3.3.0</version>
+ </info>
+ <dependencies>
+ <include key="avalon-framework-api" tag="api"/>
+ <include key="avalon-util-lifecycle" tag="api"/>
+ <include key="avalon-util-extension-api" tag="spi"/>
+ <include key="avalon-merlin-api" tag="spi"/>
+ <include key="avalon-repository-api" tag="spi"/>
+ <include key="avalon-meta-spi" tag="spi"/>
+ <include key="avalon-repository-spi" tag="spi"/>
+ <include key="avalon-logging-spi" tag="spi"/>
+ <include key="avalon-composition-spi" tag="spi"/>
+ <include key="avalon-composition-impl" tag="impl"/>
+ <include key="avalon-util-configuration" tag="impl"/>
+ <include key="avalon-repository-main" runtime="false"/>
+ <include key="avalon-activation-impl"
+ build="false" test="false" runtime="false"/>
+ </dependencies>
+ </project>
+]]></source>
+
+ <p>
+ The above classloader chaining strategy delivers
+ the potential for applications to take control over the management of resourse
+ isolation - a fundamental security principal in component-based-development.
+ Secondly, the actual implementation of classloader chaining becomes
+ strait-forward once a declarative model is put in place (in fact the
+ classloader creation can be totally automated as in the case with the
+ magic plugin task and several Avalon repository-enabled systems).
+ </p>
+
</section>
</body>
Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/model/resources.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/model/resources.xml (original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/model/resources.xml Sun Jun 20 06:43:18 2004
@@ -8,8 +8,38 @@
<body>
<section name="Resources">
+
<p>
- </p>
+ A resource can be viewed as a logical artifact accessible from
+ a repository cache using group, name and version information.
+ Resources are resolved to file paths using the following convention:
+ </p>
+
+<source><![CDATA[
+ [cache]/[group]/[type]s/[name]-[version].[type]
+]]></source>
+
+ <p><i>Example resource descriptor:</i></p>
+
+<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<system>
+
+ <resource>
+ <info>
+ <group>log4j</group>
+ <name>log4j</name>
+ <version>1.2.8</version>
+ <type>jar</type>
+ </info>
+ </resource>
+
+ ....
+
+</system>
+]]></source>
+
</section>
</body>
Modified: avalon/trunk/central/system/index.xml
==============================================================================
--- avalon/trunk/central/system/index.xml (original)
+++ avalon/trunk/central/system/index.xml Sun Jun 20 06:43:18 2004
@@ -250,7 +250,7 @@
</info>
<dependencies>
<include key="avalon-framework-api"/>
- <include key="avalon-framework-impl" compile="false" test="true" runtime="false"/>
+ <include key="avalon-framework-impl" build="false" test="true" runtime="false"/>
</dependencies>
</project>
@@ -278,7 +278,7 @@
</dependencies>
</project>
- <plugin basedir="../../runtime/meta/tools">
+ <plugin basedir="../../runtime/meta/tools">
<info>
<group>avalon/meta</group>
<name>avalon-meta-tools</name>
@@ -288,17 +288,17 @@
<include key="avalon-meta-impl"/>
<include key="qdox"/>
</dependencies>
- <tasks>
- <taskdef name="meta" class="org.apache.avalon.meta.info.ant.MetaTask"/>
- </tasks>
- <listeners>
- <listener class="org.apache.avalon.meta.info.ant.MetaBuildListener"/>
- </listeners>
- </plugin>
+ <tasks>
+ <taskdef name="meta" class="org.apache.avalon.meta.info.ant.MetaTask"/>
+ </tasks>
+ <listeners>
+ <listener class="org.apache.avalon.meta.info.ant.MetaBuildListener"/>
+ </listeners>
+ </plugin>
- <!--
- Avalon Test.
- -->
+ <!--
+ Avalon Test.
+ -->
<project basedir="../../runtime/test/dynamics">
<info>
lmpx.com only provides a reader for public news (NNTP) servers. It is not
affiliated with the servers or forums shown here and is not responsible for
the content of articles, which is written by their respective authors.