You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by mc...@apache.org on 2004/06/20 15:05:05 UTC
svn commit: rev 21506 - in avalon/trunk/central/site/src/xdocs: central/tools central/tools/magic central/tools/magic/model products/runtime
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