howto/services-howto.html - turbine-core.git - Git at Google

 <!DOCTYPE html>


 <!--
  | Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/howto/services-howto.xml at 10 Sep 2025
  | Rendered using Apache Maven Fluido Skin 2.1.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
     <title>Services Howto – Apache Turbine</title>
     <link rel="stylesheet" href="../css/apache-maven-fluido-2.1.0.min.css" />
     <link rel="stylesheet" href="../css/site.css" />
     <link rel="stylesheet" href="../css/print.css" media="print" />
     <script src="../js/apache-maven-fluido-2.1.0.min.js"></script>
 <link rel="icon" type="image/png" sizes="48x48" href="https://apache.org/favicons/favicon.ico">
       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
     <style>.github-fork-ribbon:before { background-color: orange; }</style>
   </head>
   <body>
     <a class="github-fork-ribbon right-top" href="https://github.com/apache/turbine-build" data-ribbon="Fork me on GitHub">Fork me on GitHub</a>
     <div class="container-fluid container-fluid-top">
       <header>
         <div id="banner">
           <div class="pull-left"><div id="bannerLeft"><h1><a href="https://turbine.apache.org/"><img src="https://www.apache.org/img/feather_glyph_notm.png" style="width: 50px;" /> The Apache Turbine project</a></h1></div></div>
           <div class="pull-right"><div id="bannerRight"><h1><a href="https://turbine.apache.org/"><img src="https://turbine.apache.org/images/logo.gif" alt="Apache Turbine" /></a></h1></div></div>
           <div class="clear"><hr/></div>
         </div>

         <div id="breadcrumbs">
           <ul class="breadcrumb">
         <li id="publishDate">Last Published: 01 Apr 2025<span class="divider">|</span>
 </li>
           <li id="projectVersion">Version: 7.1-SNAPSHOT</li>
         <li class="pull-right"><span class="divider">|</span>
 <a href="https://turbine.apache.org/fulcrum/">Fulcrum</a></li>
         <li class="pull-right"><span class="divider">|</span>
 <a href="https://turbine.apache.org/">Turbine</a></li>
         <li class="pull-right"><a href="https://www.apache.org">Apache</a></li>
           </ul>
         </div>
       </header>
       <div class="row-fluid">
         <header id="leftColumn" class="span2">
           <nav class="well sidebar-nav">
   <ul class="nav nav-list">
    <li class="nav-header">General Information</li>
     <li><a href="../index.html">Overview</a></li>
     <li><a href="../features.html">Features</a></li>
     <li><a href="../fsd.html">Specification</a></li>
     <li><a href="../getting-started.html">Getting Started</a></li>
     <li><a href="../how-to-build.html">Howto Build Turbine</a></li>
     <li><a href="../changes-report.html">Changes</a></li>
    <li class="nav-header">Documentation</li>
     <li><a href="../services/index.html"><span class="icon-chevron-right"></span>Services</a></li>
     <li><a href="../howto/index.html"><span class="icon-chevron-down"></span>Howtos</a>
      <ul class="nav nav-list">
       <li><a href="../howto/action-event-howto.html">Action Events Howto</a></li>
       <li><a href="../howto/annotations.html">Annotations Howto</a></li>
       <li><a href="../howto/configuration-howto.html">Configuration Howto</a></li>
       <li><a href="../howto/extend-user-howto.html">Extend User Howto</a></li>
       <li><a href="../howto/hibernate-howto.html">Hibernate OM Howto</a></li>
       <li><a href="../howto/intake-howto.html">Intake Howto</a></li>
       <li><a href="../howto/jsp-howto.html">JSP Howto</a></li>
       <li><a href="../howto/migrate-from-2_1-howto.html">Migrating from 2.1 to 2.2</a></li>
       <li><a href="../howto/migrate-from-2_2-howto.html">Migrating from 2.2 to 2.3</a></li>
       <li><a href="../howto/migrate-from-2_3-howto.html">Migrating from 2.3 to 4.0</a></li>
       <li><a href="../howto/migrate-from-4_0-howto.html">Migrating from 4.0 to 5.0</a></li>
       <li><a href="../howto/pullmodel-howto.html">Pull Model Howto</a></li>
       <li><a href="../howto/python-howto.html">Python Howto</a></li>
       <li><a href="../howto/security-howto.html">Security Howto</a></li>
       <li class="active"><a>Services Howto</a></li>
       <li><a href="../howto/url-mapper-howto.html">URL Mapper Howto</a></li>
       <li><a href="../howto/url-rewriting-howto.html">URL Rewriting Howto</a></li>
       <li><a href="../howto/context-howto.html">Velocity Context Howto</a></li>
       <li><a href="../howto/velocity-site-howto.html">Velocity Site Howto</a></li>
       <li><a href="../howto/velocityonlylayout-howto.html">VelocityOnlyLayout Howto</a></li>
      </ul></li>
     <li><a href="https://cwiki.apache.org/confluence/display/TURBINE">Wiki</a></li>
     <li><a href="../apidocs/index.html">JavaDocs</a></li>
    <li class="nav-header">Development</li>
     <li><a href="../proposals.html">Proposals</a></li>
     <li><a href="../how-to-help.html">How To Help</a></li>
     <li><a href="../todo.html">Todo</a></li>
    <li class="nav-header">Project Documentation</li>
     <li><a href="../project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>
     <li><a href="../project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li>
    <li class="nav-header">Apache</li>
     <li><a href="https://www.apache.org/">Apache Website</a></li>
     <li><a href="https://www.apache.org/licenses/">License</a></li>
     <li><a href="https://www.apache.org/foundation/how-it-works.html">How the ASF works</a></li>
     <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
     <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li>
     <li><a href="https://www.apache.org/security/">Security</a></li>
   </ul>
           </nav>
           <div class="well sidebar-nav">
 <form id="search-form" action="https://www.google.com/search" method="get" >
   <input value="http://turbine.apache.org/turbine/turbine-7-0" name="sitesearch" type="hidden" />
   <input class="search-query" name="q" id="query" type="text" placeholder="Search with Google..." />
 </form>
             <div id="poweredBy">
               <div class="clear"></div>
               <div class="clear"></div>
 <a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
             </div>
           </div>
         </header>
         <main id="bodyColumn" class="span10">


   <section><a id="Turbine_Services_Creation"></a>
 <h1>Turbine Services Creation</h1>

 <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:

 </p>
 <pre class="prettyprint"><code>
 services.MyServiceName.classname = full.class.name.of.your.service
 </code></pre>


 <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:

 </p>
 <pre class="prettyprint"><code>
 services.MyServiceName.earlyInit = true
 </code></pre>


 <p>
       If you look at the examples of the simple services like
       servlet/TurbineServletService you'll get on speed pretty fast.
     </p>
 </section>

 <section><a id="In_a_Nutshell"></a>
 <h1>In a Nutshell</h1>

 <p>
       </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-dependent 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>


 <pre class="prettyprint"><code>
 public void init() throws InitializationException
 {
 }
 </code></pre>

 <p>
       </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>

 </section>

 <section><a id="Style"></a>
 <h1>Style</h1>

 <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:
 </p>
 <pre class="prettyprint"><code>
 package your.package;

 import org.apache.turbine.services.Service;

 public interface FooService extends Service
 {
     /**
      * The service identifier
      */
     public String SERVICE_NAME = &quot;FooService&quot;;

     [...]

 }
 </code></pre>


 <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>


 <pre class="prettyprint"><code>
 package your.package;

 import org.apache.turbine.services.TurbineBaseService;

 public class TurbineFooService
     extends TurbineBaseService
     implements FooService
 {
     /**
      * Service logic here
      */
     [...]

 }
 </code></pre>


 <p>
       <b>your.package.TurbineFoo.java</b> which contains static facade
       methods for your service along the following lines:

 </p>
 <pre class="prettyprint"><code>
 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);
     }

     [...]

 }
 </code></pre>


 <p>
       to give users of your service the ability to simply write:

 </p>
 <pre class="prettyprint"><code>
 TurbineFoo.fooMethod1();
 </code></pre>


 <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-5 This might change
       with the lifecycle interfaces in a later release.
     </p>
 </section>


         </main>
       </div>
     </div>
     <hr/>
     <footer>
       <div class="container-fluid">
         <div class="row-fluid">
             <p>©      2000–2025
 <a href="https://www.apache.org/">The Apache Software Foundation</a>
 </p>
         </div>
       </div>
     </footer>
   </body>
 </html>
	<!DOCTYPE html>


	<!--
	\| Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/howto/services-howto.xml at 10 Sep 2025
	\| Rendered using Apache Maven Fluido Skin 2.1.0
	-->
	<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
	<head>
	<meta charset="UTF-8" />
	<meta name="viewport" content="width=device-width, initial-scale=1" />
	<meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
	<title>Services Howto – Apache Turbine</title>
	<link rel="stylesheet" href="../css/apache-maven-fluido-2.1.0.min.css" />
	<link rel="stylesheet" href="../css/site.css" />
	<link rel="stylesheet" href="../css/print.css" media="print" />
	<script src="../js/apache-maven-fluido-2.1.0.min.js"></script>
	<link rel="icon" type="image/png" sizes="48x48" href="https://apache.org/favicons/favicon.ico">
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<style>.github-fork-ribbon:before { background-color: orange; }</style>
	</head>
	<body>
	<a class="github-fork-ribbon right-top" href="https://github.com/apache/turbine-build" data-ribbon="Fork me on GitHub">Fork me on GitHub</a>
	<div class="container-fluid container-fluid-top">
	<header>
	<div id="banner">
	<div class="pull-left"><div id="bannerLeft"><h1><a href="https://turbine.apache.org/"><img src="https://www.apache.org/img/feather_glyph_notm.png" style="width: 50px;" /> The Apache Turbine project</a></h1></div></div>
	<div class="pull-right"><div id="bannerRight"><h1><a href="https://turbine.apache.org/"><img src="https://turbine.apache.org/images/logo.gif" alt="Apache Turbine" /></a></h1></div></div>
	<div class="clear"><hr/></div>
	</div>

	<div id="breadcrumbs">
	<ul class="breadcrumb">
	<li id="publishDate">Last Published: 01 Apr 2025<span class="divider">\|</span>
	</li>
	<li id="projectVersion">Version: 7.1-SNAPSHOT</li>
	<li class="pull-right"><span class="divider">\|</span>
	<a href="https://turbine.apache.org/fulcrum/">Fulcrum</a></li>
	<li class="pull-right"><span class="divider">\|</span>
	<a href="https://turbine.apache.org/">Turbine</a></li>
	<li class="pull-right"><a href="https://www.apache.org">Apache</a></li>
	</ul>
	</div>
	</header>
	<div class="row-fluid">
	<header id="leftColumn" class="span2">
	<nav class="well sidebar-nav">
	<ul class="nav nav-list">
	<li class="nav-header">General Information</li>
	<li><a href="../index.html">Overview</a></li>
	<li><a href="../features.html">Features</a></li>
	<li><a href="../fsd.html">Specification</a></li>
	<li><a href="../getting-started.html">Getting Started</a></li>
	<li><a href="../how-to-build.html">Howto Build Turbine</a></li>
	<li><a href="../changes-report.html">Changes</a></li>
	<li class="nav-header">Documentation</li>
	<li><a href="../services/index.html"><span class="icon-chevron-right"></span>Services</a></li>
	<li><a href="../howto/index.html"><span class="icon-chevron-down"></span>Howtos</a>
	<ul class="nav nav-list">
	<li><a href="../howto/action-event-howto.html">Action Events Howto</a></li>
	<li><a href="../howto/annotations.html">Annotations Howto</a></li>
	<li><a href="../howto/configuration-howto.html">Configuration Howto</a></li>
	<li><a href="../howto/extend-user-howto.html">Extend User Howto</a></li>
	<li><a href="../howto/hibernate-howto.html">Hibernate OM Howto</a></li>
	<li><a href="../howto/intake-howto.html">Intake Howto</a></li>
	<li><a href="../howto/jsp-howto.html">JSP Howto</a></li>
	<li><a href="../howto/migrate-from-2_1-howto.html">Migrating from 2.1 to 2.2</a></li>
	<li><a href="../howto/migrate-from-2_2-howto.html">Migrating from 2.2 to 2.3</a></li>
	<li><a href="../howto/migrate-from-2_3-howto.html">Migrating from 2.3 to 4.0</a></li>
	<li><a href="../howto/migrate-from-4_0-howto.html">Migrating from 4.0 to 5.0</a></li>
	<li><a href="../howto/pullmodel-howto.html">Pull Model Howto</a></li>
	<li><a href="../howto/python-howto.html">Python Howto</a></li>
	<li><a href="../howto/security-howto.html">Security Howto</a></li>
	<li class="active"><a>Services Howto</a></li>
	<li><a href="../howto/url-mapper-howto.html">URL Mapper Howto</a></li>
	<li><a href="../howto/url-rewriting-howto.html">URL Rewriting Howto</a></li>
	<li><a href="../howto/context-howto.html">Velocity Context Howto</a></li>
	<li><a href="../howto/velocity-site-howto.html">Velocity Site Howto</a></li>
	<li><a href="../howto/velocityonlylayout-howto.html">VelocityOnlyLayout Howto</a></li>
	</ul></li>
	<li><a href="https://cwiki.apache.org/confluence/display/TURBINE">Wiki</a></li>
	<li><a href="../apidocs/index.html">JavaDocs</a></li>
	<li class="nav-header">Development</li>
	<li><a href="../proposals.html">Proposals</a></li>
	<li><a href="../how-to-help.html">How To Help</a></li>
	<li><a href="../todo.html">Todo</a></li>
	<li class="nav-header">Project Documentation</li>
	<li><a href="../project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>
	<li><a href="../project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li>
	<li class="nav-header">Apache</li>
	<li><a href="https://www.apache.org/">Apache Website</a></li>
	<li><a href="https://www.apache.org/licenses/">License</a></li>
	<li><a href="https://www.apache.org/foundation/how-it-works.html">How the ASF works</a></li>
	<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
	<li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li>
	<li><a href="https://www.apache.org/security/">Security</a></li>
	</ul>
	</nav>
	<div class="well sidebar-nav">
	<form id="search-form" action="https://www.google.com/search" method="get" >
	<input value="http://turbine.apache.org/turbine/turbine-7-0" name="sitesearch" type="hidden" />
	<input class="search-query" name="q" id="query" type="text" placeholder="Search with Google..." />
	</form>
	<div id="poweredBy">
	<div class="clear"></div>
	<div class="clear"></div>
	<a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
	</div>
	</div>
	</header>
	<main id="bodyColumn" class="span10">



	<section><a id="Turbine_Services_Creation"></a>
	<h1>Turbine Services Creation</h1>

	<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:

	</p>
	<pre class="prettyprint"><code>
	services.MyServiceName.classname = full.class.name.of.your.service
	</code></pre>



	<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:

	</p>
	<pre class="prettyprint"><code>
	services.MyServiceName.earlyInit = true
	</code></pre>



	<p>
	If you look at the examples of the simple services like
	servlet/TurbineServletService you'll get on speed pretty fast.
	</p>
	</section>

	<section><a id="In_a_Nutshell"></a>
	<h1>In a Nutshell</h1>

	<p>
	</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-dependent 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>


	<pre class="prettyprint"><code>
	public void init() throws InitializationException
	{
	}
	</code></pre>

	<p>
	</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>

	</section>

	<section><a id="Style"></a>
	<h1>Style</h1>

	<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:
	</p>
	<pre class="prettyprint"><code>
	package your.package;

	import org.apache.turbine.services.Service;

	public interface FooService extends Service
	{
	/**
	* The service identifier
	*/
	public String SERVICE_NAME = "FooService";

	[...]

	}
	</code></pre>



	<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>


	<pre class="prettyprint"><code>
	package your.package;

	import org.apache.turbine.services.TurbineBaseService;

	public class TurbineFooService
	extends TurbineBaseService
	implements FooService
	{
	/**
	* Service logic here
	*/
	[...]

	}
	</code></pre>


	<p>
	<b>your.package.TurbineFoo.java</b> which contains static facade
	methods for your service along the following lines:

	</p>
	<pre class="prettyprint"><code>
	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);
	}

	[...]

	}
	</code></pre>



	<p>
	to give users of your service the ability to simply write:

	</p>
	<pre class="prettyprint"><code>
	TurbineFoo.fooMethod1();
	</code></pre>



	<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-5 This might change
	with the lifecycle interfaces in a later release.
	</p>
	</section>


	</main>
	</div>
	</div>
	<hr/>
	<footer>
	<div class="container-fluid">
	<div class="row-fluid">
	<p>© 2000–2025
	<a href="https://www.apache.org/">The Apache Software Foundation</a>
	</p>
	</div>
	</div>
	</footer>
	</body>
	</html>