You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm@excalibur.apache.org by le...@apache.org on 2004/06/23 11:32:50 UTC
svn commit: rev 21598 - in excalibur/trunk/site: . xdocs xdocs/event xdocs/fortress xdocs/lifecycle
Author: leosimons
Date: Wed Jun 23 02:32:50 2004
New Revision: 21598
Added:
excalibur/trunk/site/xdocs/jira.xml
excalibur/trunk/site/xdocs/svn.xml
Modified:
excalibur/trunk/site/project.properties
excalibur/trunk/site/project.xml
excalibur/trunk/site/xdocs/component.xml
excalibur/trunk/site/xdocs/configuration.xml
excalibur/trunk/site/xdocs/event/command-howto.xml
excalibur/trunk/site/xdocs/event/command.xml
excalibur/trunk/site/xdocs/event/cpuparser-howto.xml
excalibur/trunk/site/xdocs/event/event-howto.xml
excalibur/trunk/site/xdocs/event/event.xml
excalibur/trunk/site/xdocs/event/index.xml
excalibur/trunk/site/xdocs/event/mpool-howto.xml
excalibur/trunk/site/xdocs/event/mpool.xml
excalibur/trunk/site/xdocs/event/navigation.xml
excalibur/trunk/site/xdocs/event/util-howto.xml
excalibur/trunk/site/xdocs/event/util.xml
excalibur/trunk/site/xdocs/fortress/cli.xml
excalibur/trunk/site/xdocs/fortress/design-notes.xml
excalibur/trunk/site/xdocs/fortress/features.xml
excalibur/trunk/site/xdocs/fortress/getting-started.xml
excalibur/trunk/site/xdocs/fortress/index.xml
excalibur/trunk/site/xdocs/fortress/lifecycle-extensions.xml
excalibur/trunk/site/xdocs/fortress/navigation.xml
excalibur/trunk/site/xdocs/fortress/servlet.xml
excalibur/trunk/site/xdocs/fortress/swing.xml
excalibur/trunk/site/xdocs/fortress/using-meta-info.xml
excalibur/trunk/site/xdocs/i18n.xml
excalibur/trunk/site/xdocs/index.xml
excalibur/trunk/site/xdocs/lifecycle/extension.xml
excalibur/trunk/site/xdocs/lifecycle/fortress.xml
excalibur/trunk/site/xdocs/lifecycle/index.xml
excalibur/trunk/site/xdocs/lifecycle/interfaces.xml
excalibur/trunk/site/xdocs/lifecycle/merlin.xml
excalibur/trunk/site/xdocs/lifecycle/navigation.xml
excalibur/trunk/site/xdocs/logger.xml
excalibur/trunk/site/xdocs/navigation.xml
excalibur/trunk/site/xdocs/no-docs-available.xml
excalibur/trunk/site/xdocs/sourceresolve-index.xml
excalibur/trunk/site/xdocs/store-index.xml
excalibur/trunk/site/xdocs/store-janitor.xml
excalibur/trunk/site/xdocs/store-mru.xml
excalibur/trunk/site/xdocs/thread.xml
excalibur/trunk/site/xdocs/usage.xml
Log:
A lot of work on a mavenized website
Modified: excalibur/trunk/site/project.properties
==============================================================================
--- excalibur/trunk/site/project.properties (original)
+++ excalibur/trunk/site/project.properties Wed Jun 23 02:32:50 2004
@@ -19,3 +19,5 @@
# gump integration
project.name = excalibur-site
+
+maven.xdoc.poweredby.image =
Modified: excalibur/trunk/site/project.xml
==============================================================================
--- excalibur/trunk/site/project.xml (original)
+++ excalibur/trunk/site/project.xml Wed Jun 23 02:32:50 2004
@@ -18,9 +18,9 @@
<project>
<extend>${basedir}/../buildsystem/project-common.xml</extend>
- <name>Excalibur Site</name>
+ <name>Apache Excalibur</name>
<id>excalibur-docs</id>
- <shortDescription>Excalibur Site</shortDescription>
- <description>Excalibur Site</description>
+ <shortDescription>Apache Excalibur</shortDescription>
+ <description>Apache Excalibur</description>
</project>
Modified: excalibur/trunk/site/xdocs/component.xml
==============================================================================
--- excalibur/trunk/site/xdocs/component.xml (original)
+++ excalibur/trunk/site/xdocs/component.xml Wed Jun 23 02:32:50 2004
@@ -1,59 +1,75 @@
<?xml version="1.0"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
<properties>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- <title>Excalibur i18n</title>
+ <title>ECM</title>
</properties>
<body>
<section name="Excalibur ECM (DEPRICATED)">
- <p>
- Due to a number of issues in ECM, not the least of which is a
- simplistic and convoluted design, it has been deprecated in
- favor of Fortress or Phoenix. Fortress has been designed with
- ECM users in mind, so it provides a number of goodies to make
- it easier to migrate forward. This project will be maintained
- for bug fixes only.
- </p>
- <subsection name="Introduction">
- <p>
- This project contains utilities for managing components. ECM
- is what we call an "avalon container", though it is somewhat
- different in architecture to newer developments like phoenix
- and fortress. Our intend is to someday completely replace ECM
- with fortress.
- In particular, this package contains the
- ExcaliburComponentManager, usually abbreviated to ECM.
- </p>
- </subsection>
- <subsection name="Automated Component Management">
- <p>
- The <code>org.apache.avalon.excalibur.component</code> package
- in Excalibur will allow you to manage components specified in
- a configuration file. The beauty of this approach is that the
- ComponentManagers and ComponentSelectors become the Container
- and automagically maintain your Component's lifecycle.
- </p>
- <p>
- The Excalibur Component Management infrastructure uses a
- RoleManager to help your configuration files remain readable.
- All classes are instantiated using the current thread's
- ContextClassLoader--unless you pass a different one in the
- constructor.
- </p>
- </subsection>
- <subsection name="The Developing with Avalon paper">
- <p>
- ECM is well-documented in the Developing with Avalon
- whitepaper available
- <a href="http://avalon.apache.org/developing/">here</a>.
- </p>
- </subsection>
-
- </section>
- </body>
-</document>
+ <p>
+ Due to a number of issues in ECM, not the least of which is a
+ simplistic and convoluted design, it has been deprecated in
+ favor of Fortress or Phoenix. Fortress has been designed with
+ ECM users in mind, so it provides a number of goodies to make
+ it easier to migrate forward. This project will be maintained
+ for bug fixes only.
+ </p>
+ <subsection name="Introduction">
+ <p>
+ This project contains utilities for managing components. ECM
+ is what we call an "avalon container", though it is somewhat
+ different in architecture to newer developments like phoenix
+ and fortress. Our intend is to someday completely replace ECM
+ with fortress.
+ In particular, this package contains the
+ ExcaliburComponentManager, usually abbreviated to ECM.
+ </p>
+ </subsection>
+ <subsection name="Automated Component Management">
+ <p>
+ The
+ <code>org.apache.avalon.excalibur.component</code> package
+ in Excalibur will allow you to manage components specified in
+ a configuration file. The beauty of this approach is that the
+ ComponentManagers and ComponentSelectors become the Container
+ and automagically maintain your Component's lifecycle.
+ </p>
+ <p>
+ The Excalibur Component Management infrastructure uses a
+ RoleManager to help your configuration files remain readable.
+ All classes are instantiated using the current thread's
+ ContextClassLoader--unless you pass a different one in the
+ constructor.
+ </p>
+ </subsection>
+ <subsection name="The Developing with Avalon paper">
+ <p>
+ ECM is well-documented in the Developing with Avalon
+ whitepaper available
+ <a href="http://avalon.apache.org/developing/">here</a>.
+ </p>
+ </subsection>
+
+ </section>
+ </body>
+</document>
Modified: excalibur/trunk/site/xdocs/configuration.xml
==============================================================================
--- excalibur/trunk/site/xdocs/configuration.xml (original)
+++ excalibur/trunk/site/xdocs/configuration.xml Wed Jun 23 02:32:50 2004
@@ -1,25 +1,25 @@
<?xml version="1.0"?>
-<!--
- Copyright 2004 The Apache Software Foundation
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied.
-
- See the License for the specific language governing permissions and
- limitations under the License.
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
-->
<document>
<properties>
- <author email="mcconnell@apache.org">Stephen McConnell</author>
- <title>Excalibur Configuration</title>
+ <title>Configuration</title>
</properties>
<body>
@@ -27,15 +27,15 @@
<section name="Excalibur Configuration">
<subsection name="Overview">
-<p>
+ <p>
The Configuration package contains extensions to the Avalon Framework
supporting configuration management.
-</p>
+ </p>
</subsection>
<subsection name="CascadingConfiguration">
-<p>
+ <p>
Provides support for the creation of a base and default parent relationship
between two configuration instances. This is helpful when you have a default
configuration together with a configuration that contains overriding values.
@@ -45,32 +45,32 @@
implementation will attempt to resolve the invocation against the parent
configuration. Both base and parent configuration reference can be classic or
cascading enabling the creation of complex configuration graphs.
-</p>
+ </p>
</subsection>
<subsection name="ConfigurationUtil">
-<p>
+ <p>
Provides a static list operation that is helpful in debugging. The list
operation generates a simple string representation of a configuration.
-</p>
+ </p>
</subsection>
<subsection name="ConfigurationMerger">
-<p>
+ <p>
Similar to the CascadingConfiguration in that it takes two Configuration's and
makes one. The ConfigurationMerger can take a "layer" and a "base" and merge
the layer with the base. The ConfigurationMerger goes a step farther than the
CascadingConfiguration in that it provides a consistent view of
Configuration.getChildren() based off of meta-attributes that can exist in the
layer.
-</p>
+ </p>
</subsection>
<subsection name="ConfigurationSplitter">
-<p>
+ <p>
Given a Configuration and a "base", generate the "layer" that when passed to
the ConfigurationMerger will yield the original Configuration.
-</p>
+ </p>
</subsection>
</section>
Modified: excalibur/trunk/site/xdocs/event/command-howto.xml
==============================================================================
--- excalibur/trunk/site/xdocs/event/command-howto.xml (original)
+++ excalibur/trunk/site/xdocs/event/command-howto.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,13 +17,12 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Excalibur Event - How To Use Command</title>
- </properties>
- <body>
- <section name="Setting Up The Command Manager" >
- <p>
+ <properties>
+ <title>Event - How To Use Command</title>
+ </properties>
+ <body>
+ <section name="Setting Up The Command Manager">
+ <p>
Using Command is a two step process. You have to set it up,
and then you can send Commands to it. Because Command uses
an Event Pipeline to move the Commands through the Queue to
@@ -30,9 +31,9 @@
TPC stands for "Thread Per CPU". The TPCThreadManager allows
you to customize its behaviour by passing in some parameters.
The code snippet below is fairly typical:
- </p>
- <source>
-<![CDATA[
+ </p>
+ <source>
+ <![CDATA[
ThreadManager threadManager = new TPCThreadManager();
threadManager.enableLogging( getLogger().getChildLogger("threadmanager") );
Parameters params = new Parameters();
@@ -41,55 +42,57 @@
params.setParameter( "block-timeout", "250" );
threadManager.parameterize( params );
threadManager.initialize();
-]]>
- </source>
- <p>
+ ]]>
+ </source>
+ <p>
We create a Threadmanager, pass in the Logger, pass in the Parameters,
and then initialize it. The table below provides all the parameter names
that TPCThreadManager recognizes:
- </p>
- <table>
- <tr>
- <th>Name</th> <th>Description</th> <th>Default Value</th>
- </tr>
- <tr>
- <td>processors</td>
- <td>Number of processors (autodetected if less than one)</td>
- <td>Results from SystemUtil.numProcessors()</td>
- </tr>
- <tr>
- <td>threads-per-processor</td>
- <td>Threads per processor to use (Rewritten to 1 if less than one)</td>
- <td>1</td>
- </tr>
- <tr>
- <td>sleep-time</td>
- <td>Time (in milliseconds) to wait between queue pipeline processing runs</td>
- <td>1000</td>
- </tr>
- <tr>
- <td>block-timeout</td>
- <td>Time (in milliseconds) to wait for a thread to process a pipeline</td>
- <td>1000</td>
- </tr>
- </table>
- <p>
+ </p>
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Description</th>
+ <th>Default Value</th>
+ </tr>
+ <tr>
+ <td>processors</td>
+ <td>Number of processors (autodetected if less than one)</td>
+ <td>Results from SystemUtil.numProcessors()</td>
+ </tr>
+ <tr>
+ <td>threads-per-processor</td>
+ <td>Threads per processor to use (Rewritten to 1 if less than one)</td>
+ <td>1</td>
+ </tr>
+ <tr>
+ <td>sleep-time</td>
+ <td>Time (in milliseconds) to wait between queue pipeline processing runs</td>
+ <td>1000</td>
+ </tr>
+ <tr>
+ <td>block-timeout</td>
+ <td>Time (in milliseconds) to wait for a thread to process a pipeline</td>
+ <td>1000</td>
+ </tr>
+ </table>
+ <p>
Once the ThreadManager is set up and used, we can set up the CommandManager.
We do this by instantiating the CommandManager, and registering it with the
ThreadManager. Below is a code snippet showing how that is done:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
// Create the CommandManager
CommandManager commandManager = new CommandManager();
// Register it with the ThreadManager
threadManager.register( commandManager );
- ]]>
- </source>
- </section>
- <section name="Running Commands" >
- <p>
+ ]]>
+ </source>
+ </section>
+ <section name="Running Commands">
+ <p>
There are three Command interfaces: Command, DelayedCommand, and RepeatedCommand.
Each one of those has a special purpose. The Command interface exposes the method
that the CommandManager will execute named, oddly enough, "execute()". The
@@ -99,14 +102,14 @@
interface is used to determine how long and how many times the Command will
be executed. Below is a code snippet showing how to send Commands to the
CommandManager:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
Sink commandSink = commandManager.getCommandSink();
commandSink.enqueue( new MySpecialCommand() );
- ]]>
- </source>
- <p>
+ ]]>
+ </source>
+ <p>
It's not that hard to use the CommandManager. Writing a Command is as easy as
implementing the java.lang.Runnable interface. There are two distinct advantages
to using the Command infrastructure: your Command can throw exceptions and it
@@ -117,9 +120,9 @@
running a long time without tying up system resources the whole time, then
write a RepeatedCommand. Below is an example RepeatedCommand that is used
for the DefaultPoolManager in MPool:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
/**
* This is run every 10 seconds, starting after a 10 second delay.
* It gives the appearance of being a long running thread, but it
@@ -181,8 +184,8 @@
}
}
}
- ]]>
- </source>
- </section>
- </body>
+ ]]>
+ </source>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/event/command.xml
==============================================================================
--- excalibur/trunk/site/xdocs/event/command.xml (original)
+++ excalibur/trunk/site/xdocs/event/command.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,13 +17,12 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Excalibur Event - Command</title>
- </properties>
- <body>
- <section name="Why Command Was Created" >
- <p>
+ <properties>
+ <title>Event - Command</title>
+ </properties>
+ <body>
+ <section name="Why Command Was Created">
+ <p>
Command was created as a way to offload management functions
to a CommandManager which would execute the functions in the
background. The benefits of this approach are tremendous
@@ -31,10 +32,10 @@
management), and you reduce the time for the critical path
to execute. The critical path is the part of your code that
actually solves your problems as opposed to managing resources.
- </p>
- </section>
- <section name="When To Use Command" >
- <p>
+ </p>
+ </section>
+ <section name="When To Use Command">
+ <p>
A better question might be "when should I not to use Command?".
The complexity of the thread management and command timing is
completely hidden from you. That makes Command as easy to
@@ -43,19 +44,20 @@
request loads it is definitely easier to design your system
the old fashioned way. If you do expect your application to
work under heavy load, you will find Command to be indespensible.
- </p>
- </section>
- <section name="Core Concepts" >
- <p>
- Command is built on top of <link href="event.html">Event</link>.
+ </p>
+ </section>
+ <section name="Core Concepts">
+ <p>
+ Command is built on top of
+ <link href="event.html">Event</link>.
That means we use a Command Sink to enqueue Commands for the
CommandManager to process. The CommandManager then executes the
commands as they are pulled off of the queue. A Command can be
a repeating command, so CommandManager will automatically requeue
that command for you.
- </p>
- <section name="Command" >
- <p>
+ </p>
+ <section name="Command">
+ <p>
A Command is an object that performs any function you desire.
You create it by simply implementing the Command interface.
There are three types of commands: a generic command that is
@@ -63,24 +65,24 @@
that is executed after a specified period of time, and a
repeated command that is executed again and again until the
Command Manager is shut down.
- </p>
- </section>
- <section name="Command Manager" >
- <p>
+ </p>
+ </section>
+ <section name="Command Manager">
+ <p>
The Command Manager takes care of processing both Commands
and Signals. With Signals, it will notify the registered
Signal listener. With commands it schedules their execution
in a background thread.
- </p>
- </section>
- <section name="Thread Manager" >
- <p>
+ </p>
+ </section>
+ <section name="Thread Manager">
+ <p>
A Thread Manager takes care of the threading policy for the
Command Manager. It manages the thread pool size, and how
often the Event Pipeline (the path from a Source to an
EventHandler) is checked.
- </p>
- </section>
- </section>
- </body>
+ </p>
+ </section>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/event/cpuparser-howto.xml
==============================================================================
--- excalibur/trunk/site/xdocs/event/cpuparser-howto.xml (original)
+++ excalibur/trunk/site/xdocs/event/cpuparser-howto.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,33 +17,34 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Excalibur Event - How To Extend System Util</title>
- </properties>
- <body>
- <section name="System Util Design" >
- <p>
+ <properties>
+ <title>Event - How To Extend System Util</title>
+ </properties>
+ <body>
+ <section name="System Util Design">
+ <p>
SystemUtil determines which CPUParser it needs by examining
- the results from <code>System.getProperty( "os.name" )</code>.
+ the results from
+ <code>System.getProperty( "os.name" )</code>.
It strips all the whitespace from the name, and appends it
- to the <code>org.apache.excalibur.util.system</code> package.
+ to the
+ <code>org.apache.excalibur.util.system</code> package.
For example, if the "os.name" property returns "Windows XP",
then the full class name needs to be
- <code>org.apache.excalibur.util.system.WindowsXP</code>.
- </p>
- </section>
- <section name="Writing a CPUParser" >
- <p>
+ <code>org.apache.excalibur.util.system.WindowsXP</code>.
+ </p>
+ </section>
+ <section name="Writing a CPUParser">
+ <p>
Writing a CPUParser is not hard. You only need to know
how to name your implementation, and then write the relevant
logic. All CPUParser implementations must be in the
- <code>org.apache.excalibur.util.system</code> package and
+ <code>org.apache.excalibur.util.system</code> package and
implement the CPUParser interface. The example below is
taken from the WindowsXP CPUParser included in this project.
- </p>
- <source>
-<![CDATA[
+ </p>
+ <source>
+ <![CDATA[
package org.apache.excalibur.util.system;
import java.io.BufferedReader;
@@ -110,8 +113,8 @@
}
}
-]]>
- </source>
- </section>
- </body>
+ ]]>
+ </source>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/event/event-howto.xml
==============================================================================
--- excalibur/trunk/site/xdocs/event/event-howto.xml (original)
+++ excalibur/trunk/site/xdocs/event/event-howto.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,96 +17,101 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Excalibur Event - How To Use Event</title>
- </properties>
- <body>
- <section name="Event is a Framework for Event Processing" >
- <p>
+ <properties>
+ <title>Event - How To Use Event</title>
+ </properties>
+ <body>
+ <section name="Event is a Framework for Event Processing">
+ <p>
The first thing that you should expect is that Event does not
- <b>do</b> anything by itself. It defines all the core interfaces
+ <b>do</b> anything by itself. It defines all the core interfaces
used with the Event package. We also have a few implementations.
This documentation focuses on how to use the interfaces.
- </p>
- <p>
+ </p>
+ <p>
An Event Source is where we pull events from. Whether that Source
is a Queue or just some implementation of the Source doesn't
- really matter. The Source has a <code>setTimeout()</code> to
+ really matter. The Source has a
+ <code>setTimeout()</code> to
make the Source block for the specified number of milliseconds
before responding.
- </p>
- <p>
+ </p>
+ <p>
An Event Sink is where we send events. Again, the Sink can be
a unique class, or the other end of a Queue. We have several options
for enqueueing events.
- </p>
- <p>
+ </p>
+ <p>
A Queue is the union of the Sink and the Source. Events enqueued
on to the Sink portion of the Queue will later be dequeued from
the Source side of the Queue. Because a Queue is simply a Sink and
a Source merged together, there is no reason to duplicate usage
docs.
- </p>
- <p>
+ </p>
+ <p>
The EventHandler is a class that is set up to handle events. Those
events can then be processed and sent to one of several Queues in
the system.
- </p>
- </section>
- <section name="Pulling Events From a Source" >
- <p>
+ </p>
+ </section>
+ <section name="Pulling Events From a Source">
+ <p>
We have three options: pull one event at a time, unload all the
events, or pull a number of events at a time. Each of these
may be preferred one over the other depending on your design needs.
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
Object oneEvent = m_mySource.dequeue();
Object[] allEvents = m_mySource.dequeueAll();
Object[] someEvents = m_mySource.dequeue( 10 );
- ]]>
- </source>
- <p>
+ ]]>
+ </source>
+ <p>
If there are no events, and the timeout is set to 0 or less, we
will immediately return with the results. The version that returns
- only one event will return <code>null</code> if there are no events.
+ only one event will return
+ <code>null</code> if there are no events.
The versions that return more than one event will return an empty
array.
- </p>
- <note>
- The dequeue() operation that accepts a number will return <strong>up
+ </p>
+ <note>
+ The dequeue() operation that accepts a number will return
+ <strong>up
to</strong> that number of events. If there are fewer events in the
Source, then it will only return that number.
- </note>
- <p>
- There are two remaining methods: <code>setTimeout()</code>, and
- <code>size()</code>. The <code>size()</code> method returns the
- number of elements in the Sink. The <code>setTimeout()</code>
+ </note>
+ <p>
+ There are two remaining methods:
+ <code>setTimeout()</code>, and
+ <code>size()</code>. The
+ <code>size()</code> method returns the
+ number of elements in the Sink. The
+ <code>setTimeout()</code>
sets the number of milliseconds you are willing to wait for an
event to show up in the Source. If the timeout is set to zero
or less, the dequeue() methods will return immediately.
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
// Return immediately
m_mySource.setTimeout( 0 );
// Return after the specified timeout (in milliseconds)
m_mySource.setTimeout( 250 );
- ]]>
- </source>
- </section>
- <section name="Sending Events to a Sink" >
- <p>
+ ]]>
+ </source>
+ </section>
+ <section name="Sending Events to a Sink">
+ <p>
We have several options for enqueuing events into a Sink.
We have transactional enqueuing, lossy enqueuing, and
normal enqueuing.
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
// Enqueue one event at a time:
try
{
@@ -159,32 +166,39 @@
*/
getLogger().error( "Error enqueuing events", se );
}
- ]]>
- </source>
- <p>
+ ]]>
+ </source>
+ <p>
The transactional enqueuing allows you to set some
events on the Sink ahead of time, and perform your processing.
If the events are not up to snuff, you can abort() the
enqueue, and they will not be processed.
- </p>
- <p>
+ </p>
+ <p>
There are some other methods that are utility methods:
- <code>maxSize()</code>, <code>isFull()</code>,
- <code>canAccept()</code>, <code>size()</code>. They help
- you in your planning. Use <code>maxSize()</code> to determine
+ <code>maxSize()</code>,
+ <code>isFull()</code>,
+ <code>canAccept()</code>,
+ <code>size()</code>. They help
+ you in your planning. Use
+ <code>maxSize()</code> to determine
the bounds of the Sink. If the value returned is -1, then
there are no bounds. If the value is positive, then that
is the limit of the number of events the Sink can have at
- one time. The <code>canAccept()</code> method is related
+ one time. The
+ <code>canAccept()</code> method is related
in that it only makes sense for bounded Sinks. If there is
- a limit the <code>canAccept()</code> method will return the
+ a limit the
+ <code>canAccept()</code> method will return the
number of events the Sink will accept, otherwise it will
- return -1. The <code>size()</code> method returns the number
- of elements still in the Sink. The <code>isFull()</code>
+ return -1. The
+ <code>size()</code> method returns the number
+ of elements still in the Sink. The
+ <code>isFull()</code>
method returns wether the Sink has more room.
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
// Determining how many events a Sink can handle
int numElements = m_mySink.canAccept();
@@ -192,18 +206,18 @@
{
// This is an unbounded Sink
}
- ]]>
- </source>
- </section>
- <section name="EventHandlers" >
- <p>
+ ]]>
+ </source>
+ </section>
+ <section name="EventHandlers">
+ <p>
Event Handlers are used in automated event routing systems like
SEDA architectures. Basically, it is a way for your object/component
to handle events without having to implement the Sink interface,
which can be kind of tricky. Here is an example:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
import org.apache.excalibur.event.EventHandler;
/** Send events to System.out */
@@ -224,8 +238,8 @@
System.out.println( event );
}
}
- ]]>
- </source>
- </section>
- </body>
+ ]]>
+ </source>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/event/event.xml
==============================================================================
--- excalibur/trunk/site/xdocs/event/event.xml (original)
+++ excalibur/trunk/site/xdocs/event/event.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,56 +17,55 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Excalibur Event - Event</title>
- </properties>
- <body>
- <section name="Why Event Was Created" >
- <p>
+ <properties>
+ <title>Event - Event</title>
+ </properties>
+ <body>
+ <section name="Why Event Was Created">
+ <p>
Event was created out of a desire to express the Staged Event
Driven Architecture (SEDA) design in an Avalon way. It has
grown to be a robust event pipelining library. We maintained
the core concepts from the
- <a href="http://seda.sourceforge.net/" target="_new" >SandStorm</a>
+ <a href="http://seda.sourceforge.net/" target="_new">SandStorm</a>
server, and cleaned up the API to have Queues operate in a
more transactional way.
- </p>
- </section>
- <section name="When To Use Event" >
- <p>
+ </p>
+ </section>
+ <section name="When To Use Event">
+ <p>
Most of the time, your use of the Event package is only to
interface to other subsystems. For instance, the
- <a href="command.html">Command Manager</a> uses the
+ <a href="command.html">Command Manager</a> uses the
Event Queues to receive commands from multiple threads
simultaneously.
- </p>
- <p>
+ </p>
+ <p>
You can also use Event when you are developing new systems
that have loosely coupled, disjunct pieces. One of the core
benefits of using event pipelines is that we can easily
reroute the Queues while the system is running, and not lose
any events.
- </p>
- </section>
- <section name="Core Concepts" >
- <p>
+ </p>
+ </section>
+ <section name="Core Concepts">
+ <p>
An Event Pipeline has a set of Sources and Sinks. A Source
is where you get more events, or the "dequeue" side of an
event Queue. A Sink is where you send events on to the next
stage, or the "enqueue" side of an event Queue.
- </p>
- <section name="Source" >
- <p>
+ </p>
+ <section name="Source">
+ <p>
The Source can be blocking or non-blocking. A blocking
Source will stop the current thread from processing until
there are new events to give to it. A non-blocking Source
will return an empty set of events immediately if there
are no more events.
- </p>
- </section>
- <section name="Sink" >
- <p>
+ </p>
+ </section>
+ <section name="Sink">
+ <p>
The Sink allows you to add events in a variety of ways.
You can simply add them one at a time, or you can add
a whole group of events at one time. The Sink also supports
@@ -73,24 +74,24 @@
at a later time. The Sink will make room for the events,
but it will not let them pass through until they are officially
committed.
- </p>
- </section>
- <section name="Queue" >
- <p>
+ </p>
+ </section>
+ <section name="Queue">
+ <p>
A Queue is merely the union of a Sink and a Source. A Queue
will manage the throughput of the events from Sink to Source.
- </p>
- </section>
- <section name="Signals and Messages" >
- <p>
+ </p>
+ </section>
+ <section name="Signals and Messages">
+ <p>
Signals and Messages are special events that provide contextual
information. A message will have a string and/or an object
attached to it. They are used mainly for reporting purposes,
or for the begginings of a Messaging Oriented Middleware (MOM)
implementation. A Signal is a control event that the Queue,
and the system react to.
- </p>
- </section>
- </section>
- </body>
+ </p>
+ </section>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/event/index.xml
==============================================================================
--- excalibur/trunk/site/xdocs/event/index.xml (original)
+++ excalibur/trunk/site/xdocs/event/index.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,24 +17,23 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>About Excalibur Event</title>
- </properties>
- <body>
- <section name="Introduction" >
- <p>
+ <properties>
+ <title>Event</title>
+ </properties>
+ <body>
+ <section name="Introduction">
+ <p>
This is the Excalibur Event package which includes event queues,
asynchronous command processing, and the interfaces to support
event based programming. Event is heavily influenced by Matt
Welsh's work with the
- <a href="http://www.cs.berkeley.edu/~mdw/proj/seda/" target="_new" >
+ <a href="http://www.cs.berkeley.edu/~mdw/proj/seda/" target="_new">
SEDA architecture</a>.
We forked the portion of his SandStorm server that had to do with
event processing. From there we cleaned up the API and made it as
generic as we could.
- </p>
- <p>
+ </p>
+ <p>
The Event package actually has five related sub packages inside
of it. Event is the basic interfaces for the Queues, Sinks,
Sources, etc. Command houses code for the CommandManager so that
@@ -42,7 +43,7 @@
don't have to worry about it. Lastly, Util provides some basic
utilities so that we can programatically determine the number
of processors your hardware has.
- </p>
- </section>
- </body>
+ </p>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/event/mpool-howto.xml
==============================================================================
--- excalibur/trunk/site/xdocs/event/mpool-howto.xml (original)
+++ excalibur/trunk/site/xdocs/event/mpool-howto.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,50 +17,50 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Excalibur Event - How To Use MPool</title>
- </properties>
- <body>
- <section name="Setting Up the PoolManager" >
- <p>
+ <properties>
+ <title>Event - How To Use MPool</title>
+ </properties>
+ <body>
+ <section name="Setting Up the PoolManager">
+ <p>
In order to set up a CommandManager. For those instructions,
- follow <a href="command-howto.html">the Command "How To"</a>.
+ follow
+ <a href="command-howto.html">the Command "How To"</a>.
From there, you want to set up the PoolManager using the following
code:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
// Using the CommandManager in the variable "commandManager"
PoolManager poolManager = new DefaultPoolManager( commandManager );
- ]]>
- </source>
- </section>
- <section name="Creating Your Pool" >
- <p>
+ ]]>
+ </source>
+ </section>
+ <section name="Creating Your Pool">
+ <p>
The PoolManager is responsible for manufacturing managed pools,
and for managing their sizes. All PoolManager managed pools are
"soft" limiting. They will continue to grow while they are being
accessed heavily, but it will shrink during times of inactivity.
To create your pool, use the following code:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
int initialEntries = 20;
ObjectFactory objectFactory = new MySpecialObjectFactory();
Pool managedPool = poolManager.getManagedPool( objectFactory, initialEntries );
- ]]>
- </source>
- <section name="Writing an ObjectFactory" >
- <p>
+ ]]>
+ </source>
+ <section name="Writing an ObjectFactory">
+ <p>
Writing an Object Factory is not that difficult. You just need to
implement the ObjectFactory interface. Below is an example
implementation:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
public class MySpecialObjectFactory implements ObjectFactory
{
private final Class m_mySpecialClass;
@@ -99,52 +101,53 @@
// perform permanent cleanup code
}
}
- ]]>
- </source>
- </section>
- <section name="Unmanaged Pools" >
- <p>
+ ]]>
+ </source>
+ </section>
+ <section name="Unmanaged Pools">
+ <p>
There are two unmanaged pool types in MPool:
FixedSizePool and BlockingFixedSizePool. They are
similar to one another, but differ in how they respond
to insufficient resources. The FixedSizePool fails fast,
and throws an exception. The BlockingFixedSizePool tries
to wait for a specified number of milliseconds.
- </p>
- <p>
+ </p>
+ <p>
The Fixed Size Pools are not managed because they will only
have a certain number of pooled objects at any time. They
will never grow or shrink. They are useful for instances
where the number of elements are known in advanced. One
example is a JDBC connection pool because some vendors require
you to pay per connection licensing fees.
- </p>
- </section>
- </section>
- <section name="Using the Pool" >
- <p>
+ </p>
+ </section>
+ </section>
+ <section name="Using the Pool">
+ <p>
Using the pools is quite simple:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
Object pooledResource = managedPool.acquire();
// do whatever I want with the pooled resource
managedPool.release( pooledResource );
- ]]>
- </source>
- <p>
+ ]]>
+ </source>
+ <p>
What if we have an object that needs to perform some simple
- cleanup? Have your Object implement the <code>Resettable</code>
+ cleanup? Have your Object implement the
+ <code>Resettable</code>
interface. What if we are migrating from the old Pool package?
You don't have to do anything. MPool knows about the old Pool
package, and will check for its recyclable method. It will only
call the Resettable.reset() method if your object implements both
interfaces. Both of these will work:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
import org.apache.excalibur.mpool.Resettable;
public class ResettableObject implements Resettable
@@ -156,10 +159,10 @@
// perform small cleanup code...
}
}
- ]]>
- </source>
- <source>
- <![CDATA[
+ ]]>
+ </source>
+ <source>
+ <![CDATA[
import org.apache.avalon.excalibur.pool.Recyclable;
public class ResettableObject implements Recyclable
@@ -171,8 +174,8 @@
// perform small cleanup code...
}
}
- ]]>
- </source>
- </section>
- </body>
+ ]]>
+ </source>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/event/mpool.xml
==============================================================================
--- excalibur/trunk/site/xdocs/event/mpool.xml (original)
+++ excalibur/trunk/site/xdocs/event/mpool.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,19 +17,18 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Excalibur Event - MPool (Managed Pool)</title>
- </properties>
- <body>
- <section name="Why MPool Was Created" >
- <p>
+ <properties>
+ <title>Event - MPool (Managed Pool)</title>
+ </properties>
+ <body>
+ <section name="Why MPool Was Created">
+ <p>
MPool (Managed Pool) was created as an experiment in dynamic
pool management. The theory is that by determining whether to
shrink or grow a pool can be a costly endeavor. That is
especially true when you want to play with "intelligent" pools.
- </p>
- <p>
+ </p>
+ <p>
What we observed after we used MPool in practice is that under
load, pool sizing algorithms begin to choke the efficiency of
the pool. In fact, it can get so bad that it would be better
@@ -39,53 +40,53 @@
we destroy pooled objects that we don't need. During times of
stress, we create a new object immediately and in a background
process we add new objects.
- </p>
- </section>
- <section name="When To Use MPool" >
- <p>
+ </p>
+ </section>
+ <section name="When To Use MPool">
+ <p>
Use MPool any time you need a pool without hard limits, and you
expect heavy loads. The pool size is checked periodically, so
we don't incur extra overhead of having to check that while the
pool size grows and shrinks.
- </p>
- </section>
- <section name="Core Concepts" >
- <p>
+ </p>
+ </section>
+ <section name="Core Concepts">
+ <p>
MPool has two pool types: fixed size and variable size. A fixed
size pool is not managed externally. There is a fixed limit to
the number of resources it can manage so we don't have to manage
it. A variable sized pool is a managed pool. A managed pool will
be created by the PoolManager, and that manager will manage all
of its pool sizes in the background.
- </p>
- <section name="Object Factory" >
- <p>
+ </p>
+ <section name="Object Factory">
+ <p>
An Object Factory is what the pools use to create new objects
or destroy old ones. They are particularly helpful when there
is a complex creation/destruction policy. They are also essential
for ManageablePools.
- </p>
- </section>
- <section name="Pool" >
- <p>
+ </p>
+ </section>
+ <section name="Pool">
+ <p>
The base Pool interface is how the client code interacts with
the pool. You acquire and release pooled objects from the
pool.
- </p>
- </section>
- <section name="Managable Pool" >
- <p>
+ </p>
+ </section>
+ <section name="Managable Pool">
+ <p>
A Managable Pool is a special interface that allows a PoolManager
to register itself with a "magic key" so that the managed pool
only responds to the PoolManager responsible for it.
- </p>
- </section>
- <section name="Pool Manager" >
- <p>
+ </p>
+ </section>
+ <section name="Pool Manager">
+ <p>
The Pool Manager is how you obtain a Managable Pool. It also
takes care of the management functions for that pool.
- </p>
- </section>
- </section>
- </body>
+ </p>
+ </section>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/event/navigation.xml
==============================================================================
--- excalibur/trunk/site/xdocs/event/navigation.xml (original)
+++ excalibur/trunk/site/xdocs/event/navigation.xml Wed Jun 23 02:32:50 2004
@@ -1,48 +1,86 @@
<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<project>
- <title>Avalon Sandbox</title>
+ <title>Apache Excalibur</title>
- <body>
+ <body>
- <links>
- <item name="Apache" href="http://apache.org/"/>
- <item name="Avalon" href="http://avalon.apache.org/"/>
- <item name="Framework" href="http://avalon.apache.org/product/framework/"/>
- <item name="Merlin" href="http://avalon.apache.org/product/containers/"/>
- <item name="Planet" href="http://avalon.apache.org/product/components/"/>
- </links>
-
- <menu name="About Excalibur">
- <item name="Overview" href="/index.html"/>
- <item name="Configuration" href="configuration.html"/>
- <item name="I18N" href="i18n/index.html"/>
- <item name="Sourceresolver" href="sourceresolve-index.html"/>
- <item name="Store" href="store-index.html"/>
- <item name="Event" href="event/index.html">
- <item href="event/event.html" name="Event"/>
- <item href="event/command.html" name="Command"/>
- <item href="event/mpool.html" name="MPool"/>
- <item href="event/util.html" name="Util"/>
- <item href="event/event-howto.html" name="Use Event Queues"/>
- <item href="event/command-howto.html" name="Use the Command Manager"/>
- <item href="event/mpool-howto.html" name="Use MPool"/>
- <item href="event/util-howto.html" name="Use System Util"/>
- <item href="event/cpuparser-howto.html" name="Extend System Util"/>
- </item>
- <item name="Event" href="event/index.html"/>
- <item name="I18N" href="i18n.html"/>
- <item name="Logger" href="logger.html"/>
- <item name="Lifecycle" href="lifecycle/index.html"/>
- <item name="Thread" href="thread.html"/>
- </menu>
-
- <menu name="Resources">
- <item name="Javadocs" href="http://avalon.apache.org/excalibur/api/"/>
- <item name="Download" href="http://avalon.apache.org/download.cgi"/>
- <item name="Where's my documentation???" href="/no-docs-available.html"/>
- </menu>
+ <links>
+ <item name="Apache" href="http://apache.org/"/>
+ <item name="Excalibur" href="http://excalibur.apache.org/"/>
+ <item name="Avalon-Framework" href="http://avalon.apache.org/product/framework/"/>
+ </links>
+
+ <menu name="Essentials">
+ <item name="Overview" href="/index.html"/>
+ <item name="Mailing Lists" href="/mail-lists.html"/>
+ <item name="Subversion" href="/svn.html"/>
+ <item name="Wiki" href="http://wiki.apache.org/excalibur/"/>
+ <item name="FAQ" href="http://wiki.apache.org/excalibur/FrequentlyAskedQuestions"/>
+ <item name="Javadocs" href="http://avalon.apache.org/excalibur/api/"/>
+ <item name="Download" href="http://avalon.apache.org/download.cgi"/>
+ <item name="Issue Tracking" href="/jira.html"/>
+ </menu>
+
+ <menu name="Component documentation">
+ <item name="Configuration" href="/configuration.html"/>
+ <item name="ECM" href="/component.html"/>
+ <item name="Event" href="event/index.html" collapse="false">
+ <item href="event/event.html" name="Event"/>
+ <item href="event/command.html" name="Command"/>
+ <item href="event/mpool.html" name="MPool"/>
+ <item href="event/util.html" name="Util"/>
+ <item href="event/event-howto.html" name="Use Event Queues"/>
+ <item href="event/command-howto.html" name="Use the Command Manager"/>
+ <item href="event/mpool-howto.html" name="Use MPool"/>
+ <item href="event/util-howto.html" name="Use System Util"/>
+ <item href="event/cpuparser-howto.html" name="Extend System Util"/>
+ </item>
+ <item name="Fortress" href="fortress/index.html" collapse="true">
+ <item name="Overview" href="fortress/index.html"/>
+ <item name="Features Oriented" href="fortress/features.html"/>
+ <item name="Getting Started" href="fortress/getting-started.html"/>
+ <item name="Using Meta Info" href="fortress/using-meta-info.html"/>
+ <item name="CLI" href="fortress/cli.html"/>
+ <item name="Swing" href="fortress/swing.html"/>
+ <item name="Servlet" href="fortress/servlet.html"/>
+ <item name="Lifecycle Extensions" href="fortress/lifecycle-extensions.html"/>
+ <item name="Design Notes" href="fortress/design-notes.html"/>
+ </item>
+ <item name="i18n" href="i18n.html"/>
+ <item name="Lifecycle" href="lifecycle/index.html" collapse="true">
+ <item name="Overview" href="lifecycle/index.html"/>
+ <item name="Extensions" href="lifecycle/extension.html"/>
+ <item name="Interfaces" href="lifecycle/interfaces.html"/>
+ <item name="Tutorial" href="lifecycle/fortress.html"/>
+ </item>
+ <item name="Logger" href="logger.html"/>
+ <item name="Sourceresolver" href="sourceresolve-index.html"/>
+ <item name="Store" href="store-index.html"/>
+ <item name="Thread" href="thread.html"/>
+ </menu>
+
+ <menu name="Miscellaneous">
+ <item name="Where's my documentation???" href="/no-docs-available.html"/>
+ </menu>
- </body>
+ </body>
</project>
Modified: excalibur/trunk/site/xdocs/event/util-howto.xml
==============================================================================
--- excalibur/trunk/site/xdocs/event/util-howto.xml (original)
+++ excalibur/trunk/site/xdocs/event/util-howto.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,22 +17,21 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Excalibur Event - How To Use Util</title>
- </properties>
- <body>
- <section name="Getting the System Info" >
- <p>
+ <properties>
+ <title>Event - How To Use Util</title>
+ </properties>
+ <body>
+ <section name="Getting the System Info">
+ <p>
Util has one utility: SystemUtil. SystemUtil is a static
class that performs its magic when the class is loaded.
It stores the information because it is unlikely that you
will ever go from one to two processors while your machine
is running. The code snippet below demonstrates how to
get any and all the relavant information:
- </p>
- <source>
-<![CDATA[
+ </p>
+ <source>
+ <![CDATA[
public void dumpInfo()
{
System.out.println( "Number of Processors: " + SystemUtil.numProcessors() );
@@ -39,13 +40,13 @@
System.out.println( "Operating System: " + SystemUtil.operatingSystem() );
System.out.println( "OS Version: " + SystemUtil.osVersion() );
}
-]]>
- </source>
- <p>
+ ]]>
+ </source>
+ <p>
As you can see there is no real mystery here. The method above
uses every available SystemUtil method, and it is taken directly
from the JUnit TestCase for SystemUtil.
- </p>
- </section>
- </body>
+ </p>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/event/util.xml
==============================================================================
--- excalibur/trunk/site/xdocs/event/util.xml (original)
+++ excalibur/trunk/site/xdocs/event/util.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,56 +17,55 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Excalibur Event - Util</title>
- </properties>
- <body>
- <section name="Why Util Was Created" >
- <p>
+ <properties>
+ <title>Event - Util</title>
+ </properties>
+ <body>
+ <section name="Why Util Was Created">
+ <p>
Util was created to enable us to find out how many processors are
on a system programmatically. Unfortunately Sun does not think
it is important to know these details through Java. The Thread
Manager uses this to automatically determine how many background
threads it wants in the backing ThreadPool.
- </p>
- </section>
- <section name="When To Use Util" >
- <p>
+ </p>
+ </section>
+ <section name="When To Use Util">
+ <p>
Usually you won't use this package directly, unless you want to
know how many processors a system has. You might need to add a
new CPU Parser that will find out the necessary information from
environment variables or the /proc/ filesystem for a platform
that is not currently supported.
- </p>
- </section>
- <section name="Core Concepts" >
- <p>
+ </p>
+ </section>
+ <section name="Core Concepts">
+ <p>
Util has a SystemUtil which will load the correct CPU Parser for your
platform. If there is no maching CPU Parser will assume that there is
only one processor for your system.
- </p>
- <section name="System Util" >
- <p>
+ </p>
+ <section name="System Util">
+ <p>
The System Util will allow you to gather any platform specific
information. Some of the methods are simpler ways of accessing
the System properties, and others are derived from the CPU Parser.
- </p>
- </section>
- <section name="CPU Parser" >
- <p>
+ </p>
+ </section>
+ <section name="CPU Parser">
+ <p>
The CPU Parser will allow you to gather essential information from
your platform. Unfortunately we cannot assume there is only one
way to gather information for each platform. If your platform is
not supported directly, please send an email to the
- <a href="mailto:users@avalon.apache.org">Avalon Users</a>
+ <a href="mailto:users@avalon.apache.org">Avalon Users</a>
mailing list with the new CPU Parser attached. We should be able
to include it in the next release. We currently support the entire
Microsoft Windows suite that supports Java, and Linux. Since we
don't currently have access to other machines, we can't support them
yet.
- </p>
- </section>
- </section>
- </body>
+ </p>
+ </section>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/fortress/cli.xml
==============================================================================
--- excalibur/trunk/site/xdocs/fortress/cli.xml (original)
+++ excalibur/trunk/site/xdocs/fortress/cli.xml Wed Jun 23 02:32:50 2004
@@ -1,50 +1,66 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
- <properties>
- <title>Avalon Fortress - Overview</title>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- </properties>
-
- <body>
- <section name="Command Line Tools">
- <p>
+ <properties>
+ <title>Fortress - CLI</title>
+
+ </properties>
+
+ <body>
+ <section name="Command Line Tools">
+ <p>
Command Line Tools are the class of tools or applications that are
run from a command shell. Typical examples are the ANT build tool,
Turbine Maven, Apache Forrest, etc. They have a definite begining
and a definite end. As a result, we don't have to do any trickery
with threads or synchronizing the startup and shutdown of the
container.
- </p>
- <p>
+ </p>
+ <p>
A typical example of creating a Fortress CLI application will follow
the pattern outlined below:
- </p>
-<!-- <source>
- <![CDATA[
-public int main(String [] args)
-{
- // You would have to implement the referenced method here...
- FortressConfig config = configWithArgs( args );
- ContainerManager cm = new DefaultContainerManager( config.getContext() );
- ContainerUtil.initialize( cm );
-
- // Get the root container and use it
- MyCLIContainer container = (MyCLIContainer) cm.getContainer();
- container.performAction(args);
-
- // Clean up after ourselves
- ContainerUtil.dispose( cm );
-}
- ]]>
- </source>-->
- <p>
+ </p>
+ <!-- <source>
+ <![CDATA[
+ public int main(String [] args)
+ {
+ // You would have to implement the referenced method here...
+ FortressConfig config = configWithArgs( args );
+ ContainerManager cm = new DefaultContainerManager( config.getContext() );
+ ContainerUtil.initialize( cm );
+
+ // Get the root container and use it
+ MyCLIContainer container = (MyCLIContainer) cm.getContainer();
+ container.performAction(args);
+
+ // Clean up after ourselves
+ ContainerUtil.dispose( cm );
+ }
+ ]]>
+ </source>-->
+ <p>
As you can see, there are three major portions of working with
Fortress: startup, useage, and shutdown; The Startup and shutdown
portions are not likely to change at all. What will change is how
you plan on interacting with your container.
- </p>
- </section>
- </body>
+ </p>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/fortress/design-notes.xml
==============================================================================
--- excalibur/trunk/site/xdocs/fortress/design-notes.xml (original)
+++ excalibur/trunk/site/xdocs/fortress/design-notes.xml Wed Jun 23 02:32:50 2004
@@ -1,15 +1,31 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
- <properties>
- <title>Avalon Fortress - Design Notes</title>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- </properties>
-
- <body>
- <section name="Fortress Design Notes">
- <p>
+ <properties>
+ <title>Fortress - Design Notes</title>
+
+ </properties>
+
+ <body>
+ <section name="Fortress Design Notes">
+ <p>
Fortress has two design goals: facilitate heirarchical containers and
take management functions outside of the critical path. The critical
path is the code execution path that is required to find and use a
@@ -17,17 +33,17 @@
his domain--which Fortress itself would never have any knowledge of. It
also assumes that there is one root container, although it does not
force that upon the developer.
- </p>
- <subsection name="Asynchronous Management">
- <p>
+ </p>
+ <subsection name="Asynchronous Management">
+ <p>
Due to the long startup times of certain components like the
DataSourceComponent ECM based code suffered from slowness. The problem
was also made worse by the delayed loading and running of components.
Components would only be instantiated when they were first looked
up--which made problems for components that needed to be started
immediately.
- </p>
- <p>
+ </p>
+ <p>
Fortress makes use of the Event package's CommandManager so that all
components can be started up immediately, but it is done in the
background. That means that components are still starting while
@@ -35,17 +51,17 @@
before it is needed, then Fortress will make sure it starts before it
turns over the requested component. It will also make sure no
component gets started twice.
- </p>
- <p>
+ </p>
+ <p>
All component pool sizing and management is done by background threads
so that as Fortress responds to requests for components, it manages
resources without adding that cost to the client code. That means the
critical path (the code that actually does the work of the system) is
not delayed unnecessarily.
- </p>
- </subsection>
- <subsection name="Hierarchical Containers">
- <p>
+ </p>
+ </subsection>
+ <subsection name="Hierarchical Containers">
+ <p>
Part of the design concept for Fortress heirarchical containers is to
use a ContainerManager to make sure all the necessary services are set
up and running. For example, the Fortress container needs a
@@ -53,8 +69,8 @@
set up and uses it. That way we can have one Container that has one or
more ContainerManagers that all use the kernel level services of the
parent container.
- </p>
- <p>
+ </p>
+ <p>
The kernel level services are: CommandManager, InstrumentManager,
LoggerManager and ThreadManager. The actual setup and configuration of
these services are done using a Context. The choice for the Context
@@ -62,40 +78,42 @@
objects in a proprietary manner (LoggerManageable, etc.) like the ECM
did. By passing the kernel services in the context, the kernel
services can be forwarded to any child containers.
- </p>
- <p>
+ </p>
+ <p>
To assist in the setup of the Context, Fortress uses a ContextManager.
The ContextManager will either set up the context based on a Context
passed in, or from a default context. Once the ContextManager assists
the ContainerManager to set up any missing kernel services, you can
get the Container from the ContainerManager and start using it.
- </p>
- </subsection>
- </section>
- <section name="Why Not Set Up a Standard Container Interface?">
- <p>
+ </p>
+ </subsection>
+ </section>
+ <section name="Why Not Set Up a Standard Container Interface?">
+ <p>
Each domain has its own needs. For instance, Cocoon is based on a
request/response processing model. Component based tools are based
on a useage model. Swing based Apps are based on other models. There
is no one size fits all solution, and Fortress can be used in all of
these solutions. As an interim solution, the DefaultContainer does
- have one public method exposed: <code>getServiceManager()</code>.
- </p>
- </section>
- <section name="Why Not Use a Central Kernel?">
- <p>
+ have one public method exposed:
+ <code>getServiceManager()</code>.
+ </p>
+ </section>
+ <section name="Why Not Use a Central Kernel?">
+ <p>
This was actually planned in a future release. There are some issues
to work out with a central kernel though. Those issues include how
to detect and set up sub-containers, how to make sure the container
instance you want is set up instead of the default version, etc. In
- essence, what is needed is <em>meta information</em>. Meta
+ essence, what is needed is
+ <em>meta information</em>. Meta
information is information about the container heirarchy and the
components involved. In the future Avalon Container: Merlin ,
has a proper meta model.
- </p>
- </section>
- <section name="Smooth Migration for Component Lookup">
- <p>
+ </p>
+ </section>
+ <section name="Smooth Migration for Component Lookup">
+ <p>
Due to the fact there are many ways of implementing the "preferred
practices" for role naming, different components make assumptions
about their environment. The chief problem with these assumptions
@@ -104,13 +122,13 @@
mapped, while another component may expect to lookup choices in
a ServiceSelector, while yet another may expect to find it via a
stylized entry. To recap, the supported lookup styles are:
- </p>
- <ul>
- <li>lookup(MyComponent.ROLE)</li>
- <li>lookup(MyComponent.ROLE + "Selector").select(hint)</li>
- <li>lookup(MyComponent.ROLE + "/" + hint)</li>
- </ul>
- <p>
+ </p>
+ <ul>
+ <li>lookup(MyComponent.ROLE)</li>
+ <li>lookup(MyComponent.ROLE + "Selector").select(hint)</li>
+ <li>lookup(MyComponent.ROLE + "/" + hint)</li>
+ </ul>
+ <p>
In the first case, the component that requires an external component
asks for the mapped component via the role name. It expects only
one component to be mapped. If Fortress has multiple components
@@ -118,20 +136,20 @@
version is the first entry in the configuration file, unless you
add the magic attribute "default" with the value "true". The last
component for the role with that attribute is the default value.
- </p>
- <p>
+ </p>
+ <p>
In the second case, the component expects to be able to select the
component from a ServiceSelector, mapped to the ROLE + "Selector"
entry. Fortress will manufacture a ServiceSelector for you, and
all will be as expected.
- </p>
- <p>
+ </p>
+ <p>
In the last case, the component expects to be able to look up the
component based on the ROLE and the hint combined. The magic
separator is the "/" character. Fortress will be able to interpret
that and skip the ServiceSelector step.
- </p>
- </section>
- </body>
+ </p>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/fortress/features.xml
==============================================================================
--- excalibur/trunk/site/xdocs/fortress/features.xml (original)
+++ excalibur/trunk/site/xdocs/fortress/features.xml Wed Jun 23 02:32:50 2004
@@ -1,23 +1,39 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
- <properties>
- <title>Avalon Fortress - Features</title>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- </properties>
-
- <body>
- <section name="Features">
- <p>
+ <properties>
+ <title>Fortress - Features</title>
+
+ </properties>
+
+ <body>
+ <section name="Features">
+ <p>
Fortress provides a framework for you to easily create your
own application specific containers. We strive to make it
easy for you to do without sacrificing any power. Fortress
allows you to focus on the core issues in your system, without
worrying about the component management getting in your way.
- </p>
- <subsection name="Asynchronous Component Management">
- <p>
+ </p>
+ <subsection name="Asynchronous Component Management">
+ <p>
Most component management functions don't take that long to
perform, but the time they do take can directly affect how
many requests your system can process at the same time. For
@@ -25,34 +41,34 @@
to manage our components. By moving all the management
functions to a limited number of background threads, we are
able to save you time in the critical processing path.
- </p>
- <p>
+ </p>
+ <p>
The CommandManager can be extended to your components as well.
That way, your components can perform management tasks in the
background as well. Fortress will likely be your choice of
containers if you have strict performance constraints.
- </p>
- </subsection>
- <subsection name="Extensible Lifecycle">
- <p>
+ </p>
+ </subsection>
+ <subsection name="Extensible Lifecycle">
+ <p>
Fortress has support for an experimental feature that allows
you to extend your component lifecycle in an application
specific manner. If it proves to be a truly useful feature,
other Avalon containers will adopt it.
- </p>
- </subsection>
- <subsection name="Instrumentation">
- <p>
+ </p>
+ </subsection>
+ <subsection name="Instrumentation">
+ <p>
Fortress is integrated with the Instrumentation package so
you can get a graphical view of the health of your system
at runtime. We integrate sampling points for each of the
component handlers so that you can see how many component
instances each handler is responsible for. Using that
information, you can tune your container more intelligently.
- </p>
- </subsection>
- <subsection name="Attribute Enabled Meta Information">
- <p>
+ </p>
+ </subsection>
+ <subsection name="Attribute Enabled Meta Information">
+ <p>
Instead of using a "roles" file to keep track of the component
configuration name, and what kind of lifestyle the component
has, Fortress provides some tools so that you can keep track
@@ -62,12 +78,12 @@
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.
- <a href="using-meta-info.html">You can find out more about it
+ <a href="using-meta-info.html">You can find out more about it
here.</a>
- </p>
- </subsection>
- </section>
- </body>
+ </p>
+ </subsection>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/fortress/getting-started.xml
==============================================================================
--- excalibur/trunk/site/xdocs/fortress/getting-started.xml (original)
+++ excalibur/trunk/site/xdocs/fortress/getting-started.xml Wed Jun 23 02:32:50 2004
@@ -1,56 +1,77 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
- <properties>
- <title>Fortress Getting Started</title>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- </properties>
+ <properties>
+ <title>Fortress - Getting Started</title>
- <body>
- <section name="Getting Started">
+ </properties>
+
+ <body>
+ <section name="Getting Started">
<p>
This is a brief guide to getting you up and running with fortress.
For complex topics like how to decompose a system into individual
components, Seperation of Concerns, etc, refer to other documentation.
</p>
- <subsection name="Getting your stuff together">
- <ul>
- <li>If you haven't already, download and install the latest version
- of <link href="http://ant.apache.org/">Apache Ant</link>.</li>
- <li>Get and install a CVS client (see
- <link href="http://jakarta.apache.org/site/cvsindex.html">here</link>
- for information on CVS).</li>
- <li>Check out the modules avalon, avalon-excalibur,
+ <subsection name="Getting your stuff together">
+ <ul>
+ <li>If you haven't already, download and install the latest version
+ of
+ <link href="http://ant.apache.org/">Apache Ant</link>.
+ </li>
+ <li>Get and install a CVS client (see
+ <link href="http://jakarta.apache.org/site/cvsindex.html">here</link>
+ 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>
- </ul>
+ </li>
+ </ul>
- <p>Or, if you hate CVS, get a nightly build.</p>
- </subsection>
- <subsection name="Hello, world!">
- <p>You just built fortress, its dependencies, and its examples from cvs in
+ <p>Or, if you hate CVS, get a nightly build.</p>
+ </subsection>
+ <subsection name="Hello, world!">
+ <p>You just built fortress, its dependencies, and its examples from cvs in
the previous step. This enables you to (finally!) run a HelloWorld demo.
change into the bin directory for the examples and run the
scripts there (runswing.sh is a nice one).</p>
- </subsection>
- <subsection name="Well, duh! So now what?">
- <p><b>Play with the examples</b></p>
+ </subsection>
+ <subsection name="Well, duh! So now what?">
+ <p>
+ <b>Play with the examples</b>
+ </p>
<p>After looking at the sources to the examples provided and figuring out
what goes on (if you're an IDE person, run the examples in your IDE
debugger! If you develop servlets, be sure to try to get the servlet
example to run), the real cool but also the hard part begins.</p>
- </subsection>
- <subsection name="Converting from ECM">
+ </subsection>
+ <subsection name="Converting from ECM">
<p>If you're looking at converting an existing avalonized application that
uses ECM, well, we want to write a tool that does this all but automatically
for you. Not there yet though.</p>
- </subsection>
- <subsection name="Convert a non-avalon application">
+ </subsection>
+ <subsection name="Convert a non-avalon application">
<p>The first thing you want to do is to create a fortress instance inside
your applications main loop or bootstrap class. The second thing you want
to do is identify the building blocks of your application, and transform
@@ -62,25 +83,26 @@
<p>Okay, so it may not be so simple as it sounds, but that is the general
idea. Just get started, and come and talk to us on the mailing list when
you get lost.</p>
- </subsection>
- <subsection name="Creating a new application">
+ </subsection>
+ <subsection name="Creating a new application">
<p>Start with the example that fits your enviroment (console, GUI
or embedded), and simply start hacking from there. You'll want to think
about the various tasks your app serves, and how to decompose your app
into components that fit those tasks. The
- <link href="http://avalon.apache.org/developing">Developing with Avalon</link>
- paper talks you through this.</p>
- </subsection>
- <subsection name="Mastering Fortress">
- <p>
+ <link href="http://avalon.apache.org/developing">Developing with Avalon</link>
+ paper talks you through this.
+ </p>
+ </subsection>
+ <subsection name="Mastering Fortress">
+ <p>
The best way to learn about avalon and its concepts is to build your own
container. Try and plug in your own implementations of the different parts
of fortress, like a different ComponentHandler. Once you get a hang of it,
come and join the avalon folks in their quest for the holy grail of
software architecture!
- </p>
- </subsection>
+ </p>
+ </subsection>
- </section>
- </body>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/fortress/index.xml
==============================================================================
--- excalibur/trunk/site/xdocs/fortress/index.xml (original)
+++ excalibur/trunk/site/xdocs/fortress/index.xml Wed Jun 23 02:32:50 2004
@@ -1,52 +1,70 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
- <properties>
- <title>Avalon Fortress - Overview</title>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- </properties>
-
- <body>
- <section name="Introduction">
- <p>
+ <properties>
+ <title>Fortress - Overview</title>
+
+ </properties>
+
+ <body>
+ <section name="Introduction">
+ <p>
Fortress contains a framework to help you create your own
avalon containers. It boasts asynchronous management of your
component instances, high scalability, easier maintenance of
your code, and easy embedding into various environments like
servlet engines. Fortress replaces the older
Excalibur Component Manager (ECM) container.
- </p>
- </section>
- <section name="Fortress 1.1">
- <p>
- Fortress 1.1 has been released and includes a number of bug fixes. See the
- <a href="http://avalon.apache.org/download.cgi">download</a> section to get
+ </p>
+ </section>
+ <section name="Fortress 1.1">
+ <p>
+ Fortress 1.1 has been released and includes a number of bug fixes. See the
+ <a href="http://avalon.apache.org/download.cgi">download</a> section to get
the latest source and binary distributions.
- </p>
- </section>
- <section name="Available Documentation">
- <ul>
- <li>
- <strong>The Fortress documentation has not yet been updated for the latest
- release</strong>. We are currently working on new documentation in the
- <a href="http://wiki.apache.org/avalon/AvalonFortress">wiki</a>.
- </li>
- <li>
+ </p>
+ </section>
+ <section name="Available Documentation">
+ <ul>
+ <li>
+ <strong>The Fortress documentation has not yet been updated for the latest
+ release</strong>. We are currently working on new documentation in the
+ <a href="http://wiki.apache.org/avalon/AvalonFortress">wiki</a>.
+ </li>
+ <li>
The Avalon developers are working to provide better consistency
between our containers (ECM, Fortress, Phoenix, Merlin). We hope to
offer a single platform that will build on our previous efforts.
Please subscribe to the users or developers mailing list to receive
the latest updates. See the wiki for more information on
- <a href="http://wiki.apache.org/avalon/WhichContainer">which container</a>
- to consider and <a href="http://wiki.apache.org/avalon/ContainerStory">where the
+ <a href="http://wiki.apache.org/avalon/WhichContainer">which container</a>
+ to consider and
+ <a href="http://wiki.apache.org/avalon/ContainerStory">where the
containers came from</a>.
- </li>
- <li>For general information about the avalon project, you will want to read the
- <a href="http://avalon.apache.org/framework/">Avalon Framework Documentation</a>.
- <a href="http://avalon.apache.org/developing/">Developing with Avalon</a> is a
- terribly useful resource as well.</li>
- </ul>
- </section>
- </body>
+ </li>
+ <li>For general information about the avalon project, you will want to read the
+ <a href="http://avalon.apache.org/framework/">Avalon Framework Documentation</a>.
+ <a href="http://avalon.apache.org/developing/">Developing with Avalon</a> is a
+ terribly useful resource as well.
+ </li>
+ </ul>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/fortress/lifecycle-extensions.xml
==============================================================================
--- excalibur/trunk/site/xdocs/fortress/lifecycle-extensions.xml (original)
+++ excalibur/trunk/site/xdocs/fortress/lifecycle-extensions.xml Wed Jun 23 02:32:50 2004
@@ -1,230 +1,273 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
- <properties>
- <title>Fortress Getting Started</title>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- </properties>
-
- <body>
- <section name="What are lifecycle extensions ?">
- <p>
+ <properties>
+ <title>Fortress - Lifecycle Extensions</title>
+
+ </properties>
+
+ <body>
+ <section name="What are lifecycle extensions ?">
+ <p>
Lifecycle extensions are additional stages a component can traverse through during
it's lifetime. Lifecycle extensions allow a Container to provide extra functionality
to Components in addition to the standard stages defined by Avalon Framework.
- </p>
+ </p>
- <p>
+ <p>
Avalon Framework defines a set of standard interfaces often termed as Lifecycle
metainfo which tells the ComponentManager how a particular Component should be treated
during it's life.
- </p>
+ </p>
- <p>
+ <p>
This metainfo allows the developer to separate the various concerns involved when
writing a Component, often termed SoC and IoC (Separation of Concerns and Inversion of
Control) and is one of primary advantages of using Avalon.
- </p>
+ </p>
- <p>
+ <p>
Sometimes it's useful to extend this development paradigm from the framework level
into the application domain, to create customized lifecycle extensions that are called
upon in addition to the standard set defined by the Avalon Framework.
- </p>
+ </p>
- <p>
+ <p>
Such custom lifecycle stages can further enable domain specific logic across many,
perhaps even unrelated components, can reduce code duplication, and allows the developer
to reuse the same development and thinking paradigm as the standard lifecycle stages.
- </p>
+ </p>
- <p>
+ <p>
For example, you might want to pass a specialized SecurityManager to some of your
components before they are initialized, or have their internal state persistently cached
during system shutdown and restored at during startup. You might want to pass user
dependent decryption keys to your component, or give components the opportunity to
recycle themselves before being disposed or returned to a pooled component handler.
- </p>
+ </p>
- <p>
+ <p>
The possibilities and number of extensions are only limited by the requirements of your
particular application domain.
- </p>
+ </p>
- <p>
- This document describes how to add new lifecycle extensions using <strong>Fortress</strong>.
+ <p>
+ This document describes how to add new lifecycle extensions using
+ <strong>Fortress</strong>.
This document assumes a knowledge of what an Avalon lifecycle is, and a basic understanding
of the standard lifecycle interfaces Avalon Framework defines. References in this document to
Component and ComponentManager can also be freely interpreted as Service and ServiceManager
by the reader.
- </p>
+ </p>
- <note>As at the time of writing, Fortress is the only Avalon container that
+ <note>As at the time of writing, Fortress is the only Avalon container that
supports lifecycle extensions, which means Components that use this feature will most likely
only work as expected with Fortress, and not with the other Avalon containers
(ExcaliburComponentManager, Phoenix, Merlin, Tweety, etc)</note>
- <p>
+ <p>
Support for lifecycle extensions in the other Avalon containers is technically possible but
has not yet been discussed. Please check with the Avalon developer mailing list if you use
one of these containers and would like to use lifecycle extensions.
- </p>
+ </p>
- </section>
+ </section>
- <section name="How do I extend a Component's lifecycle ?">
- <p>
+ <section name="How do I extend a Component's lifecycle ?">
+ <p>
Extending a Component's lifecycle is straightforward. An overview of the process
follows:
- </p>
+ </p>
- <ol>
- <li>Define the new component interface<br/>
+ <ol>
+ <li>Define the new component interface
+ <br/>
Create the new interface defining the operations that should be called upon components
that implement this interface. Using the previously mentioned examples, this would be
- your <code>SecurityManageable</code>, <code>Cacheable</code>, <code>Decryptable</code>,
- <code>Recycleable</code> interfaces.
- </li>
-
- <li>Define an extension object that calls upon the methods defined in the new interface,
- during one or more of the pre-defined phases of component's lifecycle<br/>
+ your
+ <code>SecurityManageable</code>,
+ <code>Cacheable</code>,
+ <code>Decryptable</code>,
+ <code>Recycleable</code> interfaces.
+ </li>
+
+ <li>Define an extension object that calls upon the methods defined in the new interface,
+ during one or more of the pre-defined phases of component's lifecycle
+ <br/>
- Create a class that implements <code>LifecycleExtension</code>, that tests any given
+ Create a class that implements
+ <code>LifecycleExtension</code>, that tests any given
component for the above defined interface (and others if applicable), invoking methods
defined in that interface.
- </li>
+ </li>
- <li>Register the extension object with Fortress' <code>LifecycleExtensionManager</code><br/>
+ <li>Register the extension object with Fortress'
+ <code>LifecycleExtensionManager</code>
+ <br/>
Create an instance of the class defined in the previous step, and register it with a
- <code>LifecycleExtensionManager</code>, using either the default manager available inside
+ <code>LifecycleExtensionManager</code>, using either the default manager available inside
of your container, or an externally created manager that is later given to the container
to use.
- </li>
+ </li>
- <li>Implement the new component interface on your component<br/>
+ <li>Implement the new component interface on your component
+ <br/>
- Add the new <code>implements</code> clause to your Component, or Component implementation,
+ Add the new
+ <code>implements</code> clause to your Component, or Component implementation,
and write any methods defined in the implemented interface.
- </li>
+ </li>
- <li><code>lookup()/select()/release()</code> components as normal<br/>
+ <li>
+ <code>lookup()/select()/release()</code> components as normal
+ <br/>
Proceed as normal. Checking for extensions is done implicitly within Fortress. Once
lifecycle extensions are registered they will be invoked on any implementing components
during the 4 phases defined later in this document.
- </li>
- </ol>
- </section>
+ </li>
+ </ol>
+ </section>
- <section name="When can a Component's lifecycle be extended ?">
- <p>
+ <section name="When can a Component's lifecycle be extended ?">
+ <p>
The life of any component can be broken down to the following phases:
- </p>
+ </p>
- <ol>
- <li>Creation<br/>
+ <ol>
+ <li>Creation
+ <br/>
When the Component is actually instantiated.
- </li>
+ </li>
- <li>Access<br/>
+ <li>Access
+ <br/>
When the Component is accessed via a ComponentManager/Selector
- (<code>lookup()/select()</code>).
- </li>
-
- <li>Release<br/>
+ (
+ <code>lookup()/select()</code>).
+ </li>
+
+ <li>Release
+ <br/>
+
+ When the Component is released via a ComponentManager/Selector (
+ <code>release()</code>).
+ </li>
- When the Component is released via a ComponentManager/Selector (<code>release()</code>).
- </li>
-
- <li>Destruction<br/>
+ <li>Destruction
+ <br/>
When the Component is decommissioned, ready for garbage collection.
- </li>
+ </li>
- </ol>
+ </ol>
- <p>A Component will go through it's Creation and Destruction phase only once. Since
- <code>ComponentHandler</code> classes can implement different handling strategies
+ <p>A Component will go through it's Creation and Destruction phase only once. Since
+ <code>ComponentHandler</code> classes can implement different handling strategies
(Poolable, ThreadSafe, etc), the access and release phases of a component can be
- done multiple times.</p>
+ done multiple times.
+ </p>
- <p>
+ <p>
Lifecycle extensions can be added to any of the above defined phases. This allows
you to choose when your particular extension will be executed.
- </p>
+ </p>
- <p>
+ <p>
For example, thread or user dependent extensions would be added at the access and release
levels (ie. when the component is retrieved and returned to the ComponentManager) as they
depend on runtime data not available until they are actually used.
- </p>
+ </p>
- <p>
+ <p>
More static, or global extensions would be added at the creation or destruction level, since
they do not depend on any external data that change during runtime, nor are they particular
to any one context of use.
- </p>
+ </p>
- </section>
+ </section>
- <section name="Which interfaces and classes do I need to use ?">
+ <section name="Which interfaces and classes do I need to use ?">
- <p>
+ <p>
Support for lifecycle extensions in Fortress is done using the following classes/interfaces.
- </p>
+ </p>
- <subsection name="The Component Extension Interface">
- <p>
+ <subsection name="The Component Extension Interface">
+ <p>
This interface specifies the business particular extension components will be tested for.
It defines the new interface that components will implement to receive additional
functionality.
- </p>
+ </p>
- <p>
+ <p>
There is no particular base interface the developer needs to extend, and the interface
can be kept separate from the Container itself.
- </p>
- </subsection>
+ </p>
+ </subsection>
- <subsection name="The LifecycleExtension Interface">
+ <subsection name="The LifecycleExtension Interface">
- <p>
+ <p>
Component extensions are invoked via a Lifecycle extension object. Lifecycle extension
- objects are managed via a <code>LifecycleExtensionManager</code> class and essentially
+ objects are managed via a
+ <code>LifecycleExtensionManager</code> class and essentially
test for a particular Component extension interface, and appropriately call methods defined
in that interface.
- </p>
+ </p>
- <p>
- All Lifecycle extension objects must implement the <code>LifecycleExtension</code> interface.
- The <code>LifecycleExtension</code> interface defines 4 methods that are called upon to allow
+ <p>
+ All Lifecycle extension objects must implement the
+ <code>LifecycleExtension</code> interface.
+ The
+ <code>LifecycleExtension</code> interface defines 4 methods that are called upon to allow
an implementor to extend a component's lifecycle.
- </p>
+ </p>
- <p>
- The 4 methods (<code>create</code>, <code>destroy</code>, <code>access</code> and
- <code>release</code>) are invoked by a manager class from inside Fortress. Each method
+ <p>
+ The 4 methods (
+ <code>create</code>,
+ <code>destroy</code>,
+ <code>access</code> and
+ <code>release</code>) are invoked by a manager class from inside Fortress. Each method
accepts 2 parameters, the particular Component instance being extended, and the container
- <code>Context</code>.
- </p>
+ <code>Context</code>.
+ </p>
- <p>
- The container <code>Context</code> is passed as a parameter to provide access to any
+ <p>
+ The container
+ <code>Context</code> is passed as a parameter to provide access to any
miscellaneous objects that might be needed during extension code (to make use of this feature
the container Context will need to be initialized with references and passed to the
- <code>FortressConfig</code> during Fortress' startup sequence).
- </p>
+ <code>FortressConfig</code> during Fortress' startup sequence).
+ </p>
- <p>
+ <p>
Each method may throw an exception to indicate an error, which will be logged, but will
not terminate other extensions from being executed on that Component.
- </p>
+ </p>
- <source>
+ <source>
/**
* LifecycleExtension interface. This interface defines the methods that
* a LifecycleExtensionManager can call on a particular concrete
@@ -276,113 +319,129 @@
void release( Object component, Context context )
throws Exception;
}
- </source>
+ </source>
- <p>
+ <p>
Many extensions will not require implementation of every method defined in the
- above interface, for that reason, there's a <code>AbstractLifecycleExtension</code>
+ above interface, for that reason, there's a
+ <code>AbstractLifecycleExtension</code>
convenience class available which provides default (empty) implementations of each
method which you can extend from. This allows you to implement only the methods
necessary for your particular extension.
- </p>
+ </p>
- </subsection>
+ </subsection>
- <subsection name="The LifecycleExtensionManager class">
+ <subsection name="The LifecycleExtensionManager class">
- <p>
- The <code>LifecycleExtensionManager</code> class provides default management of
+ <p>
+ The
+ <code>LifecycleExtensionManager</code> class provides default management of
extension implementations and an API which ComponentManager/Selector's can call
upon to execute them.
- </p>
+ </p>
- <p>
+ <p>
The LifecycleExtensionManager class API is too big to list here, instead please look at
- the following <link href="http://avalon.apache.org/excalibur/fortress/api/org/apache/excalibur/fortress/lifecycle/LifecycleExtensionManager.html">link</link>. It essentially defines
+ the following
+ <link href="http://avalon.apache.org/excalibur/fortress/api/org/apache/excalibur/fortress/lifecycle/LifecycleExtensionManager.html">link</link>. It essentially defines
4 methods for executing extension objects at the various phases of a component's lifecycle,
and several methods for registering extension objects with the manager.
- </p>
+ </p>
- <p>
- The <code>LifecycleExtensionManager</code> class will operate safely in multithreaded
+ <p>
+ The
+ <code>LifecycleExtensionManager</code> class will operate safely in multithreaded
environments, and allows you to add/remove extensions to a running system.
- </p>
+ </p>
- <p>
+ <p>
By default, all Fortress based containers will be initialized with a default
- <code>LifecycleExtensionManager</code> that contains no extensions. You can alternatively
+ <code>LifecycleExtensionManager</code> that contains no extensions. You can alternatively
provide a pre-configured LifecycleExtensionManager to your Container via the
- FortressConfig class (<code>ContainerConstants.EXTENSION_MANAGER</code> key) if you like.
- </p>
+ FortressConfig class (
+ <code>ContainerConstants.EXTENSION_MANAGER</code> key) if you like.
+ </p>
- <p>
+ <p>
To add a new lifecycle extension object to the manager simply call the method
- <code>LifecycleExtensionManager.addExtension()</code>. Methods also exist for removing
+ <code>LifecycleExtensionManager.addExtension()</code>. Methods also exist for removing
and iterating through the currently available extensions.
- </p>
- </subsection>
+ </p>
+ </subsection>
- <subsection name="FortressComponentManager/FortressComponentSelector">
+ <subsection name="FortressComponentManager/FortressComponentSelector">
- <p>
+ <p>
Fortress' inbuilt Component Manager/Selector/Factory code will automatically call
upon the LifecycleExtensionManager class at each phase in a Component's life at the
following predefined times:
- </p>
+ </p>
- <ol>
- <li>Access<br/>
+ <ol>
+ <li>Access
+ <br/>
Called inside the ComponentManager, after the component has been retrieved
from it's handler, but before it's returned to the invoker of
- <code>lookup()/select()</code>.
- </li>
+ <code>lookup()/select()</code>.
+ </li>
- <li>Release<br/>
+ <li>Release
+ <br/>
Called inside the ComponentManager, before the component is passed back to
it's handler to be disposed/pooled/etc.
- </li>
-
- <li>Creation<br/>
-
- Called inside the ComponentFactory, before <code>initialize()</code>.
- </li>
-
- <li>Destruction<br/>
+ </li>
- Called inside the ComponentFactory, after <code>dispose()</code>.
- </li>
- </ol>
+ <li>Creation
+ <br/>
- <note>, components created via Fortress' ComponentHandler classes directly
- will bypass the logic for <code>access</code> and <code>release</code> extensions. This is
+ Called inside the ComponentFactory, before
+ <code>initialize()</code>.
+ </li>
+
+ <li>Destruction
+ <br/>
+
+ Called inside the ComponentFactory, after
+ <code>dispose()</code>.
+ </li>
+ </ol>
+
+ <note>, components created via Fortress' ComponentHandler classes directly
+ will bypass the logic for
+ <code>access</code> and
+ <code>release</code> extensions. This is
because the code performing this logic is located in the ComponentManager/Selector classes
- (independent from all handlers).</note>
+ (independent from all handlers).
+ </note>
- </subsection>
+ </subsection>
- </section>
+ </section>
- <section name="An Example">
+ <section name="An Example">
- <p>
+ <p>
Let's look at a simple example. The following is also available as a working sample
in Fortress' examples directory.
- </p>
+ </p>
- <p>
- Our example implements a Lifecycle extension for passing a <code>SecurityManager</code> to
- Components. We'll call it the <code>SecurityManageable</code> interface.
- </p>
+ <p>
+ Our example implements a Lifecycle extension for passing a
+ <code>SecurityManager</code> to
+ Components. We'll call it the
+ <code>SecurityManageable</code> interface.
+ </p>
- <subsection name="Define the component extension interface">
+ <subsection name="Define the component extension interface">
- <p>
+ <p>
First we define the new Component extension interface.
- </p>
+ </p>
- <source>
+ <source>
/**
* Simple custom lifecycle extension interface for supplying a component
* with a security manager.
@@ -397,21 +456,23 @@
void secure( SecurityManager manager )
throws SecurityException;
}
- </source>
+ </source>
- </subsection>
+ </subsection>
- <subsection name="Create the lifecycle extensions class">
+ <subsection name="Create the lifecycle extensions class">
- <p>
- Next we define the actual extension implementation which invokes the <code>secure()</code>
- method. We extend from <code>AbstractLifecycleExtension</code> since we only want
- <code>secure()</code> to be invoked upon each access (ie. lookup()) to the component, and
+ <p>
+ Next we define the actual extension implementation which invokes the
+ <code>secure()</code>
+ method. We extend from
+ <code>AbstractLifecycleExtension</code> since we only want
+ <code>secure()</code> to be invoked upon each access (ie. lookup()) to the component, and
don't need to implement the other 3 LifecycleExtension methods (create, release, and
destroy).
- </p>
+ </p>
- <source>
+ <source>
/**
* Some custom extensions for this container's components.
*/
@@ -437,29 +498,31 @@
}
}
}
- </source>
- </subsection>
+ </source>
+ </subsection>
- <p>An extension class may run components through any given number of
+ <p>An extension class may run components through any given number of
extensions, and are not limited to just one.</p>
- </section>
+ </section>
- <section name="Register the lifecycle extensions class">
+ <section name="Register the lifecycle extensions class">
- <p>
+ <p>
We then inform our container about the extension. This could be done in several different
- ways, for simplicity we'll extend <code>initialize()</code> and add it to the
- <code>LifecycleExtensionManager</code> there.
- </p>
+ ways, for simplicity we'll extend
+ <code>initialize()</code> and add it to the
+ <code>LifecycleExtensionManager</code> there.
+ </p>
- <p>
+ <p>
(an alternative might be to initialize a LifecycleExtensionManager before creating the
- container and pass it in via the <code>FortressConfig.setExtensionManager()</code> method,
+ container and pass it in via the
+ <code>FortressConfig.setExtensionManager()</code> method,
or to create a LifecycleExtensionManager subclass that includes the extension preset)
- </p>
+ </p>
- <source>
+ <source>
/**
* Simple container that includes custom lifecycle extensions.
*/
@@ -474,19 +537,20 @@
m_extManager.addExtension( new Extensions() );
}
}
- </source>
+ </source>
- </section>
+ </section>
- <section name="Use the new component interface">
+ <section name="Use the new component interface">
- <p>
+ <p>
To use the new SecurityManageable lifecycle extension, we simply implement
SecurityManageable just as we do with any other Avalon lifecycle interfaces
- (assuming a predefined Component interface <code>ExtendedComponent</code>).
- </p>
+ (assuming a predefined Component interface
+ <code>ExtendedComponent</code>).
+ </p>
- <source>
+ <source>
/**
* ExtendedComponentImpl, demonstrating the use of a custom
* lifecycle stage SecurityManageable. This code does
@@ -523,14 +587,15 @@
}
}
}
- </source>
- </section>
+ </source>
+ </section>
- <section name="Need more information?">
- <p>
+ <section name="Need more information?">
+ <p>
If you have any particular questions, comments, etc, please send an email to the Avalon
- developer mailing <link href="mailto:dev@avalon.apache.org">list</link>.
- </p>
- </section>
- </body>
+ developer mailing
+ <link href="mailto:dev@avalon.apache.org">list</link>.
+ </p>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/fortress/navigation.xml
==============================================================================
--- excalibur/trunk/site/xdocs/fortress/navigation.xml (original)
+++ excalibur/trunk/site/xdocs/fortress/navigation.xml Wed Jun 23 02:32:50 2004
@@ -1,49 +1,86 @@
<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<project>
- <title>Avalon Sandbox</title>
+ <title>Apache Excalibur</title>
- <body>
+ <body>
- <links>
- <item name="Apache" href="http://apache.org/"/>
- <item name="Avalon" href="http://avalon.apache.org/"/>
- <item name="Framework" href="http://avalon.apache.org/product/framework/"/>
- <item name="Merlin" href="http://avalon.apache.org/product/containers/"/>
- <item name="Planet" href="http://avalon.apache.org/product/components/"/>
- </links>
-
- <menu name="About Excalibur">
- <item name="Overview" href="/index.html"/>
- <item name="Configuration" href="configuration.html"/>
- <item name="I18N" href="i18n/index.html"/>
- <item name="Sourceresolver" href="sourceresolve-index.html"/>
- <item name="Store" href="store-index.html"/>
- <item name="ECM" href="component.html"/>
- <item name="Event" href="event/index.html"/>
- <item name="Fortress" href="fortress/index.html">
- <item name="Overview" href="fortress/index.html"/>
- <item name="Features Oriented" href="fortress/features.html"/>
- <item name="Getting Started" href="fortress/getting-started.html"/>
- <item name="Using Meta Info" href="fortress/using-meta-info.html"/>
- <item name="CLI" href="fortress/cli.html"/>
- <item name="Swing" href="fortress/swing.html"/>
- <item name="Servlet" href="fortress/servlet.html"/>
- <item name="Lifecycle Extensions" href="fortress/lifecycle-extensions.html"/>
- <item name="Design Notes" href="fortress/design-notes.html"/>
- </item>
- <item name="I18N" href="i18n.html"/>
- <item name="Logger" href="logger.html"/>
- <item name="Lifecycle" href="lifecycle/index.html"/>
- <item name="Thread" href="thread.html"/>
- </menu>
-
- <menu name="Resources">
- <item name="Javadocs" href="http://avalon.apache.org/excalibur/api/"/>
- <item name="Download" href="http://avalon.apache.org/download.cgi"/>
- <item name="Where's my documentation???" href="/no-docs-available.html"/>
- </menu>
+ <links>
+ <item name="Apache" href="http://apache.org/"/>
+ <item name="Excalibur" href="http://excalibur.apache.org/"/>
+ <item name="Avalon-Framework" href="http://avalon.apache.org/product/framework/"/>
+ </links>
+
+ <menu name="Essentials">
+ <item name="Overview" href="/index.html"/>
+ <item name="Mailing Lists" href="/mail-lists.html"/>
+ <item name="Subversion" href="/svn.html"/>
+ <item name="Wiki" href="http://wiki.apache.org/excalibur/"/>
+ <item name="FAQ" href="http://wiki.apache.org/excalibur/FrequentlyAskedQuestions"/>
+ <item name="Javadocs" href="http://avalon.apache.org/excalibur/api/"/>
+ <item name="Download" href="http://avalon.apache.org/download.cgi"/>
+ <item name="Issue Tracking" href="/jira.html"/>
+ </menu>
+
+ <menu name="Component documentation">
+ <item name="Configuration" href="/configuration.html"/>
+ <item name="ECM" href="/component.html"/>
+ <item name="Event" href="event/index.html" collapse="true">
+ <item href="event/event.html" name="Event"/>
+ <item href="event/command.html" name="Command"/>
+ <item href="event/mpool.html" name="MPool"/>
+ <item href="event/util.html" name="Util"/>
+ <item href="event/event-howto.html" name="Use Event Queues"/>
+ <item href="event/command-howto.html" name="Use the Command Manager"/>
+ <item href="event/mpool-howto.html" name="Use MPool"/>
+ <item href="event/util-howto.html" name="Use System Util"/>
+ <item href="event/cpuparser-howto.html" name="Extend System Util"/>
+ </item>
+ <item name="Fortress" href="fortress/index.html" collapse="false">
+ <item name="Overview" href="fortress/index.html"/>
+ <item name="Features Oriented" href="fortress/features.html"/>
+ <item name="Getting Started" href="fortress/getting-started.html"/>
+ <item name="Using Meta Info" href="fortress/using-meta-info.html"/>
+ <item name="CLI" href="fortress/cli.html"/>
+ <item name="Swing" href="fortress/swing.html"/>
+ <item name="Servlet" href="fortress/servlet.html"/>
+ <item name="Lifecycle Extensions" href="fortress/lifecycle-extensions.html"/>
+ <item name="Design Notes" href="fortress/design-notes.html"/>
+ </item>
+ <item name="i18n" href="i18n.html"/>
+ <item name="Lifecycle" href="lifecycle/index.html" collapse="true">
+ <item name="Overview" href="lifecycle/index.html"/>
+ <item name="Extensions" href="lifecycle/extension.html"/>
+ <item name="Interfaces" href="lifecycle/interfaces.html"/>
+ <item name="Tutorial" href="lifecycle/fortress.html"/>
+ </item>
+ <item name="Logger" href="logger.html"/>
+ <item name="Sourceresolver" href="sourceresolve-index.html"/>
+ <item name="Store" href="store-index.html"/>
+ <item name="Thread" href="thread.html"/>
+ </menu>
+
+ <menu name="Miscellaneous">
+ <item name="Where's my documentation???" href="/no-docs-available.html"/>
+ </menu>
- </body>
+ </body>
</project>
Modified: excalibur/trunk/site/xdocs/fortress/servlet.xml
==============================================================================
--- excalibur/trunk/site/xdocs/fortress/servlet.xml (original)
+++ excalibur/trunk/site/xdocs/fortress/servlet.xml Wed Jun 23 02:32:50 2004
@@ -1,39 +1,55 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
- <properties>
- <title>Fortress Getting Started</title>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- </properties>
-
- <body>
- <section name="Servlet Based Applications">
- <p>
+ <properties>
+ <title>Fortress Getting Started</title>
+
+ </properties>
+
+ <body>
+ <section name="Servlet Based Applications">
+ <p>
Servlet based applications are viewed on the web. Examples of these
types of Java projects are Jakarta Turbine, and Apache Cocoon.
Servlets have their own lifecycle, so it is rather easy to tie the
life of a container to the life of a servlet.
- </p>
- <p>
+ </p>
+ <p>
Servlet based applications can either tie the Avalon container to
a Servlet or bind it to JNDI. The advantage of binding it to JNDI is
better resource management because the container is not being torn
down and rebuilt periodically. The disadvantage is that there is no
standard way of doing it in your Servlet container. Most of the time
we bind the container to a Servlet like the following code:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
public class MyAvalonServlet implements HttpServlet
{
- private static final String ROOT =
+ private static final String ROOT =
"resource://org/apache/excalibur/fortress/examples/servlet/";
- private static final String XCONF =
+ private static final String XCONF =
ROOT + ServletContainer.xconf";
- private static final String XLOG =
+ private static final String XLOG =
ROOT + ServletContainer.xlog";
- private static final String ROLES =
+ private static final String ROLES =
ROOT + ServletContainer.roles";
private MyServletContainer m_container;
@@ -54,7 +70,7 @@
try
{
final FortressConfig config = new FortressConfig();
- config.setContainerClass(
+ config.setContainerClass(
"org.apache.avalon.fortress.examples.servlet.ServletContainer" );
config.setContextDirectory( "./" );
config.setWorkDirectory( "./" );
@@ -62,11 +78,11 @@
config.setLoggerManagerConfiguration( XLOG );
config.setRoleManagerConfiguration( ROLES );
- m_containerManager =
+ m_containerManager =
new DefaultContainerManager( config.getContext() );
ContainerUtil.initialize(m_containerManager);
- m_container =
+ m_container =
(ServletContainer)m_containerManager.getContainer();
}
catch( Exception e )
@@ -102,8 +118,8 @@
ContainerUtil.dispose(m_containerManager);
}
}
- ]]>
- </source>
- </section>
- </body>
+ ]]>
+ </source>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/fortress/swing.xml
==============================================================================
--- excalibur/trunk/site/xdocs/fortress/swing.xml (original)
+++ excalibur/trunk/site/xdocs/fortress/swing.xml Wed Jun 23 02:32:50 2004
@@ -1,22 +1,38 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
- <properties>
- <title>Fortress Getting Started</title>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- </properties>
-
- <body>
- <section name="Swing Based Applications">
- <p>
+ <properties>
+ <title>Fortress Getting Started</title>
+
+ </properties>
+
+ <body>
+ <section name="Swing Based Applications">
+ <p>
Swing applications are those applications that have a lovely graphical
interface for you to interact with. When you are done with the
application, you close it and are done with it. Some examples of a
Swing based application include Apache JMeter, JEdit, and Avalon
Instrument Client.
- </p>
- <p>
+ </p>
+ <p>
Swing applications are very similar to CLI based applications in the
way they are set up and torn down. What differs is that the GUI runs
in a different set of threads, so the main routine has to wait until
@@ -25,14 +41,14 @@
based JFrame and implement the Runnable interface. The second is to
manage the Swing GUI separately, but give your container or its
ServiceManager to the Swing code to interact with.
- </p>
- <subsection name="Extending DefaultContainer">
- <p>
+ </p>
+ <subsection name="Extending DefaultContainer">
+ <p>
If we extend the DefaultContainer, our main method will look pretty
much the same:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
public int main(String [] args)
{
// You would have to implement the referenced method here...
@@ -46,16 +62,16 @@
// Clean up after ourselves
ContainerUtil.dispose( cm );
}
- ]]>
- </source>
- <p>
+ ]]>
+ </source>
+ <p>
The extensions to DefaultContainer that you do are different for
each application. However, they will have some common elements.
Here is an excerpt from both the Swing example and the Viewer
example included in CVS.
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
public class MySwingContainer extends DefaultContainer implements Runnable
{
JFrame m_frame = new JFrame();
@@ -81,9 +97,9 @@
}
}
}
- ]]>
- </source>
- </subsection>
- </section>
- </body>
+ ]]>
+ </source>
+ </subsection>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/fortress/using-meta-info.xml
==============================================================================
--- excalibur/trunk/site/xdocs/fortress/using-meta-info.xml (original)
+++ excalibur/trunk/site/xdocs/fortress/using-meta-info.xml Wed Jun 23 02:32:50 2004
@@ -1,11 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
- <properties>
- <title>Excalibur Fortress - Using Meta Info</title>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- </properties>
+ <properties>
+ <title>Excalibur Fortress - Using Meta Info</title>
+
+ </properties>
<body>
<section name="What is Meta Information?">
@@ -75,7 +91,8 @@
used to choose how this component is managed.
</p>
<p>
- Dependencies are declared in the <code>service()</code> method for the component.
+ 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:
@@ -152,10 +169,18 @@
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>
+ <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>
Modified: excalibur/trunk/site/xdocs/i18n.xml
==============================================================================
--- excalibur/trunk/site/xdocs/i18n.xml (original)
+++ excalibur/trunk/site/xdocs/i18n.xml Wed Jun 23 02:32:50 2004
@@ -1,25 +1,25 @@
<?xml version="1.0"?>
-<!--
- Copyright 2004 The Apache Software Foundation
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied.
-
- See the License for the specific language governing permissions and
- limitations under the License.
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
-->
<document>
<properties>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- <title>Excalibur i18n</title>
+ <title>i18n</title>
</properties>
<body>
@@ -27,26 +27,26 @@
<section name="Excalibur i18n">
<subsection name="Overview">
- <p>
+ <p>
Excalibur's Internationalization package is found in
- <code>org.apache.avalon.excalibur.i18n</code>. Avalon
+ <code>org.apache.avalon.excalibur.i18n</code>. Avalon
Excalibur includes a method of managing resources, and
an interface for specifying the resource. Support for
XML resource bundles are still under development.
- </p>
+ </p>
</subsection>
- <subsection name="Usage">
- <p>
+ <subsection name="Usage">
+ <p>
Using the i18n code is really straightforward; several
examples of internationalized applications exist within
the Avalon application family.
- </p>
- <p>
+ </p>
+ <p>
The following code is an example of the usage of the
i18n package.
- </p>
- <source>
+ </p>
+ <source>
// in a file called src/java/MyClass.java
import org.apache.avalon.excalibur.i18n.ResourceManager;
@@ -74,24 +74,24 @@
# in a file called src/java/Resources.properties
myclass.error.dostuff.bad-argument=the argument passed to the \
doStuff method is invalid; it is {0}, which is plain silly!
- </source>
+ </source>
- <p>
+ <p>
That's basically all there is to it. If you follow this
pattern consistently, it will be extremely easy to i18n
your application by just putting in place a different
Resources.properties.
- </p>
- <p>
+ </p>
+ <p>
This i18n package is, indeed, a trivial wrapper around
the built-in i18n features java has using ResourceBundles
and the like. See the java api docs for
- <a href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/ResourceBundle.html">ResourceBundle</a>
+ <a href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/ResourceBundle.html">ResourceBundle</a>
to learn more about i18n, and take a look at the javadoc
for Resources and ResourceManager to see which options
are available.
- </p>
- </subsection>
+ </p>
+ </subsection>
</section>
</body>
Modified: excalibur/trunk/site/xdocs/index.xml
==============================================================================
--- excalibur/trunk/site/xdocs/index.xml (original)
+++ excalibur/trunk/site/xdocs/index.xml Wed Jun 23 02:32:50 2004
@@ -1,16 +1,31 @@
<?xml version="1.0"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
-
+
<properties>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- <title>Excalibur i18n</title>
+ <title>Front Page</title>
</properties>
-
+
<body>
-
+
<section name="Excalibur">
-
+
<subsection name="Overview">
<p>
The Excalibur Project contains a set of utilitiy projects
@@ -21,13 +36,24 @@
</subsection>
<subsection name="Index">
<table>
- <tr><th>Package</th><th>Description</th></tr>
- <tr><td><a href="configuration/index.html">Configuration</a></td><td>
+ <tr>
+ <th>Package</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>
+ <a href="configuration/index.html">Configuration</a>
+ </td>
+ <td>
<p>
The Configuration package contains extensions to the Avalon Framework
supporting configuration management.
- </p></td></tr>
- <tr><td>Datasource</td><td>
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>Datasource</td>
+ <td>
<p>
Avalon Excalibur's DataSource package in
<code>org.apache.avalon.excalibur.datasource</code> allows you
@@ -37,8 +63,11 @@
regardless of which method you choose--since they are obtained
through Avalon's Component Manager infrastructure.
</p>
- </td></tr>
- <tr><td>Event</td><td>
+ </td>
+ </tr>
+ <tr>
+ <td>Event</td>
+ <td>
<p>
This is the Excalibur Event package which includes event queues,
asynchronous command processing, and the interfaces to support
@@ -49,16 +78,25 @@
event processing. From there we cleaned up the API and made it as
generic as we could.
</p>
- </td></tr>
- <tr><td><a href="i18n/index.html">i18n</a></td><td>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="i18n/index.html">i18n</a>
+ </td>
+ <td>
<p>
Excalibur's Internationalization package is found in
<code>org.apache.avalon.excalibur.i18n</code>. Avalon
Excalibur includes a method of managing resources, and
an interface for specifying the resource. Support for
XML resource bundles are still under development.
- </p></td></tr>
- <tr><td>Instrumentation</td><td>
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>Instrumentation</td>
+ <td>
<p>
Excalibur Instrument is an instrumentation utility that allows you
to attach a separate JVM to your running application to determine its
@@ -67,13 +105,19 @@
digest. Excalibur Instrumentation is such a package that you can use
for your Avalon based projects.
</p>
- </td></tr>
- <tr><td>Lifecycle</td><td>
+ </td>
+ </tr>
+ <tr>
+ <td>Lifecycle</td>
+ <td>
<p>The Lifecycle package contains a set of interfaces and classes supporting portable lifecycle extensions.</p>
-
+
<p>Contributions to this project are based on co-development actives by container projects aiming towards cross-container component portability and consistent service management.</p>
- </td></tr>
- <tr><td>Logger</td><td>
+ </td>
+ </tr>
+ <tr>
+ <td>Logger</td>
+ <td>
<p>
Find Avalon Excalibur's Log Management System in the
<code>org.apache.avalon.excalibur.logger</code> package.
@@ -82,10 +126,15 @@
be able to define the log categories on a component basis by
specifying a 'logger' attribute which denotes the log category
to use for a particular component (given the
- component is <code>LogEnabled</code> or <code>Loggable</code>).
+ component is
+ <code>LogEnabled</code> or
+ <code>Loggable</code>).
</p>
- </td></tr>
- <tr><td>Monitor</td><td>
+ </td>
+ </tr>
+ <tr>
+ <td>Monitor</td>
+ <td>
<p>
Avalon Excalibur's resource management code allows you to
be notified when a resource has changed. There are two
@@ -100,8 +149,11 @@
program will be notified when the change occurs instead of
constantly polling it.
</p>
- </td></tr>
- <tr><td>Pool</td><td>
+ </td>
+ </tr>
+ <tr>
+ <td>Pool</td>
+ <td>
<p>
Find Avalon Excalibur's Pool implementations in the
<code>org.apache.avalon.excalibur.pool</code> package.
@@ -110,8 +162,13 @@
used resources at all, or limiting the used resources
based on specific rules.
</p>
- </td></tr>
- <tr><td><a href="sourceresolve-index.html">Sourceresolver</a></td><td>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="sourceresolve-index.html">Sourceresolver</a>
+ </td>
+ <td>
<p>
A very common problem is resolving a source, which means
finding a source using a URI.
@@ -125,17 +182,28 @@
in the same way, like dealing with custom, self-build
protocols such as myxmldatabase://root/documents/test.xml.
</p>
- </td></tr>
- <tr><td><a href="store-index.html">Store</a></td><td>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="store-index.html">Store</a>
+ </td>
+ <td>
<p>
The Store Package provides a way to store named objects without
taking care about where and how they are stored.
You can choose between different implementations that store
the data e.g. in memory or on the file system etc.
</p>
- </td></tr>
- <tr><td>Thread</td><td>PENDING</td></tr>
- <tr><td>XMLUtil</td><td>
+ </td>
+ </tr>
+ <tr>
+ <td>Thread</td>
+ <td>PENDING</td>
+ </tr>
+ <tr>
+ <td>XMLUtil</td>
+ <td>
<p>
Excalibur's XML Utilities provide simplified wrappers
for XML parsers, transformers and XPath evaluators. It
@@ -143,13 +211,18 @@
constructing a pipeline of XML components by defining interfaces
for consuming and producing XML in either SAX or DOM formats.
</p>
- </td></tr>
+ </td>
+ </tr>
</table>
</subsection>
<subsection name="Depricated">
<table>
- <tr><th>Package</th><th>Description</th></tr>
- <tr><td>Compatability</td>
+ <tr>
+ <th>Package</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>Compatability</td>
<td>
<p>
Avalon is minimizing the number of projects and utilities it maintains
@@ -163,7 +236,11 @@
</p>
</td>
</tr>
- <tr><td><a href="component.html">Component</a></td><td>
+ <tr>
+ <td>
+ <a href="component.html">Component</a>
+ </td>
+ <td>
<p>
Due to a number of issues in ECM, not the least of which is a
simplistic and convoluted design, it has been deprecated in
@@ -172,11 +249,12 @@
it easier to migrate forward. This project will be maintained
for bug fixes only.
</p>
- </td></tr>
+ </td>
+ </tr>
</table>
</subsection>
</section>
-
+
</body>
-
+
</document>
Added: excalibur/trunk/site/xdocs/jira.xml
==============================================================================
--- (empty file)
+++ excalibur/trunk/site/xdocs/jira.xml Wed Jun 23 02:32:50 2004
@@ -0,0 +1,57 @@
+<?xml version="1.0"?>
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document>
+
+ <properties>
+ <title>Issue Tracking</title>
+ </properties>
+
+ <body>
+
+ <section name="What is JIRA?">
+ <p>
+ JIRA is an issue and bug tracker. The Excalibur team uses JIRA to keep track of all
+ of our open tasks and changelog data.
+ </p>
+ </section>
+ <section name="Who can use it?">
+ <p>
+ Anyone. Anyone can create an account and enter or update issues, bug reports, and
+ feature requests.
+ </p>
+ </section>
+ <section name="Where is it?">
+ <p>
+ Apache Excalibur uses the following
+ <a href="http://issues.apache.org/jira">ASF JIRA</a> modules:
+ </p>
+ <ul>
+ <li><a href="http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10428">Excalibur Components</a></li>
+ <li><a href="http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10420">Excalibur Fortress</a></li>
+ </ul>
+
+ <p>
+ You can browse these modules to see the current status of the project or to enter
+ new issues.
+ </p>
+ </section>
+
+ </body>
+
+</document>
Modified: excalibur/trunk/site/xdocs/lifecycle/extension.xml
==============================================================================
--- excalibur/trunk/site/xdocs/lifecycle/extension.xml (original)
+++ excalibur/trunk/site/xdocs/lifecycle/extension.xml Wed Jun 23 02:32:50 2004
@@ -15,198 +15,221 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Lifecycle Extensions</title>
- </properties>
- <body>
- <section name="What are lifecycle extensions ?" >
- <p>
+ <properties>
+ <title>Lifecycle Extensions</title>
+ </properties>
+ <body>
+ <section name="What are lifecycle extensions ?">
+ <p>
Lifecycle extensions are additional stages a component can traverse through during
it's lifetime. Lifecycle extensions allow a container to provide extra functionality
to components in addition to the standard stages defined by Avalon Framework.
- </p>
+ </p>
- <p>
+ <p>
Avalon Framework defines a set of standard interfaces often termed as Lifecycle
stages that can be used by a container to determine the components requirements
during deployment and subsequent decommissioning.
- </p>
+ </p>
- <p>
+ <p>
These interfaces allows the developer to separate the various concerns involved when
writing a component. Often termed SoC and IoC (Separation of Concerns and Inversion of
Control), these concepts represent one of the primary advantages of using Avalon.
- </p>
+ </p>
- <p>
+ <p>
Sometimes it's useful to extend this development paradigm from the framework level
into the application domain, to create customized lifecycle extensions that are called
upon in addition to the standard set defined by the Avalon Framework.
- </p>
+ </p>
- <p>
+ <p>
Such custom lifecycle stages can further enable domain specific logic across many,
perhaps even unrelated components, can reduce code duplication, and allows the developer
to reuse the same development and thinking paradigm as the standard lifecycle stages.
- </p>
+ </p>
- <p>
+ <p>
For example, you might want to pass a specialized SecurityManager to some of your
components before they are initialized, or have their internal state persistently cached
during system shutdown and restored at during startup. You might want to pass user
dependent decryption keys to your component, or give components the opportunity to
recycle themselves before being disposed or returned to a pooled component handler.
- </p>
+ </p>
- <p>
+ <p>
The possibilities and number of extensions are only limited by the requirements of your
particular application domain.
- </p>
+ </p>
- <p>
- This document describes how to add new lifecycle extensions using <strong>Fortress</strong>
- and <strong>Merlin</strong> containers.
+ <p>
+ This document describes how to add new lifecycle extensions using
+ <strong>Fortress</strong>
+ and
+ <strong>Merlin</strong> containers.
This document assumes a knowledge of what an Avalon lifecycle is, and a basic understanding
of the standard lifecycle interfaces Avalon Framework defines. References in this document to
Service and ServiceManager can also be freely interpreted as Component and ComponentManager
by the reader.
- </p>
+ </p>
- <note>As at the time of writing, Fortress and Merlin is the only Avalon container that
+ <note>As at the time of writing, Fortress and Merlin is the only Avalon container that
supports lifecycle extensions, which means components that use this feature will not work
with the other Avalon containers (ExcaliburComponentManager, Phoenix, Tweety, etc)</note>
- <p>
+ <p>
Support for lifecycle extensions in the other Avalon containers is technically possible but
has not yet been discussed. Please check with the Avalon developer mailing list if you use
one of these containers and would like to use lifecycle extensions.
- </p>
+ </p>
- </section>
+ </section>
- <section name="How do I extend a Component's lifecycle ?" >
- <p>
+ <section name="How do I extend a Component's lifecycle ?">
+ <p>
Extending a Component's lifecycle is straightforward. An overview of the process
follows:
- </p>
+ </p>
- <ol>
- <li>Define the new component interface
+ <ol>
+ <li>Define the new component interface
- <br/><br/>
+ <br/>
+ <br/>
Create the new interface defining the operations that should be called upon components
that implement this interface. Using the previously mentioned examples, this would be
- your <code>SecurityManageable</code>, <code>Cacheable</code>, <code>Decryptable</code>,
- <code>Recycleable</code> interfaces.
- </li>
+ your
+ <code>SecurityManageable</code>,
+ <code>Cacheable</code>,
+ <code>Decryptable</code>,
+ <code>Recycleable</code> interfaces.
+ </li>
- <li>Define an extension object that calls upon the methods defined in the new interface,
+ <li>Define an extension object that calls upon the methods defined in the new interface,
during one or more of the pre-defined phases of component's lifecycle
- <br/><br/>
- Create a class that implements the <code>Creator</code> and/or <code>Accessor</code>
+ <br/>
+ <br/>
+ Create a class that implements the
+ <code>Creator</code> and/or
+ <code>Accessor</code>
interfaces and implemets the interaction with target components supplied under the
create, destroy, access and relase operations.
- </li>
+ </li>
- <li>Register your extension object
+ <li>Register your extension object
- <br/><br/>
+ <br/>
+ <br/>
This depends on the container you are using. In
Merlin you need to include the <extensions> tag in the component .xinfo file and
Merlin will automatically recognize it. In Fortress you register the extension object
- with a <code>LifecycleExtensionManager</code>
- </li>
-
- <li>Implement the new component interface on your component
- <br/><br/>
+ with a
+ <code>LifecycleExtensionManager</code>
+ </li>
+
+ <li>Implement the new component interface on your component
+ <br/>
+ <br/>
- Add the new <code>implements</code> clause to your Component, or Component implementation,
+ Add the new
+ <code>implements</code> clause to your Component, or Component implementation,
and write any methods defined in the implemented interface.
- <br/><br/>
+ <br/>
+ <br/>
Proceed as normal. Checking for extensions is done implicitly within both Fortress and
Merlin. Once lifecycle extensions are registered they will be activated during the 4
phases defined later in this document.
- </li>
- </ol>
- </section>
+ </li>
+ </ol>
+ </section>
- <section name="When can a Component's lifecycle be extended ?" >
- <p>
+ <section name="When can a Component's lifecycle be extended ?">
+ <p>
The life of any component can be broken down to the following phases:
- </p>
+ </p>
- <ol>
- <li>Creation
+ <ol>
+ <li>Creation
- <br/><br/>
+ <br/>
+ <br/>
When the component is instantiated.
- </li>
+ </li>
- <li>Access
+ <li>Access
- <br/><br/>
+ <br/>
+ <br/>
When the component is accessed via a ServiceManager/Selector
- (<code>lookup()/select()</code>).
- </li>
-
- <li>Release
+ (
+ <code>lookup()/select()</code>).
+ </li>
+
+ <li>Release
+
+ <br/>
+ <br/>
+ When the component is released via a ServiceManager/Selector (
+ <code>release()</code>).
+ </li>
- <br/><br/>
- When the component is released via a ServiceManager/Selector (<code>release()</code>).
- </li>
+ <li>Destruction
- <li>Destruction
-
- <br/><br/>
+ <br/>
+ <br/>
When the component is decommissioned, ready for garbage collection.
-
- </li>
- </ol>
+ </li>
+
+ </ol>
- <note>A component will go through it's Creation and Destruction phase only once. Since
+ <note>A component will go through it's Creation and Destruction phase only once. Since
extension classes can implement different handling strategies (Poolable, ThreadSafe,
etc), the access and release phases of a component can be applied multiple times.</note>
- <p>
+ <p>
Lifecycle extensions can be added to any of the above defined phases. This allows
you to control the interception point your particular extension will be applied under.
- </p>
+ </p>
- <p>
+ <p>
For example, thread or user dependent extensions would be added at the access and release
levels (ie. when the component is retrieved and returned to the ServiceManager) as they
depend on runtime data not available until they are actually used.
- </p>
+ </p>
- <p>
+ <p>
More static, or global extensions would be added at the creation or destruction level, since
they do not depend on any external data that change during runtime, nor are they particular
to any one context of use.
- </p>
+ </p>
- </section>
+ </section>
- <section name="Lifestyle Extension Interfaces" >
+ <section name="Lifestyle Extension Interfaces">
- <p>
+ <p>
A container manages extensions using an extension handler. Handlers may implement
- the <code>Creator</code> and/or <code>Accessor</code> interfaces. A creator extension
+ the
+ <code>Creator</code> and/or
+ <code>Accessor</code> interfaces. A creator extension
will be activated during the create and destroy stages of a component lifecycle. A
accessor extension will be activated during the access and release stages.
- </p>
+ </p>
- <section name="The Creator Interface" >
+ <section name="The Creator Interface">
-<p>The <code>Creator</code> interface describes the create and destroy
+ <p>The
+ <code>Creator</code> interface describes the create and destroy
stages that occur between a component and a container
during service management. Lifecycle extensions supporting create
-and destroy stages must implement this interface.</p>
+and destroy stages must implement this interface.
+ </p>
- <source>
+ <source>
package org.apache.avalon.lifecycle;
import org.apache.avalon.framework.context.Context;
@@ -234,17 +257,18 @@
void destroy( Object object, Context context );
}
- </source>
- </section>
+ </source>
+ </section>
- <section name="Accessor Interface" >
-<p>
-The <code>Accessor</code> interface describes the access and release
+ <section name="Accessor Interface">
+ <p>
+The
+ <code>Accessor</code> interface describes the access and release
stages that occur between a service or component manager and a container
during service deployment. Lifecycle extensions supporting access
and release stages must implement this interface.
-</p>
-<source>
+ </p>
+ <source>
package org.apache.avalon.lifecycle;
import org.apache.avalon.framework.context.Context;
@@ -272,16 +296,17 @@
void release( Object object, Context context );
}
-</source>
- </section>
- </section>
+ </source>
+ </section>
+ </section>
- <section name="Need more information ?" >
- <p>
+ <section name="Need more information ?">
+ <p>
If you have any particular questions, comments, etc, please send an email to the Avalon
- developer mailing <a href="mailto:dev@avalon.apache.org">list</a>.
- </p>
- </section>
+ developer mailing
+ <a href="mailto:dev@avalon.apache.org">list</a>.
+ </p>
+ </section>
- </body>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/lifecycle/fortress.xml
==============================================================================
--- excalibur/trunk/site/xdocs/lifecycle/fortress.xml (original)
+++ excalibur/trunk/site/xdocs/lifecycle/fortress.xml Wed Jun 23 02:32:50 2004
@@ -15,30 +15,31 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Fortress Lifecycle Extensions</title>
- </properties>
- <body>
- <section name="Example" >
+ <properties>
+ <title>Fortress Lifecycle Extensions</title>
+ </properties>
+ <body>
+ <section name="Example">
- <p>
+ <p>
Let's look at a simple example. The following is also available as a working sample
in Fortress' examples directory.
- </p>
+ </p>
- <p>
- Our example implements a Lifecycle extension for passing a <code>SecurityManager</code> to
- Components. We'll call it the <code>SecurityManageable</code> interface.
- </p>
+ <p>
+ Our example implements a Lifecycle extension for passing a
+ <code>SecurityManager</code> to
+ Components. We'll call it the
+ <code>SecurityManageable</code> interface.
+ </p>
- <section name="Define the component extension interface" >
+ <section name="Define the component extension interface">
- <p>
+ <p>
First we define the new Component extension interface.
- </p>
+ </p>
- <source>
+ <source>
/**
* Simple custom lifecycle extension interface for supplying a component
* with a security manager.
@@ -53,21 +54,23 @@
void secure( SecurityManager manager )
throws SecurityException;
}
- </source>
+ </source>
- </section>
+ </section>
- <section name="Create the lifecycle extensions class" >
+ <section name="Create the lifecycle extensions class">
- <p>
- Next we define the actual extension implementation which invokes the <code>secure()</code>
- method. We extend from <code>AbstractAccessor</code> since we only want
- <code>secure()</code> to be invoked upon each access (ie. lookup()) to the component, and
+ <p>
+ Next we define the actual extension implementation which invokes the
+ <code>secure()</code>
+ method. We extend from
+ <code>AbstractAccessor</code> since we only want
+ <code>secure()</code> to be invoked upon each access (ie. lookup()) to the component, and
don't need to implement the other 3 LifecycleExtension methods (create, release, and
destroy).
- </p>
+ </p>
- <source>
+ <source>
/**
* Some custom extensions for this container's components.
*/
@@ -93,28 +96,30 @@
}
}
}
- </source>
+ </source>
- <note>An extension class may run components through any given number of
+ <note>An extension class may run components through any given number of
extensions, and are not limited to just one.</note>
- </section>
+ </section>
- <section name="Register the lifecycle extensions class" >
+ <section name="Register the lifecycle extensions class">
- <p>
+ <p>
We then inform our container about the extension. This could be done in several different
- ways, for simplicity we'll extend <code>initialize()</code> and add it to the
- <code>LifecycleExtensionManager</code> there.
- </p>
+ ways, for simplicity we'll extend
+ <code>initialize()</code> and add it to the
+ <code>LifecycleExtensionManager</code> there.
+ </p>
- <p>
+ <p>
(an alternative might be to initialize a LifecycleExtensionManager before creating the
- container and pass it in via the <code>FortressConfig.setExtensionManager()</code> method,
+ container and pass it in via the
+ <code>FortressConfig.setExtensionManager()</code> method,
or to create a LifecycleExtensionManager subclass that includes the extension preset)
- </p>
+ </p>
- <source>
+ <source>
/**
* Simple container that includes custom lifecycle extensions.
*/
@@ -129,19 +134,20 @@
m_extManager.addExtension( new Extensions() );
}
}
- </source>
+ </source>
- </section>
+ </section>
- <section name="Use the new component interface" >
+ <section name="Use the new component interface">
- <p>
+ <p>
To use the new SecurityManageable lifecycle extension, we simply implement
SecurityManageable just as we do with any other Avalon lifecycle interfaces
- (assuming a predefined Component interface <code>ExtendedComponent</code>).
- </p>
+ (assuming a predefined Component interface
+ <code>ExtendedComponent</code>).
+ </p>
- <source>
+ <source>
/**
* ExtendedComponentImpl, demonstrating the use of a custom
* lifecycle stage SecurityManageable. This code does
@@ -178,10 +184,10 @@
}
}
}
- </source>
- </section>
+ </source>
+ </section>
- </section>
+ </section>
- </body>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/lifecycle/index.xml
==============================================================================
--- excalibur/trunk/site/xdocs/lifecycle/index.xml (original)
+++ excalibur/trunk/site/xdocs/lifecycle/index.xml Wed Jun 23 02:32:50 2004
@@ -15,25 +15,24 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Lifecycle Extensions</title>
- </properties>
- <body>
- <section name="Introduction" >
+ <properties>
+ <title>Lifecycle Extensions</title>
+ </properties>
+ <body>
+ <section name="Introduction">
- <p>
+ <p>
The Lifecycle package contains a set of interfaces and classes
supporting portable lifecycle extensions.
- </p>
+ </p>
- <p>
+ <p>
Contributions to this project are based on co-development actives by
container projects aiming towards cross-container component portability
and consistent service management.
- </p>
+ </p>
- <p>
+ <p>
The first step in the container project has been undertaken between the
Fortress and Merlin containers on the subject of lifestyle extension
support. The original design and implementation of lifecycle extensions
@@ -45,11 +44,11 @@
consensus on a common set of APIs and abstract implementation. These
resources constitute the first sub-project of the Excalibur Container
package.
- </p>
+ </p>
- </section>
+ </section>
- </body>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/lifecycle/interfaces.xml
==============================================================================
--- excalibur/trunk/site/xdocs/lifecycle/interfaces.xml (original)
+++ excalibur/trunk/site/xdocs/lifecycle/interfaces.xml Wed Jun 23 02:32:50 2004
@@ -15,31 +15,33 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Extension Interfaces</title>
- </properties>
- <body>
- <section name="Lifestyle Extension Interfaces" >
+ <properties>
+ <title>Extension Interfaces</title>
+ </properties>
+ <body>
+ <section name="Lifestyle Extension Interfaces">
- <p>
+ <p>
A container manages extensions using an extension handler. Handlers
- may implement the <code>Creator</code> and/or <code>Accessor</code>
+ may implement the
+ <code>Creator</code> and/or
+ <code>Accessor</code>
interfaces. A creator extension will be activated during the create and
destroy stages of a component lifecycle. A accessor extension will be
activated during the access and release stages.
- </p>
+ </p>
- <section name="The Creator Interface" >
+ <section name="The Creator Interface">
- <p>
- The <code>Creator</code> interface describes the create and destroy
+ <p>
+ The
+ <code>Creator</code> interface describes the create and destroy
stages that occur between a component and a container
during service management. Lifecycle extensions supporting create
and destroy stages must implement this interface.
- </p>
+ </p>
- <source>
+ <source>
package org.apache.avalon.lifecycle;
import org.apache.avalon.framework.context.Context;
@@ -67,17 +69,18 @@
void destroy( Object object, Context context );
}
- </source>
- </section>
+ </source>
+ </section>
- <section name="Accessor Interface" >
- <p>
- The <code>Accessor</code> interface describes the access and release
+ <section name="Accessor Interface">
+ <p>
+ The
+ <code>Accessor</code> interface describes the access and release
stages that occur between a service or component manager and a
container during service deployment. Lifecycle extensions supporting
access and release stages must implement this interface.
- </p>
-<source>
+ </p>
+ <source>
package org.apache.avalon.lifecycle;
import org.apache.avalon.framework.context.Context;
@@ -105,8 +108,8 @@
void release( Object object, Context context );
}
-</source>
- </section>
- </section>
- </body>
+ </source>
+ </section>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/lifecycle/merlin.xml
==============================================================================
--- excalibur/trunk/site/xdocs/lifecycle/merlin.xml (original)
+++ excalibur/trunk/site/xdocs/lifecycle/merlin.xml Wed Jun 23 02:32:50 2004
@@ -15,22 +15,26 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Lifecycle Extensions</title>
- </properties>
- <body>
- <section name="Example" >
+ <properties>
+ <title>Merlin Lifecycle Extensions</title>
+ </properties>
+ <body>
+ <section name="Outdated content">
+ <p>
+ <b>Merlin no longer uses the excalibur-lifecycle package.</b>
+ </p>
+ </section>
+ <section name="Example">
- <section name="Create your lifestyle stage interface" >
+ <section name="Create your lifestyle stage interface">
- <p>
+ <p>
The following interface is your domain specific lifecycle stage
interface. It is the interface that an extension handler will use to
interact with your component during deployment and decommissioning.
- </p>
+ </p>
- <source>
+ <source>
public interface Exploitable
{
/**
@@ -39,12 +43,12 @@
*/
void exploit( String message );
}
- </source>
+ </source>
- </section>
+ </section>
- <section name="Create the lifestyle extension handler" >
- <p>
+ <section name="Create the lifestyle extension handler">
+ <p>
An extension handler is the implementation class that will be
activated by the Merlin container to handle domain specific tasks
during the deployment and decommissioning phases. The extension can
@@ -52,8 +56,8 @@
depeding on the particular extension requirements. IN this example we
are defining a simple creation stage handler that supplies a message
to an instance of Exploitable.
- </p>
- <source>
+ </p>
+ <source>
public class ExploitationManager implements Creator
{
/**
@@ -80,41 +84,41 @@
{
}
}
- </source>
- <p>
+ </source>
+ <p>
To complete the defintion of you extension handler you need to prepare
the meta-info that will be used by Merlin to identify the extension
and the stage interface is supports. The following <type/>
- declaration includes an <extensions/> tag that contains a
- <reference/> element that includes the reference to the
+ declaration includes an <extensions/> tag that contains a
+ <reference/> element that includes the reference to the
Exploitable lifecycle stage interface. This is the key that Merlin
uses to associate a handler with a component. If you extension class
requires any specific context values, they should be declared in a
context element within the extension element.
- </p>
+ </p>
- <source>
-<type>
+ <source>
+ <type>
- <info>
- <name>my-extension-handler</name>
- </info>
+ <info>
+ <name>my-extension-handler</name>
+ </info>
- <extensions>
- <extension>
- <name>exploitation</name>
- <reference type="Exploitable" version="1.0"/>
- </extension>
- </extensions>
+ <extensions>
+ <extension>
+ <name>exploitation</name>
+ <reference type="Exploitable" version="1.0"/>
+ </extension>
+ </extensions>
-</type>
+ </type>
- </source>
+ </source>
- </section>
+ </section>
- <section name="Create a component implementing the stage interface" >
- <source>
+ <section name="Create a component implementing the stage interface">
+ <source>
public class MyComponent extends AbstractLogEnabled implements Exploitable
{
/**
@@ -126,9 +130,9 @@
getLogger().info( message );
}
}
- </source>
+ </source>
- <p>
+ <p>
To complete the defintion of your component you need to prepare the
meta-info that will be used by Merlin to identify the stage interface
is requires a handler for. The following <type/> declaration
@@ -136,36 +140,36 @@
element that includes the reference to the Exploitable lifecycle stage
interface. This is the key that Merlin uses to associate the component
with a handler capable of handling the Exploitable interface.
- </p>
+ </p>
- <source>
-<type>
+ <source>
+ <type>
- <info>
- <name>my-component</name>
- </info>
+ <info>
+ <name>my-component</name>
+ </info>
- <stages>
- <stage>
- <name>exploit-me</name>
- <reference type="Exploitable" version="1.0"/>
- </stage>
- </stages>
+ <stages>
+ <stage>
+ <name>exploit-me</name>
+ <reference type="Exploitable" version="1.0"/>
+ </stage>
+ </stages>
-</type>
+ </type>
- </source>
- </section>
+ </source>
+ </section>
- <section name="Register you component and the extension" >
+ <section name="Register you component and the extension">
- <p>
+ <p>
To complete the process you need to declare your handler and component
in a jar manifest file. The following entries show the declaration of
the component and the extension handler.
- </p>
+ </p>
- <source>
+ <source>
Manifest-Version: 1.0
Created-By: Ant 1.5
@@ -174,41 +178,41 @@
Name: ExploitationManager.class
Avalon: Type
- </source>
+ </source>
- </section>
+ </section>
- <section name="Execute the example" >
+ <section name="Execute the example">
- <p>
+ <p>
To execute the example you simply need to include a reference to you
component within a Merlin container declaration. The following XML
source declares a Merlin kernel, container, and component. You don't
need to include the handler because Merlin can sort that out itself
based on the information supplied in the meta-info declarations.
- </p>
+ </p>
- <source>
- <kernel>
+ <source>
+ <kernel>
- <container name="my-container>
+ <container name="my-container>
- <classpath>
- <fileset dir="lib">
- <include name="my-domo.jar"/>
- </fileset>
- </classpath>
+ <classpath>
+ <fileset dir="lib">
+ <include name="my-domo.jar"/>
+ </fileset>
+ </classpath>
- <component name="demo" class="MyComponent" activation="startup"/>
+ <component name="demo" class="MyComponent" activation="startup"/>
- <container>
+ <container>
- </kernel>
- </source>
+ </kernel>
+ </source>
- </section>
+ </section>
- </section>
+ </section>
- </body>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/lifecycle/navigation.xml
==============================================================================
--- excalibur/trunk/site/xdocs/lifecycle/navigation.xml (original)
+++ excalibur/trunk/site/xdocs/lifecycle/navigation.xml Wed Jun 23 02:32:50 2004
@@ -1,44 +1,86 @@
<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<project>
- <title>Avalon Sandbox</title>
+ <title>Apache Excalibur</title>
- <body>
+ <body>
- <links>
- <item name="Apache" href="http://apache.org/"/>
- <item name="Avalon" href="http://avalon.apache.org/"/>
- <item name="Framework" href="http://avalon.apache.org/product/framework/"/>
- <item name="Merlin" href="http://avalon.apache.org/product/containers/"/>
- <item name="Planet" href="http://avalon.apache.org/product/components/"/>
- </links>
-
- <menu name="About Excalibur">
- <item name="Overview" href="/index.html"/>
- <item name="Configuration" href="configuration.html"/>
- <item name="I18N" href="i18n/index.html"/>
- <item name="Sourceresolver" href="sourceresolve-index.html"/>
- <item name="Store" href="store-index.html"/>
- <item name="ECM" href="component.html"/>
- <item name="Event" href="event/index.html"/>
- <item name="Fortress" href="fortress/index.html"/>
- <item name="I18N" href="i18n.html"/>
- <item name="Logger" href="logger.html"/>
- <item name="Lifecycle" href="lifecycle/index.html">
- <item name="Overview" href="lifecycle/index.html"/>
- <item name="Extensions" href="lifecycle/extension.html"/>
- <item name="Interfaces" href="lifecycle/interfaces.html"/>
- <item name="Tutorial" href="lifecycle/fortress.html"/>
- </item>
- <item name="Thread" href="thread.html"/>
- </menu>
-
- <menu name="Resources">
- <item name="Javadocs" href="http://avalon.apache.org/excalibur/api/"/>
- <item name="Download" href="http://avalon.apache.org/download.cgi"/>
- <item name="Where's my documentation???" href="/no-docs-available.html"/>
- </menu>
+ <links>
+ <item name="Apache" href="http://apache.org/"/>
+ <item name="Excalibur" href="http://excalibur.apache.org/"/>
+ <item name="Avalon-Framework" href="http://avalon.apache.org/product/framework/"/>
+ </links>
+
+ <menu name="Essentials">
+ <item name="Overview" href="/index.html"/>
+ <item name="Mailing Lists" href="/mail-lists.html"/>
+ <item name="Subversion" href="/svn.html"/>
+ <item name="Wiki" href="http://wiki.apache.org/excalibur/"/>
+ <item name="FAQ" href="http://wiki.apache.org/excalibur/FrequentlyAskedQuestions"/>
+ <item name="Javadocs" href="http://avalon.apache.org/excalibur/api/"/>
+ <item name="Download" href="http://avalon.apache.org/download.cgi"/>
+ <item name="Issue Tracking" href="/jira.html"/>
+ </menu>
+
+ <menu name="Component documentation">
+ <item name="Configuration" href="/configuration.html"/>
+ <item name="ECM" href="/component.html"/>
+ <item name="Event" href="event/index.html" collapse="true">
+ <item href="event/event.html" name="Event"/>
+ <item href="event/command.html" name="Command"/>
+ <item href="event/mpool.html" name="MPool"/>
+ <item href="event/util.html" name="Util"/>
+ <item href="event/event-howto.html" name="Use Event Queues"/>
+ <item href="event/command-howto.html" name="Use the Command Manager"/>
+ <item href="event/mpool-howto.html" name="Use MPool"/>
+ <item href="event/util-howto.html" name="Use System Util"/>
+ <item href="event/cpuparser-howto.html" name="Extend System Util"/>
+ </item>
+ <item name="Fortress" href="fortress/index.html" collapse="true">
+ <item name="Overview" href="fortress/index.html"/>
+ <item name="Features Oriented" href="fortress/features.html"/>
+ <item name="Getting Started" href="fortress/getting-started.html"/>
+ <item name="Using Meta Info" href="fortress/using-meta-info.html"/>
+ <item name="CLI" href="fortress/cli.html"/>
+ <item name="Swing" href="fortress/swing.html"/>
+ <item name="Servlet" href="fortress/servlet.html"/>
+ <item name="Lifecycle Extensions" href="fortress/lifecycle-extensions.html"/>
+ <item name="Design Notes" href="fortress/design-notes.html"/>
+ </item>
+ <item name="i18n" href="i18n.html"/>
+ <item name="Lifecycle" href="lifecycle/index.html" collapse="false">
+ <item name="Overview" href="lifecycle/index.html"/>
+ <item name="Extensions" href="lifecycle/extension.html"/>
+ <item name="Interfaces" href="lifecycle/interfaces.html"/>
+ <item name="Tutorial" href="lifecycle/fortress.html"/>
+ </item>
+ <item name="Logger" href="logger.html"/>
+ <item name="Sourceresolver" href="sourceresolve-index.html"/>
+ <item name="Store" href="store-index.html"/>
+ <item name="Thread" href="thread.html"/>
+ </menu>
+
+ <menu name="Miscellaneous">
+ <item name="Where's my documentation???" href="/no-docs-available.html"/>
+ </menu>
- </body>
+ </body>
</project>
Modified: excalibur/trunk/site/xdocs/logger.xml
==============================================================================
--- excalibur/trunk/site/xdocs/logger.xml (original)
+++ excalibur/trunk/site/xdocs/logger.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,55 +17,56 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Excalibur Logger - Overview</title>
- </properties>
- <body>
- <section name="Introduction" >
- <p>
+ <properties>
+ <title>Excalibur Logger - Overview</title>
+ </properties>
+ <body>
+ <section name="Introduction">
+ <p>
Find Avalon Excalibur's Log Management System in the
- <code>org.apache.avalon.excalibur.logger</code> package.
+ <code>org.apache.avalon.excalibur.logger</code> package.
Excalibur-Logger integrates neatly into the Avalon ECM
and Fortress. The main goal is to
be able to define the log categories on a component basis by
specifying a 'logger' attribute which denotes the log category
to use for a particular component (given the
- component is <code>LogEnabled</code> or <code>Loggable</code>).
- </p>
- </section>
- <section name="Not just for logkit" >
- <p>
+ component is
+ <code>LogEnabled</code> or
+ <code>Loggable</code>).
+ </p>
+ </section>
+ <section name="Not just for logkit">
+ <p>
Though the documentation doesn't reflect this accurately
yet (patches welcome), excalibur-logger has been updated
to support other logging toolkits like jdk1.4 logging and
log4j as well.
- </p>
- </section>
- <section name="Not just for ECM" >
- <p>
+ </p>
+ </section>
+ <section name="Not just for ECM">
+ <p>
Though the documentation doesn't reflect this accurately
yet (patches welcome), excalibur-logger is not just used
by (or usable by) ECM. Other containers can and do make
use of logger, too.
- </p>
- </section>
- <section name="Example configurations" >
- <p>
+ </p>
+ </section>
+ <section name="Example configurations">
+ <p>
Look at this example of a component definition:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
<component role="my.component.role" class="my.component.roleImpl"
logger="category.subcategory"/>
- ]]>
- </source>
- <p>
+ ]]>
+ </source>
+ <p>
And now let's have a look at a hypothetical Excalibur-Logger configuration
using Logkit:
- </p>
- <source>
- <![CDATA[
+ </p>
+ <source>
+ <![CDATA[
<?xml version="1.0"?>
<logkit>
@@ -109,175 +112,202 @@
</category>
</categories>
</logkit>
- ]]>
- </source>
- <p>
+ ]]>
+ </source>
+ <p>
As you've seen the configuration file for excalibur-logger when used
with logkit has three sections (beside the root element).
- </p>
- <dl>
- <dt><factories></dt>
- <dd>
+ </p>
+ <dl>
+ <dt><factories></dt>
+ <dd>
The factories section defines the
- <code>LogTargetFactory</code>s
+ <code>LogTargetFactory</code>s
that are used to create the needed
- <code>LogTargets</code>. You'll
+ <code>LogTargets</code>. You'll
find the factories available in the
- <code>org.apache.avalon.excalibur.logger.factory</code>
+ <code>org.apache.avalon.excalibur.logger.factory</code>
package. You can write your own factories which
only needs to implement the
- <code>org.apache.avalon.excalibur.logger.LogTargetFactory</code>
+ <code>org.apache.avalon.excalibur.logger.LogTargetFactory</code>
interface or you extend one of the available factories
in the mentioned package.
- </dd>
- <dt><targets></dt>
- <dd>
+ </dd>
+ <dt><targets></dt>
+ <dd>
The targets section defines the individual
- <code>LogTargets</code>.
+ <code>LogTargets</code>.
The element name of a target definition corresponds
to a type attribute of a <factory> element. You'll
probably need to consult the javadocs of the corresponding
factory to get familiar with the configuration
options available for a particular target.
- </dd>
- <dt><categories></dt>
- <dd>
+ </dd>
+ <dt><categories></dt>
+ <dd>
The categories section finally assembles all together. The
name attribute of a category gives the reference used in
logger attribute in the components configuration files.
The log-level attribute gives the logging priority to the
- <code>Logger</code> of that category. <category>
+ <code>Logger</code> of that category. <category>
elements have <log-targets> children which, you
- already guessed, defines the <code>LogTarget</code>s
+ already guessed, defines the
+ <code>LogTarget</code>s
for a particular logging category. You'll also see in the
sample above that category elements can be nested to define
sub-categories.
- </dd>
- </dl>
- </section>
- <section name="Design principles and implementation details of Excalibur-Logger">
- <p>
- The first abstraction is the <code>LogKitManager</code>:
- </p>
- <source>
+ </dd>
+ </dl>
+ </section>
+ <section name="Design principles and implementation details of Excalibur-Logger">
+ <p>
+ The first abstraction is the
+ <code>LogKitManager</code>:
+ </p>
+ <source>
public interface LogKitManager
{
Logger getLogger( String categoryName );
}
- </source>
- <p>
- There is a implementation named <code>DefaultLogKitManager</code>
+ </source>
+ <p>
+ There is a implementation named
+ <code>DefaultLogKitManager</code>
which is the only class exposed to clients. As a convenient a
additional interface is introduced for the
- <code>ComponentManager</code> (stolen from the role management
+ <code>ComponentManager</code> (stolen from the role management
system) which states that a class is willing to get a
- <code>LogKitManager</code>:
- </p>
- <source>
+ <code>LogKitManager</code>:
+ </p>
+ <source>
public interface LogKitManageable
{
void setLogKitManager( LogKitManager logmanager );
}
- </source>
- <p>
+ </source>
+ <p>
This method has to be called before the configure method but after the
contextualize method.
- </p>
- <p>
- The <code>DefaultLogKitManager</code> is <code>Configurable</code>
- (as well as <code>Loggable</code> [the initial default logger] and
- <code>Contextualizable</code> [to pass along for ie.
- <code>ServletOutputLogTarget</code>]) and gets a
- <code>Configuration</code> object as expressed in the logkit
- xml syntax above. This <code>DefaultLogKitManager</code> then uses
+ </p>
+ <p>
+ The
+ <code>DefaultLogKitManager</code> is
+ <code>Configurable</code>
+ (as well as
+ <code>Loggable</code> [the initial default logger] and
+ <code>Contextualizable</code> [to pass along for ie.
+ <code>ServletOutputLogTarget</code>]) and gets a
+ <code>Configuration</code> object as expressed in the logkit
+ xml syntax above. This
+ <code>DefaultLogKitManager</code> then uses
a object of type
- </p>
- <source>
+ </p>
+ <source>
public interface LogTargetFactoryManager
{
LogTargetFactory getLogTargetFactory( String factoryName );
}
- </source>
- <p>
- The <code>DefaultLogTargetFactoryManager</code> is
- <code>Configurable</code> (as well as <code>Loggable</code> and
- <code>Contextualizable</code>) and gets the
- <code>Configuration</code> object located at the <factories>
+ </source>
+ <p>
+ The
+ <code>DefaultLogTargetFactoryManager</code> is
+ <code>Configurable</code> (as well as
+ <code>Loggable</code> and
+ <code>Contextualizable</code>) and gets the
+ <code>Configuration</code> object located at the <factories>
element. It will instanciate the concrete factories into a map
keyed by the type attribute. So we are at the
- <code>LogTargetFactory</code> abstraction which is:
- </p>
- <source>
+ <code>LogTargetFactory</code> abstraction which is:
+ </p>
+ <source>
public interface LogTargetFactory
{
LogTarget createTarget( Configuration configuration )
throws ConfigurationException;
}
- </source>
- <p>
- It may happen that a <code>LogTargetFactory</code> needs to
- create <code>LogTarget</code>s they don't know in advance
+ </source>
+ <p>
+ It may happen that a
+ <code>LogTargetFactory</code> needs to
+ create
+ <code>LogTarget</code>s they don't know in advance
and thus an additional interface is needed:
- </p>
- <source>
+ </p>
+ <source>
public interface LogTargetFactoryManageable
{
void setLogTargetFactoryManager(
LogTargetFactoryManager logTargetFactoryManager );
}
- </source>
- <p>
+ </source>
+ <p>
This eases writing factories which acts like decorators
- (<code>AsyncLogTarget</code>, <code>PriorityFilter</code>)
+ (
+ <code>AsyncLogTarget</code>,
+ <code>PriorityFilter</code>)
and thus need a LogTargetFactoryManager to create the decorated
- <code>LogTargets</code> which are embeded in the configuration
+ <code>LogTargets</code> which are embeded in the configuration
of them (see <priority-filter> above).
- </p>
- <p>
- After initializing the <code>LogTargetFactoryManager</code> a
- <code>LogTargetManager</code>
- </p>
- <source>
+ </p>
+ <p>
+ After initializing the
+ <code>LogTargetFactoryManager</code> a
+ <code>LogTargetManager</code>
+ </p>
+ <source>
public interface LogTargetManager
{
LogTarget getLogTarget( String targetId );
}
- </source>
- <p>
- is created. The implementation <code>DefaultLogTargetManager</code>
- is, you guess it, <code>Configurable</code> (as well as
- <code>Loggable</code> and <code>Contextualizable</code>). The
- <code>Configuration</code> object is the <targets> element
+ </source>
+ <p>
+ is created. The implementation
+ <code>DefaultLogTargetManager</code>
+ is, you guess it,
+ <code>Configurable</code> (as well as
+ <code>Loggable</code> and
+ <code>Contextualizable</code>). The
+ <code>Configuration</code> object is the <targets> element
in the xml syntax and is put into a map keyed by the id
attribute of the target element. It is also
- <code>LogTargetFactoryManageable</code> tob e able to create
- the <code>LogTargets</code>.
- </p>
- <p>
- The last step of the <code>DefaultLogKitManagers</code> configure
+ <code>LogTargetFactoryManageable</code> tob e able to create
+ the
+ <code>LogTargets</code>.
+ </p>
+ <p>
+ The last step of the
+ <code>DefaultLogKitManagers</code> configure
method is to create the actual categories based on the categories
elements content. It does it as the syntax will show in a
recursive way populating the Loggers retrieved by
- <code>Hierarchy.getDefaultHierarchy().getLoggerFor( full_category )</code>
- with the denoted <code>LogTargets</code> from the
- <code>LogTargetManager</code>.
- </p>
- <p>
- After that the <code>LogKitManager</code> is ready to be asked
- for <code>Logger</code>s.
- </p>
- <p>
+ <code>Hierarchy.getDefaultHierarchy().getLoggerFor( full_category )</code>
+ with the denoted
+ <code>LogTargets</code> from the
+ <code>LogTargetManager</code>.
+ </p>
+ <p>
+ After that the
+ <code>LogKitManager</code> is ready to be asked
+ for
+ <code>Logger</code>s.
+ </p>
+ <p>
Now ECM is aware of a
"magic attributes" named logger and used like
- <code>logger="category"</code> on the component definition syntax.
+ <code>logger="category"</code> on the component definition syntax.
The classes building up ECM
- are made <code>LogTargetFactoryManageable</code>. If you pass along
- a <code>LogKitManager</code> to the <code>ExcaliburComponentManager</code>
+ are made
+ <code>LogTargetFactoryManageable</code>. If you pass along
+ a
+ <code>LogKitManager</code> to the
+ <code>ExcaliburComponentManager</code>
it will retrieve the denoted logger
category specified with the logger attribute from the
- <code>LogKitManager</code> and pass it to <code>Component</code>s
- implementing <code>Loggable</code>.
- </p>
- </section>
- </body>
+ <code>LogKitManager</code> and pass it to
+ <code>Component</code>s
+ implementing
+ <code>Loggable</code>.
+ </p>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/navigation.xml
==============================================================================
--- excalibur/trunk/site/xdocs/navigation.xml (original)
+++ excalibur/trunk/site/xdocs/navigation.xml Wed Jun 23 02:32:50 2004
@@ -1,39 +1,86 @@
<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<project>
- <title>Avalon Sandbox</title>
+ <title>Apache Excalibur</title>
- <body>
+ <body>
- <links>
- <item name="Apache" href="http://apache.org/"/>
- <item name="Avalon" href="http://avalon.apache.org/"/>
- <item name="Framework" href="http://avalon.apache.org/product/framework/"/>
- <item name="Merlin" href="http://avalon.apache.org/product/containers/"/>
- <item name="Planet" href="http://avalon.apache.org/product/components/"/>
- </links>
-
- <menu name="About Excalibur">
- <item name="Overview" href="/index.html"/>
- <item name="Configuration" href="configuration.html"/>
- <item name="I18N" href="i18n/index.html"/>
- <item name="Sourceresolver" href="sourceresolve-index.html"/>
- <item name="Store" href="store-index.html"/>
- <item name="ECM" href="component.html"/>
- <item name="Event" href="event/index.html"/>
- <item name="Fortress" href="fortress/index.html"/>
- <item name="I18N" href="i18n.html"/>
- <item name="Logger" href="logger.html"/>
- <item name="Lifecycle" href="lifecycle/index.html"/>
- <item name="Thread" href="thread.html"/>
- </menu>
-
- <menu name="Resources">
- <item name="Javadocs" href="http://avalon.apache.org/excalibur/api/"/>
- <item name="Download" href="http://avalon.apache.org/download.cgi"/>
- <item name="Where's my documentation???" href="/no-docs-available.html"/>
- </menu>
+ <links>
+ <item name="Apache" href="http://apache.org/"/>
+ <item name="Excalibur" href="http://excalibur.apache.org/"/>
+ <item name="Avalon-Framework" href="http://avalon.apache.org/product/framework/"/>
+ </links>
+
+ <menu name="Essentials">
+ <item name="Overview" href="/index.html"/>
+ <item name="Mailing Lists" href="/mail-lists.html"/>
+ <item name="Subversion" href="/svn.html"/>
+ <item name="Wiki" href="http://wiki.apache.org/excalibur/"/>
+ <item name="FAQ" href="http://wiki.apache.org/excalibur/FrequentlyAskedQuestions"/>
+ <item name="Javadocs" href="http://avalon.apache.org/excalibur/api/"/>
+ <item name="Download" href="http://avalon.apache.org/download.cgi"/>
+ <item name="Issue Tracking" href="/jira.html"/>
+ </menu>
+
+ <menu name="Component documentation">
+ <item name="Configuration" href="/configuration.html"/>
+ <item name="ECM" href="/component.html"/>
+ <item name="Event" href="event/index.html" collapse="true">
+ <item href="event/event.html" name="Event"/>
+ <item href="event/command.html" name="Command"/>
+ <item href="event/mpool.html" name="MPool"/>
+ <item href="event/util.html" name="Util"/>
+ <item href="event/event-howto.html" name="Use Event Queues"/>
+ <item href="event/command-howto.html" name="Use the Command Manager"/>
+ <item href="event/mpool-howto.html" name="Use MPool"/>
+ <item href="event/util-howto.html" name="Use System Util"/>
+ <item href="event/cpuparser-howto.html" name="Extend System Util"/>
+ </item>
+ <item name="Fortress" href="fortress/index.html" collapse="true">
+ <item name="Overview" href="fortress/index.html"/>
+ <item name="Features Oriented" href="fortress/features.html"/>
+ <item name="Getting Started" href="fortress/getting-started.html"/>
+ <item name="Using Meta Info" href="fortress/using-meta-info.html"/>
+ <item name="CLI" href="fortress/cli.html"/>
+ <item name="Swing" href="fortress/swing.html"/>
+ <item name="Servlet" href="fortress/servlet.html"/>
+ <item name="Lifecycle Extensions" href="fortress/lifecycle-extensions.html"/>
+ <item name="Design Notes" href="fortress/design-notes.html"/>
+ </item>
+ <item name="i18n" href="i18n.html"/>
+ <item name="Lifecycle" href="lifecycle/index.html" collapse="true">
+ <item name="Overview" href="lifecycle/index.html"/>
+ <item name="Extensions" href="lifecycle/extension.html"/>
+ <item name="Interfaces" href="lifecycle/interfaces.html"/>
+ <item name="Tutorial" href="lifecycle/fortress.html"/>
+ </item>
+ <item name="Logger" href="logger.html"/>
+ <item name="Sourceresolver" href="sourceresolve-index.html"/>
+ <item name="Store" href="store-index.html"/>
+ <item name="Thread" href="thread.html"/>
+ </menu>
+
+ <menu name="Miscellaneous">
+ <item name="Where's my documentation???" href="/no-docs-available.html"/>
+ </menu>
- </body>
+ </body>
</project>
Modified: excalibur/trunk/site/xdocs/no-docs-available.xml
==============================================================================
--- excalibur/trunk/site/xdocs/no-docs-available.xml (original)
+++ excalibur/trunk/site/xdocs/no-docs-available.xml Wed Jun 23 02:32:50 2004
@@ -1,10 +1,25 @@
<?xml version="1.0"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
<properties>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- <title>Excalibur - Please volunteer to write documentation</title>
+ <title>Please volunteer to write documentation</title>
</properties>
<body>
@@ -35,7 +50,7 @@
interested in helping out, please drop by on the Avalon
Development mailing list
- (<a href="http://avalon.apache.org/mailing-lists.html">Subscription information</a>)
+ (<a href="http://excalibur.apache.org/mail-lists.html">Subscription information</a>)
for more information on how to do just that.
</p>
Modified: excalibur/trunk/site/xdocs/sourceresolve-index.xml
==============================================================================
--- excalibur/trunk/site/xdocs/sourceresolve-index.xml (original)
+++ excalibur/trunk/site/xdocs/sourceresolve-index.xml Wed Jun 23 02:32:50 2004
@@ -1,18 +1,34 @@
<?xml version="1.0"?>
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
<properties>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- <title>Excalibur Source Resolving - Overview</title>
+ <title>Source Resolving - Overview</title>
</properties>
- <body>
- <section name="Introduction">
- <p>
+ <body>
+ <section name="Introduction">
+ <p>
A very common problem is resolving a source, which means
finding a source using a URI.
- </p>
- <p>
+ </p>
+ <p>
The source resolver of Avalon Excalibur is a component
helping you in this task. It resolves sources from a given
URI. The URI can use all available protocols of the JRE.
@@ -20,54 +36,54 @@
the standard protocols like HTTP, FTP or file can be handled
in the same way, like dealing with custom, self-build
protocols such as myxmldatabase://root/documents/test.xml.
- </p>
- <p>
+ </p>
+ <p>
The main advantage in comparisson to the mechanisms provided
by the JRE is that the source resolver can be used without
any problems with web application servers. Each web
application can use it's own configured version of this
component avoiding any possible conflicts between these
applications.
- </p>
- <p>
+ </p>
+ <p>
The architecture of this package is simple but powerful.
The main component is the SourceResolver. It is used
to resolve any URI. If the SourceResolver can resolve the
protocol of the URI, it returns a Source object. This Source
object is an abstraction of the underlying resource. This
resource can be accessed by a provided InputStream.
- </p>
- <p>
+ </p>
+ <p>
Own protocols can be configured using the SourceFactory interface.
Whenever the SourceResolver finds a protocol that it can't handle
by itself, it gets a role selector for a SourceFactory and tries
to get a component with the role name of the protocol.
If such a factory exists, the source creation is passed on to this
factory.
- </p>
- <p>
+ </p>
+ <p>
The Source object is handled similar to Avalon components.
After it has been used it must be released using the SourceResolver.
The SourceResolver in turn passed on the release of the
object to the SourceFactory that created it.
- </p>
- <p>
+ </p>
+ <p>
The Source object is a lightwight object which can be extended with
several interface. For example the XMLizable interface from the XML
package to generate SAX events from the Source. Or the Monitorable
interface from the monitor package to monitor the resource.
- </p>
- <p>
+ </p>
+ <p>
For caching purposes the Source object offers a SourceValidity object
which can be used in addition to the system ID of the Source to verify
if a cache contains a valid version of the Source object.
- </p>
- </section>
- <section name="Projects">
- <p>You can see the source resolving in action in the Apache Cocoon
+ </p>
+ </section>
+ <section name="Projects">
+ <p>You can see the source resolving in action in the Apache Cocoon
project.
- </p>
- </section>
- </body>
+ </p>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/store-index.xml
==============================================================================
--- excalibur/trunk/site/xdocs/store-index.xml (original)
+++ excalibur/trunk/site/xdocs/store-index.xml Wed Jun 23 02:32:50 2004
@@ -1,29 +1,47 @@
<?xml version="1.0"?>
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
<properties>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- <title>Excalibur Store - Overview</title>
+ <title>Store - Overview</title>
</properties>
<body>
- <section name="Introduction">
- <p>
+ <section name="Introduction">
+ <p>
The Store Package provides a way to store named objects without
taking care about where and how they are stored.
You can choose between different implementations that store
the data e.g. in memory or on the file system etc.
- </p>
- <p>
+ </p>
+ <p>
This project provides some general components for dealing with stores.
It contains different store implementations, like the
- <a href="store-mru.html">MRU Store</a> and a montoring component,
- the <a href="store-janitor.html">Store Janitor</a>.
- </p>
- <p>
- These components have been donated by the <a href="http://cocoon.apache.org">Apache Cocoon project</a>.
- </p>
- </section>
- </body>
+ <a href="store-mru.html">MRU Store</a> and a montoring component,
+ the
+ <a href="store-janitor.html">Store Janitor</a>.
+ </p>
+ <p>
+ These components have been donated by the
+ <a href="http://cocoon.apache.org">Apache Cocoon project</a>.
+ </p>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/store-janitor.xml
==============================================================================
--- excalibur/trunk/site/xdocs/store-janitor.xml (original)
+++ excalibur/trunk/site/xdocs/store-janitor.xml Wed Jun 23 02:32:50 2004
@@ -1,49 +1,84 @@
<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
<properties>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
<title>The Store Janitor</title>
</properties>
<body>
- <section name="Goal">
- <p>This document describes the usage of the StoreJanitor.</p>
- </section>
- <section name="Description">
- <p>The implementation is quit simple! Every implementation of a Store can register in the
+ <section name="Goal">
+ <p>This document describes the usage of the StoreJanitor.</p>
+ </section>
+ <section name="Description">
+ <p>The implementation is quit simple! Every implementation of a Store can register in the
StoreJanitor. It checks in a configurable interval if memory is running low. If low,
it greps via Round Robin a victim (Store) and frees xx% of all emlements in this Store.
After that the StoreJanitor sleeps and waits for the next iteration.</p>
- <p>The StoreJanitor is very useful for web applications that use the store as
+ <p>The StoreJanitor is very useful for web applications that use the store as
a in-memory cache. The StoreJanitor helps in avoiding OutOfMemory exceptions.</p>
- </section>
- <section name="Configuration">
- <p>The Store Janitor can be configured with a few options:
- </p>
- <ul>
- <li><em>freememory</em>: How many bytes shall be always free in the JVM (Default: 1mb)</li>
- <li><em>heapsize</em>: Maximum possible size of the JVM memory consumption (Default: 64mb)</li>
- <li><em>cleanupthreadinterval</em>: How often (sec) shall run the cleanup thread (Default: 10s)</li>
- <li><em>adaptivethreadinterval</em> (experimental): Enable adaptive algorithm to determine thread interval
- (Default: false) When true, <code>cleanupthreadinterval</code> defines the maximum cleanup interval.
+ </section>
+ <section name="Configuration">
+ <p>The Store Janitor can be configured with a few options:
+ </p>
+ <ul>
+ <li>
+ <em>freememory</em>: How many bytes shall be always free in the JVM (Default: 1mb)
+ </li>
+ <li>
+ <em>heapsize</em>: Maximum possible size of the JVM memory consumption (Default: 64mb)
+ </li>
+ <li>
+ <em>cleanupthreadinterval</em>: How often (sec) shall run the cleanup thread (Default: 10s)
+ </li>
+ <li>
+ <em>adaptivethreadinterval</em> (experimental): Enable adaptive algorithm to determine thread interval
+ (Default: false) When true,
+ <code>cleanupthreadinterval</code> defines the maximum cleanup interval.
Cleanup interval then is determined based on the memory fill rate: the faster memory is filled in,
- and the less free memory is left, the shorter is the cleanup time.</li>
- <li><em>threadpriority</em>: priority of the thread (1-10). (Default: 10)</li>
- <li><em>percent_to_free</em>: What fraction of the store to free when memory is low (1-100). (Default: 10%)</li>
- <li><em>invokegc</em>: Invoke the gc on low memory first (true|false; default: false)</li>
- </ul>
- <p>The right configuration is very important, because wrong settings can
+ and the less free memory is left, the shorter is the cleanup time.
+ </li>
+ <li>
+ <em>threadpriority</em>: priority of the thread (1-10). (Default: 10)
+ </li>
+ <li>
+ <em>percent_to_free</em>: What fraction of the store to free when memory is low (1-100). (Default: 10%)
+ </li>
+ <li>
+ <em>invokegc</em>: Invoke the gc on low memory first (true|false; default: false)
+ </li>
+ </ul>
+ <p>The right configuration is very important, because wrong settings can
cause a high system load. Let's have a look at a sample configuration.</p>
- <subsection name="Example configuration">
- <ul><li>Tomcat settings in tomcat.sh or tomcat.bat:</li></ul>
- <source><![CDATA[
+ <subsection name="Example configuration">
+ <ul>
+ <li>Tomcat settings in tomcat.sh or tomcat.bat:</li>
+ </ul>
+ <source><![CDATA[
%_RUNJAVA% %TOMCAT_OPTS% -Dtomcat.home="%TOMCAT_HOME%" \
-Xmx200000000 org.apache.tomcat.startup.Tomcat %2 %3 %4 %5 %6 %7 %8 %9
- ]]></source>
- <ul><li>StoreJanitor settings:</li></ul>
- <p>The freememory and heapsize paramter always depends on the Xmx
+ ]]></source>
+ <ul>
+ <li>StoreJanitor settings:</li>
+ </ul>
+ <p>The freememory and heapsize paramter always depends on the Xmx
parameter.</p>
- <source><![CDATA[
+ <source><![CDATA[
<!--+
| Store Janitor: the store garbage collector and memory usage controller.
|
@@ -83,26 +118,30 @@
<!-- Invoke the garbage collector when low memory is reached -->
<parameter name="invokegc" value="false"/>
</store-janitor>
- ]]></source>
- <p>It is recommended to have <code>heapsize</code> equal to -Xmx, especially
- on Sun's JVM which are unable to shrink its heap once it grows above minimum.
- <code>freememory</code> should be greater than amount of memory necessary for normal
+ ]]></source>
+ <p>It is recommended to have
+ <code>heapsize</code> equal to -Xmx, especially
+ on Sun's JVM which are unable to shrink its heap once it grows above minimum.
+ <code>freememory</code> should be greater than amount of memory necessary for normal
application operation. But the heap size of the memory of the JVM is a little bit less than
the value you specify for -Xmx, so you have to set the heapsize
for the store janitor to a value which is lower (2% less seems
to be a working value)
- </p>
- <p> The <code>cleanupthreadinterval</code> defines the interval of the background
+ </p>
+ <p> The
+ <code>cleanupthreadinterval</code> defines the interval of the background
thread which checks memory in seconds. Also this paramter should configured wisely.
- A to short interval can cause also a high system load. The
- <code>threadpriority</code> defines the priority of the background thread.
- 1 is lowest level and 10 the highest.</p>
- <p>
- The <code>percent_to_free</code> parameter describes, how much percent of the
+ A to short interval can cause also a high system load. The
+ <code>threadpriority</code> defines the priority of the background thread.
+ 1 is lowest level and 10 the highest.
+ </p>
+ <p>
+ The
+ <code>percent_to_free</code> parameter describes, how much percent of the
elements of each registered Store shall be removed when low on memory.
- </p>
- </subsection>
- </section>
- </body>
+ </p>
+ </subsection>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/store-mru.xml
==============================================================================
--- excalibur/trunk/site/xdocs/store-mru.xml (original)
+++ excalibur/trunk/site/xdocs/store-mru.xml Wed Jun 23 02:32:50 2004
@@ -1,29 +1,45 @@
<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
<properties>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
<title>MRUMemoryStore and Swapping</title>
</properties>
<body>
- <section name="Goal">
- <p>This document explains how the MRUMemoryStore and Swapping executes.</p>
- </section>
- <section name="Overview">
- <p>The MRUMemoryStore was developed to provide a standard algorithm to
+ <section name="Goal">
+ <p>This document explains how the MRUMemoryStore and Swapping executes.</p>
+ </section>
+ <section name="Overview">
+ <p>The MRUMemoryStore was developed to provide a standard algorithm to
store data in memory. For web-based applications the MRU (Most Recently Used) algorithm
is very suitable, because the object most frequently accessed is always on "top".
- </p>
- <p>If configured, the objects are also swapped to the filesystem if the
+ </p>
+ <p>If configured, the objects are also swapped to the filesystem if the
MRUMemoryStore reached his configured max. object limit.
- </p>
- </section>
- <section name="Implementation">
- <subsection name="MRUMemoryStore">
- <p>
+ </p>
+ </section>
+ <section name="Implementation">
+ <subsection name="MRUMemoryStore">
+ <p>
The heart of the MRUMemoryStore ist combination of a LinkedList and a HashMap:
- </p>
- <p>
+ </p>
+ <p>
The LinkedList provides the queue mechanism, and the entries in the LinkedList
contain the key to the data in the HashMap. When caching a new entry in to the list,
the entry is inserted to the front of the list.
@@ -33,43 +49,47 @@
This implementation keeps the most recent used objects in the store and provides the best
use of the machines memory.
- </p>
- </subsection>
- <subsection name="Swapping">
- <p>
+ </p>
+ </subsection>
+ <subsection name="Swapping">
+ <p>
When the MRUMemoryStore is full or the JVM is at the heap size limit the
objects in the MRUMemoryStore are swapped to the Filesystem. The default
directory is "cache-dir" in the work-directory.
- </p>
- <p>
+ </p>
+ <p>
NOTE: The keys are Strings at the moment. Therefor the
filenames of the swapped objects can be very long. Especially Windows OS
flavours have problems with long filenames. Use the JispFilesystemStore to
get rid of it.
- </p>
- </subsection>
- </section>
- <section name="Configuration of the MRUMemoryStore in the cocoon.xconf">
- <source><![CDATA[
+ </p>
+ </subsection>
+ </section>
+ <section name="Configuration of the MRUMemoryStore in the cocoon.xconf">
+ <source><![CDATA[
<store class="org.apache.excalibur.store.impl.MRUMemoryStore"
logger="core.store">
<parameter name="maxobjects" value="100"/>
<parameter name="use-persistent-cache" value="true"/>
</store>]]>
- </source>
- <p>Explanation of the paramters:</p>
- <ol>
- <li><code><parameter name="maxobjects" value="100"/></code>:
+ </source>
+ <p>Explanation of the paramters:</p>
+ <ol>
+ <li>
+ <code><parameter name="maxobjects" value="100"/></code>:
Indicates how many objects will be hold in MRUMemoryStore. When the number
of maxobjects has been reached, the last object in the MRUMemoryStore will be
- thrown out.</li>
- <li><code><parameter name="use-persistent-cache" value="true"/></code>:
+ thrown out.
+ </li>
+ <li>
+ <code><parameter name="use-persistent-cache" value="true"/></code>:
If this switch is set on true, objects are swapped out to the filesystem,
if the MRUMemoryStore has reached his maximum object limit, or the JVM
memory consumption is over the heap size limit. See StoreJanitor user
- docs for more information.</li>
- </ol>
- </section>
- </body>
+ docs for more information.
+ </li>
+ </ol>
+ </section>
+ </body>
</document>
Added: excalibur/trunk/site/xdocs/svn.xml
==============================================================================
--- (empty file)
+++ excalibur/trunk/site/xdocs/svn.xml Wed Jun 23 02:32:50 2004
@@ -0,0 +1,101 @@
+<?xml version="1.0"?>
+
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document>
+
+ <properties>
+ <title>Subversion Access</title>
+ </properties>
+
+ <body>
+
+ <section name="What is Subversion?">
+
+ <p>
+ Subversion (svn for short) is a version control system that beats the shit out of
+ CVS. See <a href="http://subversion.tigris.org">the subversion homepage</a> for more
+ information. Excalibur uses subversion for version control.
+ </p>
+
+ <h2>How do I use it?</h2>
+
+ <p>After downloading the client, point it towards the excalibur repository at</p>
+
+ <pre>
+
+ https://svn.apache.org/repos/asf/excalibur/
+ </pre>
+
+ <p>
+ (note you can also browse the repository online from that url). To check out the
+ latest and greatest bleeding edge excalibur source tree, use a command like this:
+ </p>
+
+ <pre>
+ svn checkout https://svn.apache.org/repos/asf/excalibur/trunk/ excalibur-trunk
+ </pre>
+
+ </section>
+
+ <section name="What about write access?">
+
+ <p>
+ If you're an excalibur, <a href="http://cocoon.apache.org/">cocoon</a> or
+ <a href="http://james.apache.org/">james</a> committer, you have write access to
+ that repository using that same URL. Before you can do anything, you need to set up
+ a svn password. To do so, log in to svn.apache.org using SSH, and enter the command
+ <code>svnpasswd</code>. Pick a safe password!
+ </p>
+
+ <p>
+ Now, when you make changes, you can commit them with your username/password
+ combination. Ie:
+ </p>
+
+ <pre>
+ cd excalibur-trunk
+ echo "test" > test.txt
+ svn add test.txt
+ svn commit --username your-name --password your-password --message "Trying out svn"
+ </pre>
+
+ </section>
+ <section name="How does all that work?">
+
+ <p>
+ The setup the ASF uses is pretty much the one described in
+ <a href="http://svnbook.red-bean.com/svnbook/ch06s04.html">chapter 6 of the svn
+ book</a>. The repository lives in /x1/svn on minotaur.apache.org, with the important
+ files related to authorization living in that directory, too.
+ </p>
+
+ </section>
+ <section name="What about IDE integration and GUI clients?">
+
+ <p>It works fine. Go and google.</p>
+
+ <ul>
+ <li><a href="http://tortoisesvn.tigris.org/">TortoiseSVN</a> provides windows explorer integration;</li>
+ <li><a href="http://svnup.tigris.org/">svnup</a> provides IDEA integration and a java GUI;</li>
+ <li><a href="http://subclipse.tigris.org/">subclipse</a> provides Eclipse integration; etc etc.</li>
+ </ul>
+
+ </section>
+ </body>
+
+</document>
Modified: excalibur/trunk/site/xdocs/thread.xml
==============================================================================
--- excalibur/trunk/site/xdocs/thread.xml (original)
+++ excalibur/trunk/site/xdocs/thread.xml Wed Jun 23 02:32:50 2004
@@ -1,3 +1,5 @@
+<?xml version="1.0"?>
+
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,26 +17,26 @@
limitations under the License.
-->
<document>
- <properties>
- <author email="dev@avalon.apache.org">Avalon Development Team</author>
- <title>Excalibur Thread Pool Utilities - Overview</title>
- </properties>
- <body>
- <section name="Introduction" >
- <warn>
+ <properties>
+ <title>Thread Pool Utilities - Overview</title>
+ </properties>
+ <body>
+ <section name="Introduction">
+ <warn>
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 Scratchpad.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.
- </warn>
- <p>
+ </warn>
+ <p>
Avalon Excalibur's Thread Pool Management code is still under
- development. The package is <code>org.apache.avalon.excalibur.thread</code>
+ development. The package is
+ <code>org.apache.avalon.excalibur.thread</code>
in the Scratchpad jar. It is functional, using the no resource
limiting pool implementation in Excalibur's Pool package. Expect
the interface to this change before we promote it to Excalibur.
- </p>
- </section>
- </body>
+ </p>
+ </section>
+ </body>
</document>
Modified: excalibur/trunk/site/xdocs/usage.xml
==============================================================================
--- excalibur/trunk/site/xdocs/usage.xml (original)
+++ excalibur/trunk/site/xdocs/usage.xml Wed Jun 23 02:32:50 2004
@@ -1,27 +1,42 @@
<?xml version="1.0"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<document>
<properties>
- <author email="dev@avalon.apache.org">Avalon Documentation Team</author>
- <title>Excalibur i18n - Usage</title>
+ <title>i18n - Usage</title>
</properties>
<body>
<section name="Excalibur i18n">
- <subsection name="Usage">
- <p>
+ <subsection name="Usage">
+ <p>
Using the i18n code is really straightforward; several
examples of internationalized applications exist within
the Avalon application family.
- </p>
- <p>
+ </p>
+ <p>
The following code is an example of the usage of the
i18n package.
- </p>
- <source>
+ </p>
+ <source>
// in a file called src/java/MyClass.java
import org.apache.avalon.excalibur.i18n.ResourceManager;
@@ -49,26 +64,26 @@
# in a file called src/java/Resources.properties
myclass.error.dostuff.bad-argument=the argument passed to the \
doStuff method is invalid; it is {0}, which is plain silly!
- </source>
+ </source>
- <p>
+ <p>
That's basically all there is to it. If you follow this
pattern consistently, it will be extremely easy to i18n
your application by just putting in place a different
Resources.properties.
- </p>
- <p>
+ </p>
+ <p>
This i18n package is, indeed, a trivial wrapper around
the built-in i18n features java has using ResourceBundles
and the like. See the java api docs for
- <link href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/ResourceBundle.html">ResourceBundle</link>
+ <link href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/ResourceBundle.html">ResourceBundle</link>
to learn more about i18n, and take a look at the javadoc
for Resources and ResourceManager to see which options
are available.
- </p>
- </subsection>
+ </p>
+ </subsection>
- </section>
+ </section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: scm-unsubscribe@excalibur.apache.org
For additional commands, e-mail: scm-help@excalibur.apache.org