You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by bl...@apache.org on 2003/05/30 21:21:31 UTC
cvs commit: avalon-excalibur/fortress/src/xdocs using-meta-info.xml getting-started.xml index.xml book.xml features.xml
bloritsch 2003/05/30 12:21:31
Modified: fortress/src/xdocs getting-started.xml index.xml book.xml
features.xml
Added: fortress/src/xdocs using-meta-info.xml
Log:
Update the docs
Revision Changes Path
1.6 +2 -2 avalon-excalibur/fortress/src/xdocs/getting-started.xml
Index: getting-started.xml
===================================================================
RCS file: /home/cvs/avalon-excalibur/fortress/src/xdocs/getting-started.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- getting-started.xml 14 May 2003 15:54:47 -0000 1.5
+++ getting-started.xml 30 May 2003 19:21:30 -0000 1.6
@@ -25,7 +25,7 @@
for information on CVS).</li>
<li>Check out the modules avalon, avalon-excalibur,
avalon-logkit and jakarta-site</li>
- <li>Use ant to build the various projects: avalon, logkit, excalibur fortress.
+ <li>Use ant to build the various projects: avalon, logkit, excalibur fortress.
If something goes wrong, run ant in verbose mode using the -v option and
send the output to the avalon-user mailing list. Someone'll help you out.
</li>
1.10 +3 -10 avalon-excalibur/fortress/src/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/avalon-excalibur/fortress/src/xdocs/index.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- index.xml 7 Feb 2003 17:56:31 -0000 1.9
+++ index.xml 30 May 2003 19:21:30 -0000 1.10
@@ -10,13 +10,6 @@
</header>
<body>
<section><title>Introduction</title>
- <warning>
- This package is under development, and the API is not
- guaranteed to be the same when it is ready for release.
- You can find this in the excalibur-fortress-1.0.jar file if you want
- to play with it. Do not blame us if the next release of
- Excalibur breaks your code if you use this package.
- </warning>
<p>
Fortress contains a framework to help you create your own
avalon containers. It boasts asynchronous management of your
@@ -25,7 +18,7 @@
servlet engines.
</p>
</section>
- <section><title>downloads</title>
+ <section><title>Downloads</title>
<p>
When fortress is released, binaries will be made available. For
now, you can try downloading a nightly build from
@@ -35,7 +28,7 @@
Other than that, the only way to get fortress is by using cvs.
</p>
</section>
- <section><title>available documentation</title>
+ <section><title>Available Documentation</title>
<ul>
<li>The primary source of documentation is the fortress website, available
at
1.10 +1 -0 avalon-excalibur/fortress/src/xdocs/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/avalon-excalibur/fortress/src/xdocs/book.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- book.xml 14 May 2003 15:54:47 -0000 1.9
+++ book.xml 30 May 2003 19:21:30 -0000 1.10
@@ -10,6 +10,7 @@
<menu-item href="index.html" label="Overview"/>
<menu-item href="features.html" label="Features"/>
<menu-item href="getting-started.html" label="Getting Started"/>
+ <menu-item href="using-meta-info.html" lanel="Using Meta Info"/>
<menu-item href="http://jakarta.apache.org/builds/avalon-excalibur/release" label="Download"/>
</menu>
1.6 +3 -1 avalon-excalibur/fortress/src/xdocs/features.xml
Index: features.xml
===================================================================
RCS file: /home/cvs/avalon-excalibur/fortress/src/xdocs/features.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- features.xml 14 May 2003 15:54:47 -0000 1.5
+++ features.xml 30 May 2003 19:21:30 -0000 1.6
@@ -63,6 +63,8 @@
and generates the meta info files which are then read at
runtime. It makes it a whole lot easier to manage critical
aspects like lifestyle and which classes represent components.
+ <link href="using-meta-info.html">You can find out more about it
+ here.</link>
</p>
</section>
</section>
1.1 avalon-excalibur/fortress/src/xdocs/using-meta-info.xml
Index: using-meta-info.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>Excalibur Fortress - Using Meta Info</title>
<authors>
<person name="The Avalon Documentation Team" email="dev@avalon.apache.org"/>
</authors>
</header>
<body>
<section>
<title>What is Meta Information?</title>
<p>
Meta Information is information about your components. The information that
Fortress needs to properly manage your components is fairly small. It needs to
know which classes are components, which services that component implements, what
its dependencies are, and what type of lifestyle the component was designed for.
Using this information, Fortress can determine if there are some circular
dependencies as well as manage other aspects of your component.
</p>
<p>
Your container has to find the meta information in some way. If you are used
to the Excalibur Component Manager (ECM), then you supplied the meta information
based on a "roles" file and certain marker interfaces that your component
implemented. There are several drawbacks to this approach, some of which include
inheritance of conflicting meta information and having to manage your information
in separate files.
</p>
<p>
Fortress has adopted a practice that is available in both Phoenix and Merlin to
make managing meta information a breeze. It is the use of JavaDoc tags to mark the
meta information right with the source code itself. This scheme works much better,
and unlocks some features to you. One of them is for Fortress to tell you that you
have a circular dependency (some components that require each other to work) at
initialization time instead of at run time.
</p>
</section>
<section>
<title>How does the Meta Info Tags Look?</title>
<p>
The best way to demonstrate how these tags look and behave is to show some sample
code. Fortress follows the AMTAGS proposal on the WIKI, and also supports a couple
extra tags. Specifically, the set of tags that Fortress supports are
"avalon.dependency", "avalon.service", "x-avalon.info", "x-avalon.lifestyle",
"avalon.component", "fortress.name", "fortress.handler". The two Fortress specific
tags are recognized, but are not encouraged for routine use.
</p>
<p>
Everything except for the "avalon.dependency" must be specified in the component's
class JavaDoc. Below is a snippet:
</p>
<source>
<![CDATA[
/**
* My component implementation.
*
* @avalon.component
* @avalon.service type="RoleInterface"
* @x-avalon.info name="my-component"
* @x-avalon.lifestyle type="pooled"
*/
public class MyComponent implements RoleInterface
{
// ....
}
]]>
</source>
<p>
The "avalon.component" is a marker tag, and it is required to mark a class as a
component. You must have one or more "avalon.service" tags (one per interface
type). The value in the "type" attribute must be a resolvable class name. If the
type of "RoleInterface" is in the same package, or in one of the imports, then all
is well. The "x-avalon.info" tag is used to provide a configuration name for the
component. In this case, the configuration name is "my-component". If you do not
supply this tag, Fortress will create one for you based on the class name of the
component. It is best if you supply your own. The "x-avalon.lifestyle" tag is
used to choose how this component is managed.
</p>
<p>
Dependencies are declared in the <code>service()</code> method for the component.
The component needs to implement the Serviceable interface. Fortress knows how
to look at the code hierarchy to collect all the dependencies as long as you have
all your source code available. The dependency declarations look like this:
</p>
<source>
<![CDATA[
/**
* Get all the dependencies.
*
* @avalon.dependency type="OtherService"
* @avalon.dependency type="Foo"
*/
public void service( ServiceManager manager )
{
// ...
}
]]>
</source>
<p>
All the "avalon.dependency" entries are collected by the same rules as the
"avalon.service" entries. In other words, the "type" attribute is evaluated
based on the same rules as your Java compiler evaluates them. Fortress will
take care of resolving them properly.
</p>
</section>
<section>
<title>Collecting the Meta Information</title>
<p>
Fortress provides an ANT task to collect all your meta information and generate
the extra files that your JAR files need to have for Fortress to use the meta
information at run time. You include the ANT task in your build.xml file like
this:
</p>
<source>
<![CDATA[
<project>
<!-- ... -->
<taskdef name="collect-metainfo"
classname="org.apache.avalon.fortress.tools.ComponentMetaInfoCollector">
<classpath refid="tools.class.path"/>
</taskdef>
<target name="compile" depends="jar-tools" description="Compiles the source code">
<mkdir dir="${build.classes}"/>
<!-- Compile all classes excluding the tests. -->
<javac srcdir="${java.dir}"
destdir="${build.classes}">
<classpath>
<path refid="tools.class.path"/>
<pathelement location="${loader.classes}"/>
</classpath>
<include name="**/*.java"/>
</javac>
<collect-metainfo destdir="${build.classes}">
<fileset dir="${java.dir}"/>
</collect-metainfo>
</target>
<!-- ... -->
</project>
]]>
</source>
<p>
Once you include all the generated files in your JAR for the components, you
don't have to do anything more than include the JAR in your classpath for Fortress.
Everything else is taken care of.
</p>
</section>
<section>
<title>The x-avalon.lifestyle Tag</title>
<p>
The "x-avalon.lifestyle" tag needs a little further explanation. It can have one
of four values in the "type" attribute:
</p>
<ul>
<li><strong>singleton</strong> One instance of the component shared with all clients.</li>
<li><strong>thread</strong> One instance of the component per thread of execution.</li>
<li><strong>pooled</strong> One instance of the component per request, with instances reused from a pool.</li>
<li><strong>transient</strong> One instance of the component per request, with instances destroyed on release.</li>
</ul>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org