avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mcconn...@apache.org
Subject svn commit: rev 21506 - in avalon/trunk/central/site/src/xdocs: central/tools central/tools/magic central/tools/magic/model products/runtime
Date Sun, 20 Jun 2004 13:05:05 GMT
Author: mcconnell
Date: Sun Jun 20 06:05:04 2004
New Revision: 21506

Modified:
   avalon/trunk/central/site/src/xdocs/central/tools/magic/index.xml
   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/navigation.xml
   avalon/trunk/central/site/src/xdocs/central/tools/navigation.xml
   avalon/trunk/central/site/src/xdocs/products/runtime/index.xml
Log:
get magic docs into something semi-reasonable

Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/index.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/index.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/index.xml	Sun Jun 20 06:05:04
2004
@@ -18,9 +18,9 @@
       <p>
       Avalon Magic is a build system based on Apache
       <a href="http://ant.apache.org">Ant</a>.  It provides 
-      a project model abstraction layer enabling centralized version
-      and dependency management, build task automation, and dynamic 
-      plugin management.
+      a <a href="model.index.html">project model</a> abstraction 
+      layer enabling centralized version and dependency management, 
+      build task automation, and dynamic plugin management.
       </p>
 
     </section>

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:05:04
2004
@@ -11,41 +11,86 @@
 
       <p>
       The notion of a POM (Project Object Model) is familiar to 
-      Maven users.  Magic extends this concepts through a central 
-      index of projects, unique project keys, and complete support
-      for transitive inheritance of dependency information.
+      Maven users.  Magic extends this concepts through complete support
+      for transitive inheritance of dependency information together with
+      build, test and runtime scopes.
       </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.  
+      </p>
+
       <p>
-      An example of a Magic project defintion:
+      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[
-<project basedir="../../runtime/framework/impl">
-  <info>
-    <group>avalon/framework</group>
-    <name>avalon-framework-impl</name>
-    <version>4.2.0</version>
-  </info>
-  <dependencies>
-    <include key="avalon-framework-api"/>
-  </dependencies>
-</project>
+ [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>
+
+      <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>
+
+      <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>
-      The above XML fragment is taken from a index.xml file.  The index.xml 
-      contains the resource, project, and plugin defintions for a suite of 
-      interconnected systems.  Within magic, plugins and projects are derived
-      from the notion of a resouce.  A resource can be viewed as a logical 
-      artifact accessible from a repository cache using group, name and version 
-      information.  A project extends this concept to include a local basedir 
-      refernce (the root of the project directory) and a set of dependencies.
-      Plugins extend the concept of project to include the delcaration of 
-      the Ant tasks they provide to the classic ant build environment. 
+      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 refernce the name of another 
-      another project within the scope of an index.xml file.  As such, a 
+      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 
@@ -56,16 +101,37 @@
       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 four policies: 
+      transativate dependency inheritance relative to the following three policies: 
       </p>
 
       <ul>
-        <li>ANY</li>
         <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 
@@ -79,7 +145,6 @@
       </p>
 
       <ul>
-        <li>ANY</li>
         <li>API</li>
         <li>SPI</li>
         <li>IMPL</li>
@@ -100,12 +165,42 @@
       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>
-      While technically duanting, the above classloader chaining strategy delivers
+      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.
+      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:05:04 2004
@@ -22,11 +22,12 @@
  <title>Apache Avalon Central</title>
 
  <body>
-    <menu>
-      <item name="Home" href="home.html"/>
-      <item name="Resources" href="resources.html"/>
-      <item name="Projects" href="projects.html"/>
-      <item name="Plugins" href="plugins.html"/>
+    <menu>
+      <!--
+      <item name="Resource" href="resources.html"/>
+      <item name="Project" href="projects.html"/>
+      <item name="Plugin" href="plugins.html"/>
+      -->
     </menu>
  </body>
 

Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/navigation.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/navigation.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/navigation.xml	Sun Jun 20 06:05:04
2004
@@ -23,9 +23,11 @@
 
  <body>
     <menu>
-      <item name="Model" href="model/index.html"/>
+      <item name="System Model" href="model/index.html"/>
+      <!--
       <item name="Targets" href="targets/index.html"/>
       <item name="Tasks" href="tasks/index.html"/>
+      -->
     </menu>
  </body>
 

Modified: avalon/trunk/central/site/src/xdocs/central/tools/navigation.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/navigation.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/navigation.xml	Sun Jun 20 06:05:04 2004
@@ -24,8 +24,10 @@
  <body>
     <menu>
       <item name="Magic" href="magic/index.html"/>
+      <!--
       <item name="Plugins" href="plugins/index.html"/>
       <item name="Legacy" href="maven/index.html"/>
+      -->
     </menu>
  </body>
 

Modified: avalon/trunk/central/site/src/xdocs/products/runtime/index.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/products/runtime/index.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/products/runtime/index.xml	Sun Jun 20 06:05:04 2004
@@ -12,59 +12,27 @@
 The Merlin project deals with the general area of service and component management.  The
Merlin system is a container that provides comprehensive support for the management of complex
component based systems based on an underlying meta-model that facilitates automated assembly
and deployment of components.
     </p>
 
-    </section>
+    <p>
+Merlin aims to simplify the process of managing component-based systems.  It achieves this
objective through delivery of functionality supporting automated component assembly and deployment
combined with strong support for the isolatiion of  implementation from the service that a
component provides. Applications are implemented through component composition. In turn, applications
can be exposed as simple components and used by other components as building blocks in other
applications.
+    </p>
 
-    <section name="Purpose">
-      <subsection name="Simplification">
-        <p>
-Merlin aims to simplify the process of managing component-based systems.  It achieves this
objective through delivery of functionality supporting automated component assembly and deployment.
-        </p>
-      </subsection>
-      <subsection name="Isolation">
-        <p>
-Merlin aims to provide a framework for isolating an application implementation from the service
that the application provides. Applications are implemented through component composition.
In turn, applications can be exposed as simple components and used by other components in
building other applications.
-        </p>
-      </subsection>
-      <subsection name="Distribution">
-        <p>
-A goal of the Merlin project is to provide distribution of services established by system
to other Merlin systems across a distributed network environment.
-        </p>
-      </subsection>
-    </section>
-
-    <section name="Features and Benefits">
-      <subsection name="Composite Component Management">
+    <subsection name="Composite Component Management">
         <p>
 Merlin provides support for the packaging and deployment of composite components with a structure
called a Block.  A block represents the association of resources to a containment hierarchy
within which components are managed.  In addition, a block enables the separation of a component
assembly (the composite implementation) from the set of services published by the block.
         </p>
-      </subsection>
-      <subsection name="Cascading Containers">
         <p>
-The Merlin system provides support for <strong>cascading containers</strong>.
This model enables component assemblers to (among other things) associate jar files under
a protected scope where each container is associated with its own classloader.
+Merlin will handle resolution of service dependencies for components by looking for explicitly
declared components commencing within the local container, and working progressively up the
container hierarchy.  If no explicit solutions are resolved, Merlin will attempt to build
a packaged or implicit solution based on component types declared in the classloader hierachy.
 
         </p>
-      </subsection>
-      <subsection name="Automated Assembly">
-        <p>
-Merlin will handle resolution of service dependencies for components by looking for explicitly
declared components commencing within the local container, and working progressively up the
container hierarchy.  If 
-no explicit solutions are resolved, Merlin will attempt to build a packaged or implicit solution
based on component types declared in the classloader hierachy.  
-        </p>
-      </subsection>
-      <subsection name="Deployment Engine">
         <p>
 Underlying the Merlin system is a runtime deployment engine that provides support for the
orderly establishment of simple and composite components.  The deployment engine takes care
of component instantiation, lifecycle processing, and component decommissioning.
         </p>
       </subsection>
-      <subsection name="Lifestyle Management">
-        <p>
-Merlin provides support for different component instantiation policies.  These policies are
referred to as lifestyles. Examples of lifestyle include 'singleton', 'per-thread', 'pooled'
and 'transient'.
-        </p>
-      </subsection>
       <subsection name="Lifecycle Management">
         <p>
 Merlin provides support for constructor based injection of lifecycle artifacts, or optional
phased delivery under which a component is processed through a series of lifecycle stages.
 Lifecycle processing involves the execution of a series of stages such as associating a logging
channel, applying a configuration or component parameters, setting the runtime context, supplying
dependent services, initialization, startup, shutdown and disposal.  Within the Merlin system,
lifecycle stages can be extended or modified through association of other components that
provide lifecycle support.  Merlin distinguishes these services as deployment dependencies
as distinct from classic runtime dependencies.
         </p>
       </subsection>
-    <subsection name="Seperating Concerns">
+      <subsection name="Seperating Concerns">
 <p>
 Every developer that has written a complex component based application has had to deal with
container-side programming. Given normal commercial pressures, it too easy to write code into
your application that has assumptions built into it concerning the requirements of the target
components.
 </p>
@@ -92,7 +60,7 @@
 </source>
 
 <p>
-The above container-side code is making a lot of assumptions about the component it is deploying.
 Firstly, it knows that the component is log enabled, contextualizable, and initializable.
This is problematic because it means that the container-side code is dependent on the component
implementation.  If the component were to be changed so that it supported the configurable
semantics, there container-side code needs to be updated as well.  This is dangerous because
it is easy for container-side to get out-of-sync with the component implementation - for example,
the container side code to some extent is dependent on a component properly checking if it
has been configured or not. A deeper and more important issue concerns component assembly
- if a component  is refactored to use other components, then the container-side code become
much more complex and much more closely tied to the set of components that make up the assembly.
+The above container-side code is making a lot of assumptions about the component it is deploying.
 Firstly, it knows that the component is log enabled, contextualizable, and initializable.
This is problematic because it means that the container-side code is dependent on the component
implementation.  If the component were to be changed so that it supported the configurable
semantics, there container-side code needs to be updated as well.  This is dangerous because
it is easy for container-side to get out-of-sync with the component implementation - for example,
the container-side code to some extent is dependent on a component properly checking if it
has been configured or not. A deeper and more important issue concerns component assembly
- if a component  is refactored to use other components, then the container-side code become
much more complex and much more closely tied to the set of components that make up the assembly.
 </p>
 
 <p>

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


Mime
View raw message