Start with the migration guide and report about your experiences here.

Migrating Turbine Services to Fulcrum Components

The Turbine services configuration used to live in WEB-INF/conf/TurbineResources.properties. The Avalon container uses two files to achieve the same function, namely WEB-INF/conf/roleConfiguration.xml to define which component is implemented by which class and WEB-INF/conf/componentConfiguration.xml to define the detailed configuration of each component.

Note: Most of the static Service Accessor classes have been removed. They need to be replaced by explicit lookups.

AvalonComponentService

The AvalonComponentService is the main service container for all Fulcrum Components. We replaced the deprecated Excalibur container with the Fulcrum YAAFI container by default. See YAAFI site for a description of the differences if you use other than the provided Avalon Services with Turbine.

Replace entry in TurbineResources.properties for the AvalonComponentService

services.AvalonComponentService.classname=org.apache.turbine.services.avaloncomponent.ACSYaafiComponentService

with the following entry

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

Be sure to have the line

# Determines if the component service should be initialized early.
services.AvalonComponentService.earlyInit=true

It starts the service container during the servlet start and makes sure that all Avalon components are available.

CryptoService

The TurbineCryptoService has been replaced with the Fulcrum Crypto counterpart. The following example shows the default configuration of the CryptoService before and after the migration. For details of the configuration options available see the Fulcrum Crypto Site.

TurbineResources.properties:

services.CryptoService.classname=org.apache.turbine.services.crypto.TurbineCryptoService

# -------------------------------------------------------------------
#
#  C R Y P T O   S E R V I C E
#
# -------------------------------------------------------------------

#
# Standard Unix crypt(3) password encryption.
#
services.CryptoService.algorithm.unix = org.apache.turbine.services.crypto.provider.UnixCrypt
#
# This providers allows access to the Java Message Digest encryption algorithms
#
services.CryptoService.algorithm.java = org.apache.turbine.services.crypto.provider.JavaCrypt
#
# This is a simple, cleartext "encryption" provider.
#
services.CryptoService.algorithm.cleartext = org.apache.turbine.services.crypto.provider.ClearCrypt
#
# Use this provider if you upgrade from Turbine 2.1 to current. It provides bug-to-bug
# compatibility for passwords created with the old Security Service. See the javadocs for
# OldJavaCrypt
#
services.CryptoService.algorithm.oldjava = org.apache.turbine.services.crypto.provider.OldJavaCrypt
#
# This is the default crypto provider. It implements the normal Java MessageDigest ciphers
# You need not to have this, it is the default if no algorithms are given. The default
# provider gives you all the Java MessageDigest Ciphers
#
services.CryptoService.algorithm.default = org.apache.turbine.services.crypto.provider.JavaCrypt

roleConfiguration.xml:

    <role
        name="org.apache.fulcrum.crypto.CryptoService"
        shorthand="crypto"
        default-class="org.apache.fulcrum.crypto.DefaultCryptoService"/>

componentConfiguration.xml:

    <crypto>
      <algorithm>
        <unix>org.apache.fulcrum.crypto.provider.UnixCrypt</unix>
        <clear>org.apache.fulcrum.crypto.provider.ClearCrypt</clear>
        <java>org.apache.fulcrum.crypto.provider.JavaCrypt</java>
        <oldjava>org.apache.fulcrum.crypto.provider.OldJavaCrypt</oldjava>
      </algorithm>
    </crypto>

FactoryService

The TurbineFactoryService has been replaced with the Fulcrum Factory counterpart. The following example shows the default configuration of the FactoryService before and after the migration. For details of the configuration options available see the Fulcrum Factory Site.

TurbineResources.properties:

services.FactoryService.classname=org.apache.turbine.services.factory.TurbineFactoryService

# -------------------------------------------------------------------
#
#  F A C T O R Y  S E R V I C E
#
# -------------------------------------------------------------------

# A comma separated list of classloaders (very optional)
#
# Example: org.foo.bar.MyClassLoader, org.ack.joe.YourClassLoader
#
#services.FactoryService.class.loaders=

# Customized factories to be used instead of the default factory.
# E.g. to instantiate XML parsers, SSL sockets, etc., which require
# specific instantiation not supported by the default factory.
# The property name is prefixed with "factory" followed by the
# name of the production class. The value is the class name of
# the factory implementing the Factory interface. The factory
# will be instantiated by using the service itself.
#
# Examples:
#
# services.FactoryService.factory.javax.xml.parsers.DocumentBuilder=org.foo.xml.DomBuilderFactory
# services.FactoryService.factory.javax.xml.parsers.SAXParser=org.foo.xml.SaxParserFactory
# services.FactoryService.factory.java.net.ServerSocket=org.foo.net.SslServerSocketFactory

roleConfiguration.xml:

    <role
        name="org.apache.fulcrum.factory.FactoryService"
        shorthand="factory"
        default-class="org.apache.fulcrum.factory.DefaultFactoryService"/>

componentConfiguration.xml:

    <factory/>

PoolService

The TurbinePoolService has been replaced with the Fulcrum Pool counterpart. The following example shows the default configuration of the PoolService before and after the migration. For details of the configuration options available see the Fulcrum Pool Site.

TurbineResources.properties:

services.PoolService.classname=org.apache.turbine.services.pool.TurbinePoolService

# -------------------------------------------------------------------
#
#  P O O L  S E R V I C E
#
# -------------------------------------------------------------------

# Default capacity of pools of the Object pooling service.
#
# Default: 128
services.PoolService.pool.capacity = 128

# Class specific capacities used instead of the default if specified.
#
services.PoolService.pool.capacity.org.apache.turbine.services.rundata.DefaultTurbineRunData=512

roleConfiguration.xml:

    <role
        name="org.apache.fulcrum.pool.PoolService"
        shorthand="pool"
        default-class="org.apache.fulcrum.pool.DefaultPoolService"/>

componentConfiguration.xml:

    <pool>
        <capacity>
            <org.apache.turbine.services.rundata.DefaultTurbineRunData>
                512
            </org.apache.turbine.services.rundata.DefaultTurbineRunData>
            <default>
                128
            </default>
        </capacity>
    </pool>

LocalizationService

The TurbineLocalizationService has been replaced with the Fulcrum Localization counterpart. The following example shows the default configuration of the LocalizationService before and after the migration. For details of the configuration options available see the Fulcrum Localization Site.

TurbineResources.properties:

services.LocalizationService.classname=org.apache.turbine.services.localization.TurbineLocalizationService

# -------------------------------------------------------------------
#
#  L O C A L I Z A T I O N  S E R V I C E
#
# -------------------------------------------------------------------

# Default ResourceBundle and language/country codes used by the
# TurbineLocalizationService.
#
locale.default.bundles=your.package.Bundle1,your.package.Bundle2
locale.default.language=en
locale.default.country=US

roleConfiguration.xml:

    <role
        name="org.apache.fulcrum.localization.LocalizationService"
        shorthand="localization"
        default-class="org.apache.fulcrum.localization.DefaultLocalizationService"/>

componentConfiguration.xml:

    <localization>
      <bundles locale-default-language="en" locale-default-country="US">
        <bundle>your.package.Bundle1</bundle>
        <bundle>your.package.Bundle1</bundle>
      </bundles>
    </localization>

MimeTypeService

The TurbineMimeTypeService has been replaced with the Fulcrum Mimetype counterpart. The following example shows the default configuration of the MimeTypeService before and after the migration. For details of the configuration options available see the Fulcrum Mimetype Site.

TurbineResources.properties:

services.MimeTypeService.classname=org.apache.turbine.services.mimetype.TurbineMimeTypeService

# -------------------------------------------------------------------
#
#  M I M E T Y P E  S E R V I C E
#
# -------------------------------------------------------------------

# This property specifies a file containing mappings between MIME
# content types and the corresponding file name extensions. The
# service itself contains a hardcoded set of most common mappings.
# The file must use the same syntax as the mime.types file of
# the Apache Server, i.e.
# <mimetype> <ext1> <ext2>...
#
services.MimeTypeService.mime.types=/WEB-INF/conf/mime.types

# This property specifies a file containing mappings between locales
# and the corresponding character encodings. The service itself
# contains a hardcoded set of most common mappings.
# The file should use the Java property file syntax, i.e.
# <lang_country_variant>=<charset>
#
services.MimeTypeService.charsets=/WEB-INF/conf/charset.properties

roleConfiguration.xml:

    <role
        name="org.apache.fulcrum.mimetype.MimeTypeService"
        shorthand="mimetype"
        default-class="org.apache.fulcrum.mimetype.DefaultMimeTypeService"/>

componentConfiguration.xml:

    <mimetype
        mimetypes="WEB-INF/conf/mime.types"
        charsets="WEB-INF/conf/charsets.properties" />

GlobalCacheService

The TurbineGlobalCacheService has been replaced with the Fulcrum Cache counterpart. The following example shows the default configuration of the GlobalCacheService before and after the migration. For details of the configuration options available see the Fulcrum Cache Site. Note that the cache check frequency is in seconds now, rather than milliseconds.

TurbineResources.properties:

services.GlobalCacheService.classname=org.apache.turbine.services.cache.TurbineGlobalCacheService

# -------------------------------------------------------------------
#
#  C A C H E   S E R V I C E
#
# -------------------------------------------------------------------

# Interval at which the cache will be checked. The default is
# 5000ms or 5 seconds.

services.GlobalCacheService.cache.check.frequency = 5000

roleConfiguration.xml:

    <role
        name="org.apache.fulcrum.cache.GlobalCacheService"
        shorthand="cache"
        default-class="org.apache.fulcrum.cache.impl.DefaultGlobalCacheService"/>

componentConfiguration.xml:

    <cache cacheInitialSize="20" cacheCheckFrequency="5"/>

UploadService

The TurbineUploadService has been replaced with the Fulcrum Upload counterpart. The following example shows the default configuration of the UploadService before and after the migration. For details of the configuration options available see the Fulcrum Upload Site. The automatic option has been moved to the ParserService.

TurbineResources.properties:

services.UploadService.classname=org.apache.turbine.services.upload.TurbineUploadService

# -------------------------------------------------------------------
#
#  U P L O A D  S E R V I C E
#
# -------------------------------------------------------------------

# Whether the files should be automatically picked up by
# ParameterParser.

services.UploadService.automatic=true

#
# The directory where files will be temporarily stored.
#
services.UploadService.repository=./tmp

#
# The maximum size of a request that will be processed.
#
services.UploadService.size.max=1048576

#
# The maximum size of a request that will have it's elements cached in
# memory by TurbineUploadService class.
#
services.UploadService.size.threshold=10240

roleConfiguration.xml:

    <role
        name="org.apache.fulcrum.upload.UploadService"
        shorthand="upload"
        default-class="org.apache.fulcrum.upload.DefaultUploadService"/>

componentConfiguration.xml:

    <upload repository="tmp" sizeMax="1048576" sizeThreshold="10240"/>

IntakeService

The TurbineIntakeService has been replaced with the Fulcrum Intake counterpart. The following example shows the default configuration of the IntakeService before and after the migration. For details of the configuration options available see the Fulcrum Intake Site.

TurbineResources.properties:

services.IntakeService.classname=org.apache.turbine.services.intake.TurbineIntakeService

# -------------------------------------------------------------------
#
#  I N T A K E   S E R V I C E
#
# -------------------------------------------------------------------

# The location of the xml file specifying valid inputs
#
# If you need to define multiple definition files, you can
# separate them with commas.
#
# Default: WEB-INF/conf/intake.xml
#
services.IntakeService.xml.path=WEB-INF/conf/intake.xml

# This file is used to cache the XML definitions after they are
# parsed.  It provides for a small performance gain on startup.
#
# Note: Even if you have multiple XML definition files, you will
# only need one serialization file!
#
# Default: WEB-INF/appData.ser
#
services.IntakeService.serialize.path=WEB-INF/appData.ser

roleConfiguration.xml:

    <role
        name="org.apache.fulcrum.intake.IntakeService"
        shorthand="intake"
        default-class="org.apache.fulcrum.intake.IntakeServiceImpl"/>

componentConfiguration.xml:

    <intake>
      <serialDataPath>WEB-INF/appData.ser</serialDataPath>
      <xmlPaths>
        <xmlPath>WEB-INF/conf/intake1.xml</xmlPath>
        <xmlPath>WEB-INF/conf/intake2.xml</xmlPath>
      </xmlPaths>
    </intake>

Added Components

ParserService

The different parser types (ParameterParser, CookieParser etc) as used in Turbine 2.3.3 are now being managed by a separate component called ParserService. The component provides initialized parser objects and manages them in a pool. The following example shows the default configuration of the parsers before and after the migration. For details of the configuration options available see the Fulcrum Parser Site.

Note: One of the main changes in the code of your Turbine modules probably is the replacement of org.apache.turbine.util.parser.ParameterParser with org.apache.fulcrum.parser.ParameterParser.

TurbineResources.properties:

services.RunDataService.default.parameter.parser=org.apache.turbine.util.parser.DefaultParameterParser
services.RunDataService.default.cookie.parser=org.apache.turbine.util.parser.DefaultCookieParser

#--------------------------------------------------------------------
#
# P A R A M E T E R  P A R S E R
#
#--------------------------------------------------------------------
#
# This variable controls the case folding applied to URL variable
# names.
#
# Allowed values: none, lower, upper
# Default: lower
#

url.case.folding=lower

New TurbineResources.properties:

services.RunDataService.default.parameter.parser=org.apache.fulcrum.parser.DefaultParameterParser
services.RunDataService.default.cookie.parser=org.apache.fulcrum.parser.DefaultCookieParser

roleConfiguration.xml:

    <role
        name="org.apache.fulcrum.parser.ParserService"
        shorthand="parser"
        default-class="org.apache.fulcrum.parser.DefaultParserService"/>

componentConfiguration.xml:

    <parser>
        <urlCaseFolding>lower</urlCaseFolding>
        <parameterEncoding>utf-8</parameterEncoding>
        <automaticUpload>true</automaticUpload>
    </parser>

Further Modifications

Add Pipeline Configuration

Turbine 4.0 comes with the feature to modify the processing sequence of modules during a request using the so-called pipeline. This can be configured in the file turbine-classic-pipeline.xml. The file actually used can be modified in TurbineResources.properties. The default content of turbine-classic-pipeline.xml as shown below models the way Turbine 2.3.3 used to handle requests. Place this file into WEB-INF/conf.

<?xml version="1.0" encoding="UTF-8"?>
<org.apache.turbine.pipeline.TurbinePipeline>
  <valves>
    <org.apache.turbine.pipeline.DetermineActionValve/>
    <org.apache.turbine.pipeline.DetermineTargetValve/>
    <org.apache.turbine.pipeline.DefaultSessionTimeoutValve/>
    <org.apache.turbine.pipeline.DefaultLoginValve/>
    <org.apache.turbine.pipeline.DefaultSessionValidationValve/>
    <org.apache.turbine.pipeline.DefaultACLCreationValve/>
    <org.apache.turbine.pipeline.ExecutePageValve/>
    <org.apache.turbine.pipeline.CleanUpValve/>
    <org.apache.turbine.pipeline.DetermineRedirectRequestedValve/>
  </valves>
</org.apache.turbine.pipeline.TurbinePipeline>

Replace Imports

Gotchas

The following problems/bugs have surfaced during test migrations. If possible, a workaround is provided.

Turbine4/Turbine4.0M1/Migrate233 (last edited 2013-03-02 10:19:11 by ThomasVandahl)