seade 2003/01/29 16:32:12
Modified: xdocs/howto index.xml navigation.xml
Added: xdocs/howto services-howto.xml
Log:
Henning's services howto, as marked up by Matt K.
Submitted by: Matt Koranda
Revision Changes Path
1.6 +1 -0 jakarta-turbine-2/xdocs/howto/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-2/xdocs/howto/index.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- index.xml 21 Jan 2003 02:23:08 -0000 1.5
+++ index.xml 30 Jan 2003 00:32:12 -0000 1.6
@@ -21,6 +21,7 @@
<li><a href="pullmodel-howto.html">Pull Model Howto</a></li>
<li><a href="python-howto.html">Python Howto</a></li>
<li><a href="security-howto.html">Security Howto</a></li>
+ <li><a href="services-howto.html">Services Howto</a></li>
<li><a href="url-rewriting-howto.html">URL rewriting Howto</a></li>
<li><a href="velocity-site-howto.html">Velocity Site Howto</a></li>
<li><a href="context-howto.html">Velocity Context Howto</a></li>
1.4 +1 -0 jakarta-turbine-2/xdocs/howto/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-2/xdocs/howto/navigation.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- navigation.xml 17 Jan 2003 20:38:07 -0000 1.3
+++ navigation.xml 30 Jan 2003 00:32:12 -0000 1.4
@@ -39,6 +39,7 @@
<item name="Pull Model Howto" href="/howto/pullmodel-howto.html"/>
<item name="Python Howto" href="/howto/python-howto.html"/>
<item name="Security Howto" href="/howto/security-howto.html"/>
+ <item name="Services Howto" href="/howto/services-howto.html"/>
<item name="Migrating from 2.1" href="/howto/migrate-from-2_1-howto.html"/>
<item name="URL rewriting Howto" href="/howto/url-rewriting-howto.html"/>
<item name="Velocity Site Howto" href="/howto/velocity-site-howto.html"/>
1.1 jakarta-turbine-2/xdocs/howto/services-howto.xml
Index: services-howto.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Services Howto</title>
<author email="[EMAIL PROTECTED]">Henning P. Schmiedehausen</author>
<author
email="[EMAIL PROTECTED]">Matt Koranda</author>
</properties>
<body>
<section
name="Turbine Services Creation">
<p>
Adding your own services to Turbine is
an easy task. Simply make your
class extend
<b>org.apache.turbine.services.TurbineBaseService</b>.
This is necessary so
that the Turbine Service Broker can start up
your service.
</p>
<p>
To make it known to the Turbine itself, you must configure it in
the
TurbineResources.properties like this:
<source>
services.MyServiceName.classname =
full.class.name.of.your.service
</source>
</p>
<p>
and you're set,
Turbine will now initialize the service if it is
requested by an application.
Please be aware that your service is
<b>not</b> initialized right at Startup.
This is called lazy init.
If you need your Service to start up right away, you
must add another
property to the TurbineResources.properties:
<source>
services.MyServiceName.earlyInit = true
</source>
</p>
<p>
If you look
at the examples of the simple services like
db/TurbinePoolBrokerService or
servlet/TurbineServletService you'll
get on speed pretty fast.
</p>
</section>
<section name="In a Nutshell">
<p>
<ul>
<li>
You must not try to provide a constructor with parameters, best is
not to
provide any constructor at all, because nothing should be
done at
construction time (You'll get the default constructor which
is fine for us).
</li>
<li>
Your Service will be instantiated exactly
once. So it must be
threadsafe and must not use class global variables for
session-dependend information.
</li>
<li>
You
should provide an init() method which is called when your
service is
requested for the first time (or at startup if you
set earlyInit = true)
and should initialize your service
dependent code. There is lots of
confusion of how this init()
method should look like because Turbine used
different methods
of Service initialization. Beginning with Turbine 2.2,
you should
only use the parameterless variant:
</li>
</ul>
</p>
<source>
public void init() throws InitializationException
{
}
</source>
<p>
<ul>
<li>
You <b>must</b> call setInit(true) if your
service initializes
correctly. Otherwise no user of your service can
request it.
Right after this, your service might be queried and used by
other
sessions, so you should not call setInit() prematurely.
</li>
<li>
You might provide a shutdown() method which is called when
Turbine shuts down. You can clean up your internal data in this
method. You should call setInit(false) as the last thing in
shutdown().
</li>
</ul>
</p>
</section>
<section name="Style">
<p>
It is
good style, that if you build the FooService, to provide
<b>your.package.FooService.java</b> with an Interface definition of
your
service which extends <b>org.apache.turbine.services.Service</b>
It should
contain a constant SERVICE_NAME with the Turbine visible
name of your service
like this:
<source>
package your.package;
import org.apache.turbine.services.Service;
public interface FooService extends Service
{
/**
* The service
identifier
*/
public String SERVICE_NAME = "FooService";
[...]
}
</source>
</p>
<p>
<b>your.package.TurbineFooService.java</b>
which extends the
<b>org.apache.turbine.services.TurbineBaseService</b> class
and
implements <b>your.package.FooService</b> and provides the actual code:
</p>
<source>
package your.package;
import
org.apache.turbine.services.TurbineBaseService;
public class TurbineFooService
extends TurbineBaseService
implements FooService
{
/**
* Service logic
here
*/
[...]
}
</source>
<p>
<b>your.package.TurbineFoo.java</b>
which contains static facade
methods for your service along the following
lines:
<source>
import org.apache.turbine.services.TurbineServices;
public class
TurbineFoo
{
protected static FooService getService()
{
return
(FooService) TurbineServices
.getInstance().getService(FooService.SERVICE_NAME);
}
[...]
public
static void fooMethod1()
{
getService().fooMethod1();
}
public
static int fooMethod2(int bar)
{
return getService().fooMethod2(bar);
}
[...]
}
</source>
</p>
<p>
to give users of your service
the ability to simply write:
<source>
TurbineFoo.fooMethod1();
</source>
</p>
<p>
in their code and not to care about which actual Implementation of
FooService is running.
</p>
<p>
init() and shutdown() applies to
Turbine 2.1/2.2 This might change
with the lifecycle interfaces in a later
release.
</p>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
