avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mcconn...@apache.org
Subject svn commit: rev 21507 - in avalon/trunk/central: site site/src/xdocs/central/tools/magic/model system
Date Sun, 20 Jun 2004 13:43:19 GMT
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="dev@avalon.apache.org">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>

---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org


Mime
View raw message