howto/migrate-from-2_3-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/migrate-from-2_3-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>Migrating from 2.3 to 4.0 – 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 class="active"><a>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><a href="../howto/services-howto.html">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="Introduction"></a>
 <h1>Introduction</h1>

 <p>
     This document describes the basic steps needed to migrate an
     application written for Turbine 2.3 to Turbine 4.0.
 </p>

 <p>
 	Migrating from Turbine 2.3 to Turbine 4.0 is mostly a task of
 	moving from the old service format to the new one. One of the
 	biggest purposes with Turbine 4 was to decouple the different services
 	and move them to <a href="http://turbine.apache.org/fulcrum/" class="externalLink">Fulcrum</a>.
 	Many of the released components of Fulcrum correspond to
 	a previous Turbine service that is no longer bundled with the
 	Turbine core.
 </p>

 <p>
 	The services has been converted to Avalon components and do not
 	implement the Service interface any more. Turbine still handles
 	services that do implement the Service interface though so no
 	rewrite is necessary if you have written services of your own.
 	The new services can also be accessed in pretty much the same way
 	as the old ones, as long as the AvalonComponentService is properly configured.
 </p>
 </section>

 <section><a id="Accessing_the_new_services"></a>
 <h1>Accessing the new services</h1>

 <p>
 	What needs to be done to access the decoupled services can be
 	summarised in 4 steps:
 	</p>
 <ul>

 <li>Make sure the AvalonComponentService is properly configured</li>

 <li>Add the services you need to your project dependency and to roleConfiguration.xml</li>

 <li>Access the Fulcrum services with class name instead of service name</li>

 <li>Remove any reference to the static facade classes and access the interfaces directly</li>
 	</ul>

 <section><a id="Make_sure_the_AvalonComponentService_is_properly_configured"></a>
 <h2>Make sure the AvalonComponentService is properly configured</h2>

 <p>
 	The AvalonComponentService allows you to retrieve the new services
 	via the old TurbineServices interface. Make sure that the AvalonComponentService
 	is added in your TurbineResources.properties and that you use TurbineYaafiComponentService as
 	the implementing class.
 </p>

 <pre class="prettyprint"><code>

 services.AvalonComponentService.classname=org.apache.turbine.services.avaloncomponent.TurbineYaafiComponentService
 services.AvalonComponentService.earlyInit=true

 </code></pre>

 <p>
 	The service <em>must</em> be the first service in TurbineResources.properties and it <em>must</em> be initialized early.
 	Also make sure that <a href="http://turbine.apache.org/fulcrum/fulcrum-yaafi/" class="externalLink">Fulcrum YAAFI</a>
 	is added to your project dependency.
 </p>
 </section>
 <section><a id="Add_the_services_you_need_to_your_project_dependency_and_to_roleConfiguration.xml"></a>
 <h2>Add the services you need to your project dependency and to roleConfiguration.xml</h2>

 <p>
 	Many services that were previously included in Turbine has been converted to Avalon
 	components and moved to Fulcrum. You only need to add the ones used in your project as
 	a dependency. Each service has its own documentation and it is described on their project
 	page how you can configure them, but common for all is that they need to be added to your
 	roleConfiguration.xml file. Adding a service to roleConfiguration.xml is equivalent to adding
 	a Turbine service to TurbineResources.properties.
 </p>
 </section>
 <section><a id="Access_the_Fulcrum_services_with_class_name_instead_of_service_name"></a>
 <h2>Access the Fulcrum services with class name instead of service name</h2>

 <p>
 	As you may have noticed in the documentation for the Fulcrum components, the name for
 	the different services is the full class name. Therefore the input parameter in the
 	getService method of TurbineServices needs to be the full class name of the service.
 	Usually this is stored in a static field called ROLE. Ex:
 </p>

 <pre class="prettyprint"><code>

 ParseService parserService = (ParserService)TurbineServices.getInstance().getService(ParserService.ROLE);

 </code></pre>
 </section>
 <section><a id="Remove_any_reference_to_the_static_facade_classes_and_access_the_interfaces_directly"></a>
 <h2>Remove any reference to the static facade classes and access the interfaces directly</h2>

 <p>
 	The new services do not have a static facade class like the old ones
 	(org.apache.turbine.services.localization.Localization for LocalizationService,
 	org.apache.turbine.services.cache.TurbineGlobalCache for GlobalCacheService etc).
 	If you have used these facade classes, you now need to access the service directly via
 	the interface instead. How to access the classes is described in the previous section.
 </p>
 </section>
 </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/migrate-from-2_3-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>Migrating from 2.3 to 4.0 – 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 class="active"><a>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><a href="../howto/services-howto.html">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="Introduction"></a>
	<h1>Introduction</h1>

	<p>
	This document describes the basic steps needed to migrate an
	application written for Turbine 2.3 to Turbine 4.0.
	</p>

	<p>
	Migrating from Turbine 2.3 to Turbine 4.0 is mostly a task of
	moving from the old service format to the new one. One of the
	biggest purposes with Turbine 4 was to decouple the different services
	and move them to <a href="http://turbine.apache.org/fulcrum/" class="externalLink">Fulcrum</a>.
	Many of the released components of Fulcrum correspond to
	a previous Turbine service that is no longer bundled with the
	Turbine core.
	</p>

	<p>
	The services has been converted to Avalon components and do not
	implement the Service interface any more. Turbine still handles
	services that do implement the Service interface though so no
	rewrite is necessary if you have written services of your own.
	The new services can also be accessed in pretty much the same way
	as the old ones, as long as the AvalonComponentService is properly configured.
	</p>
	</section>

	<section><a id="Accessing_the_new_services"></a>
	<h1>Accessing the new services</h1>

	<p>
	What needs to be done to access the decoupled services can be
	summarised in 4 steps:
	</p>
	<ul>

	<li>Make sure the AvalonComponentService is properly configured</li>

	<li>Add the services you need to your project dependency and to roleConfiguration.xml</li>

	<li>Access the Fulcrum services with class name instead of service name</li>

	<li>Remove any reference to the static facade classes and access the interfaces directly</li>
	</ul>

	<section><a id="Make_sure_the_AvalonComponentService_is_properly_configured"></a>
	<h2>Make sure the AvalonComponentService is properly configured</h2>

	<p>
	The AvalonComponentService allows you to retrieve the new services
	via the old TurbineServices interface. Make sure that the AvalonComponentService
	is added in your TurbineResources.properties and that you use TurbineYaafiComponentService as
	the implementing class.
	</p>

	<pre class="prettyprint"><code>

	services.AvalonComponentService.classname=org.apache.turbine.services.avaloncomponent.TurbineYaafiComponentService
	services.AvalonComponentService.earlyInit=true

	</code></pre>

	<p>
	The service <em>must</em> be the first service in TurbineResources.properties and it <em>must</em> be initialized early.
	Also make sure that <a href="http://turbine.apache.org/fulcrum/fulcrum-yaafi/" class="externalLink">Fulcrum YAAFI</a>
	is added to your project dependency.
	</p>
	</section>
	<section><a id="Add_the_services_you_need_to_your_project_dependency_and_to_roleConfiguration.xml"></a>
	<h2>Add the services you need to your project dependency and to roleConfiguration.xml</h2>

	<p>
	Many services that were previously included in Turbine has been converted to Avalon
	components and moved to Fulcrum. You only need to add the ones used in your project as
	a dependency. Each service has its own documentation and it is described on their project
	page how you can configure them, but common for all is that they need to be added to your
	roleConfiguration.xml file. Adding a service to roleConfiguration.xml is equivalent to adding
	a Turbine service to TurbineResources.properties.
	</p>
	</section>
	<section><a id="Access_the_Fulcrum_services_with_class_name_instead_of_service_name"></a>
	<h2>Access the Fulcrum services with class name instead of service name</h2>

	<p>
	As you may have noticed in the documentation for the Fulcrum components, the name for
	the different services is the full class name. Therefore the input parameter in the
	getService method of TurbineServices needs to be the full class name of the service.
	Usually this is stored in a static field called ROLE. Ex:
	</p>

	<pre class="prettyprint"><code>

	ParseService parserService = (ParserService)TurbineServices.getInstance().getService(ParserService.ROLE);

	</code></pre>
	</section>
	<section><a id="Remove_any_reference_to_the_static_facade_classes_and_access_the_interfaces_directly"></a>
	<h2>Remove any reference to the static facade classes and access the interfaces directly</h2>

	<p>
	The new services do not have a static facade class like the old ones
	(org.apache.turbine.services.localization.Localization for LocalizationService,
	org.apache.turbine.services.cache.TurbineGlobalCache for GlobalCacheService etc).
	If you have used these facade classes, you now need to access the service directly via
	the interface instead. How to access the classes is described in the previous section.
	</p>
	</section>
	</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>