You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@turbine.apache.org by ep...@apache.org on 2004/11/09 10:49:46 UTC
cvs commit: jakarta-turbine-fulcrum/yaafi/xdocs todo.xml howto.xml navigation.xml
epugh 2004/11/09 01:49:46
Modified: yaafi/xdocs navigation.xml
Added: yaafi/xdocs/services index.xml servicemanagerservice.xml
systempropertyservice.xml
yaafi/xdocs/lifecycle index.xml incarnation.xml
reconfiguration.xml decommission.xml
yaafi/xdocs todo.xml howto.xml
Log:
More documentation!
Revision Changes Path
1.1 jakarta-turbine-fulcrum/yaafi/xdocs/services/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>YAAFI Services</title>
<author email="siegfried.goeschl@it20one.at">Siegfried Goeschl</author>
</properties>
<body>
<section name="YAAFI Services">
<p>
YAAFI comes already with the following services since they are generally useful and
do not add any dependencies
<table>
<tr>
<th>Name</th>
<th>Desciption</th>
</tr>
<tr>
<td><a href="servicemanagerservice.html">ServiceManagerService</a></td>
<td>
Keeps a reference to the YAAFI instance
</td>
</tr>
<tr>
<td><a href="systempropertyservice.html">SystemPropertyService</a></td>
<td>
Copies system properties during startup
</td>
</tr>
</table>
</p>
</section>
</body>
</document>
1.1 jakarta-turbine-fulcrum/yaafi/xdocs/services/servicemanagerservice.xml
Index: servicemanagerservice.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>ServiceManagerService</title>
<author email="siegfried.goeschl@it20one.at">Siegfried Goeschl</author>
</properties>
<body>
<section name="Overview">
<p>
This service keeps an YAAFI instance.
</p>
<p>
</p>
</section>
<section name="Configuration">
<subsection name="Role Configuration">
<source>
<![CDATA[
<role
default-class="org.apache.fulcrum.yaafi.service.servicemanager.ServiceManagerService"
early-init="true"
/> ]]>
</source>
</subsection>
</section>
<section name="Usage">
<p>
ServiceManagerService.getServiceManager() returns you an instance of
ServiceManager which allows to lookup other services.
</p>
<source>
FOO foo = (FOO) ServiceManagerService.getServiceManager().lookup("FOO");
</source>
</section>
</body>
</document>
1.1 jakarta-turbine-fulcrum/yaafi/xdocs/services/systempropertyservice.xml
Index: systempropertyservice.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>SystemPropertyService</title>
<author email="siegfried.goeschl@it20one.at">Siegfried Goeschl</author>
</properties>
<body>
<section name="Overview">
<p>
This service copies entries from the configuratio.xml into the
SystemProperties.
</p>
<p>
Quite useful since you can avoid tinkering with system properties
in start scripts.
</p>
</section>
<section name="Configuration">
<subsection name="Role Configuration">
<source>
<![CDATA[
<role
name="org.apache.fulcrum.yaafi.service.systemproperty.SystemPropertyService"
shorthand="SystemPropertyService"
default-class="org.apache.fulcrum.yaafi.service.systemproperty.SystemPropertyServiceImpl"
early-init="true"
/>
]]>
</source>
</subsection>
<subsection name="Component Configuration">
<source>
<![CDATA[
<SystemPropertyService>
<property name="FOO">BAR</property>
</SystemPropertyService>
]]>
</source>
</subsection>
</section>
<section name="Usage">
<p>
This service does not expose any methods
</p>
</section>
</body>
</document>
1.1 jakarta-turbine-fulcrum/yaafi/xdocs/lifecycle/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Service Lifecycle</title>
<author email="siegfried.goeschl@it20one.at">Siegfried Goeschl</author>
</properties>
<body>
<section name="Service Lifecycle">
<p>
The service lifecycle contains of a bunch of interfaces covering the following aspects of a service
<ul>
<li><a href="incarnation.html">incarnation</a></li>
<li><a href="reconfiguration.html">reconfiguration</a></li>
<li><a href="decommission.html">decommissioning</a></li>
</ul>
</p>
<p>
These interfaces are the contract between your service implementation
and the service container. And this is the reason why we can deploy
a service implementation using different service framework implementations
such as Excalibur or Merlin.
</p>
</section>
</body>
</document>
1.1 jakarta-turbine-fulcrum/yaafi/xdocs/lifecycle/incarnation.xml
Index: incarnation.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Fulcrum YAAFI</title>
<author email="siegfried.goeschl@it20one.at">Siegfried Goeschl</author>
</properties>
<body>
<section name="Incarnation">
<p>
The incarnation of a service covers the creation and configuration of a
service
</p>
<p>
The following methods are invoked:
<ul>
<li>Constructor()</li>
<li>LogEnabled.enableLogging(Logger)</li>
<li>Contextualizable.contextualize(Context)</li>
<li>Serviceable.service(ServiceManager)</li>
<li>Configurable.configure(Configuration)</li>
<li>Parameterizable.parameterize(Parameters)</li>
<li>Initializable.initialize()</li>
<li>Executable.execute()</li>
<li>Startable.start()</li>
</ul>
</p>
<p>
The good news are that you don't have to implement all these interfaces
if you have a simple service. The bad news are that you might need all of
this interfaces in a complex application ... :-)
</p>
<subsection name="Constructor()">
<p>
This doesn't come as a surprise
</p>
</subsection>
<subsection name="LogEnabled.enableLogging(Logger)">
<p>
Here you get the logger for your service implementation. This
is again an interface to an implementation of a logger provided
by the caller of the service framework.
</p>
</subsection>
<subsection name="Contextualizable.contextualize(Context)">
<p>
The context contains information about your application
environment. The following entries are guaranteed to be
available since they are supplied by YAAFI
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>urn:avalon:home</td>
<td>File</td>
<td>
The home directory of the application. This is usually
the current working directory or WEB-INF. It is assumed
that your application has read access.
</td>
</tr>
<tr>
<td>urn:avalon:temp</td>
<td>File</td>
<td>
The temp directory of the application. It is assumed
that temporary files will be dumped there and therefore
read/write access is required.
</td>
</tr>
<tr>
<td>componentAppRoot</td>
<td>String</td>
<td>
The absolute path home directory of the application again.
This is provided for backward compatibility with Fulcrum and
might be depracted in the future.
</td>
</tr>
</table>
</p>
</subsection>
<subsection name="Serviceable.service(ServiceManager)">
<p>
At this point you get a reference to the service container. This
is the right moment to lookup all dependent services just to make
sure that everything is fine.
</p>
</subsection>
<subsection name="Configurable.configure(Configuration)">
<p>
A common task is to access configuration information whereas
the Configuration instance is a light-weight XML DOM tree. This
means you can use nested XML files for the configuration of your
service.
</p>
</subsection>
<subsection name="Parameterizable.parameterize(Parameters)">
<p>
Quite frankly I'm not sure why this method is needed. The only
reason I can think of is a command-line application ...
</p>
</subsection>
<subsection name="Initializable.initialize()">
<p>
This method is used for initializing your service implementation
since you have all your configuration information by now.
</p>
</subsection>
<subsection name="Executable.execute()">
<p>
If the component implements Executable the execute method will be
invoked before the component instance is exposed to any other component.
</p>
</subsection>
<subsection name="Startable.start()">
<p>
The Startable interface is used by any component that is constantly
running for the duration of its life.
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-turbine-fulcrum/yaafi/xdocs/lifecycle/reconfiguration.xml
Index: reconfiguration.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Fulcrum YAAFI</title>
<author email="siegfried.goeschl@it20one.at">Siegfried Goeschl</author>
</properties>
<body>
<section name="Decommision">
<p>
The reconfiguration of a service covers the following methods
<ul>
<li>Suspendable.suspend()</li>
<li>Reconfigurable.reconfigure(Configuration)</li>
<li>Suspendable.resume()</li>
</ul>
</p>
<subsection name="Suspendable.suspend()">
<p>
Suspend the service since it is guarenteed that no client
will invoke the service.
</p>
</subsection>
<subsection name="Reconfigurable.reconfigure(Configuration)">
<p>
Reconfigure the service with the Configuration instance.
</p>
</subsection>
<subsection name="Suspendable.resume()">
<p>
Resume the service - afterwards clients will invoke the service
again.
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-turbine-fulcrum/yaafi/xdocs/lifecycle/decommission.xml
Index: decommission.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Fulcrum YAAFI</title>
<author email="siegfried.goeschl@it20one.at">Siegfried Goeschl</author>
</properties>
<body>
<section name="Decommision">
<p>
The decommision of a service covers the shutdown procedure a service
<ul>
<li>Startable.stop()</li>
<li>Disposable.dispose()</li>
<li>Finalizer</li>
</ul>
</p>
<subsection name="Startable.stop()">
<p>
Stop all of the service activities since it is guaranteed that no client
will invoke the service.
</p>
</subsection>
<subsection name="Disposable.dispose()">
<p>
Free all resources hold by the service implementation.
</p>
</subsection>
<subsection name="Finalizer">
<p>
Well, it might be never called but all resouces have been
released before.
</p>
</subsection>
</section>
</body>
</document>
1.2 +14 -1 jakarta-turbine-fulcrum/yaafi/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-fulcrum/yaafi/xdocs/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 19 Oct 2004 22:03:50 -0000 1.1
+++ navigation.xml 9 Nov 2004 09:49:46 -0000 1.2
@@ -10,7 +10,20 @@
</links>
<menu name="Overview">
- <item name="Main" href="/index.html"/>
+ <item name="Main" href="/index.html"/>
+ <item name="Overview" href="/index.html"/>
+ <item name="Lifecycle" href="/lifecycle/index.html" collapse="true">
+ <item name="Incarnation" href="/lifecycle/incarnation.html"/>
+ <item name="Reconfiguration" href="/lifecycle/reconfiguration.html"/>
+ <item name="Decommision" href="/lifecycle/decommission.html"/>
+ </item>
+ <item name="Services" href="/services/index.html" collapse="true">
+ <item name="ServiceManagerService" href="/services/servicemanagerservice.html"/>
+ <item name="SystemPropertyService" href="/services/systempropertyservice.html"/>
+ </item>
+ <item name="How To" href="/howto.html"/>
+ <item name="Todo's" href="/todo.html"/>
+
</menu>
</body>
</project>
1.1 jakarta-turbine-fulcrum/yaafi/xdocs/todo.xml
Index: todo.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>TODO</title>
<author email="siegfried.goeschl@it20one.at">Siegfried Goeschl</author>
</properties>
<body>
<section name="TODO">
<subsection name="Support for encrytped configuration files">
<p>
Encryption/decryption of role and component configuration file using
BlowfishJ from Markus Hahn (see http://www.lassekolb.info/bfacs.htm).
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-turbine-fulcrum/yaafi/xdocs/howto.xml
Index: howto.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Fulcrum YAAFI</title>
<author email="siegfried.goeschl@it20one.at">Siegfried Goeschl</author>
</properties>
<body>
<section name="How To">
<subsection name="How to write my own service?">
<ul>
<li>
Write your service interface and implementation using the
Avalon Lifecycle interfaces.
</li>
<li>
Add an entry to the role configuration file. This entry
contains the information how YAAFI can instantiate and
access the service
</li>
<li>
Add an entry to the component configuratino file if
you need to configure your service.
</li>
</ul>
</subsection>
<subsection name="How can I embed YAAFI in an application?">
<p>
The embedding is done by creating a YAAFI instance using the
ServiceManagerFactory.create() method.
</p>
<p>
The following example creates a fully initialized and running
YAAFI container with the given configuration parameters using
a LOG4J logger.
</p>
<source>
ServiceContainer manager = null;
Logger logger = new Log4JLogger( org.apache.log4j.Logger.getLogger("YAAFI");
manager = ServiceManagerFactory.create(
logger,
"roleConfiguration.xml",
"componentConfiguration.xml",
"parameters.xml"
);
</source>
<p>
At the end of day you have to terminate YAAFI
</p>
<source>
manager.dispose();
</source>
</subsection>
<subsection name="How can I embed YAAFI into Turbine?">
<p>
In the 'contrib' directory there is a ready-to-use Turbine
service which needs the following configuration (for Turbine 2.2)
</p>
<source>
services.YaafiComponentService.classname=org.apache.turbine.services.yafficomponent.TurbineYaafiComponentService
services.YaafiComponentService.componentRoles=./conf/componentRoles.xml
services.YaafiComponentService.componentConfiguration=./conf/componentConfiguration.xml
services.YaafiComponentService.parameters=
</source>
</subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-dev-help@jakarta.apache.org