Differences between revisions 13 and 14
Revision 13 as of 2011-08-25 10:44:35
Size: 20157
Comment: Fix layout
Revision 14 as of 2013-03-02 10:19:11
Size: 20212
Comment: Update workaround
Deletions are marked like this. Additions are marked like this.
Line 525: Line 525:
 * The !TurbineYaafiComponentService tries to read its `containerConfiguration.xml` before the application root directory is set. The workaround is to set the path to the `containerConfiguration.xml` file to an absolute value.  * The !TurbineYaafiComponentService tries to read its `containerConfiguration.xml` before the application root directory is set. The workaround is to set the path to the `containerConfiguration.xml` file to `${applicationRoot}/WEB-INF/conf/containerConfiguration.xml` for example.

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

  • org.apache.turbine.util.parser.ParameterParser with org.apache.fulcrum.parser.ParameterParser

  • org.apache.turbine.services.intake.* with org.apache.fulcrum.intake.* (except IntakeTool)

  • org.apache.turbine.services.cache.* with org.apache.fulcrum.cache.*

  • ...

Gotchas

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

  • The TurbineYaafiComponentService tries to read its containerConfiguration.xml before the application root directory is set. The workaround is to set the path to the containerConfiguration.xml file to ${applicationRoot}/WEB-INF/conf/containerConfiguration.xml for example.

  • The macro #TurbineHtmlHead() doesn't work with style sheets. It uses the old methods of $page. As a workaround, place the file macros/TurbineMacros.vm from turbine-2.3.3.jar into the WEB-INF/classes directory of your web application.

  • The Intake fields are not initialized from the ParameterParser. No solution yet.

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