##### General Information

- Overview
- Features
- Specification
- Getting Started
- Howto Build Turbine
- Changes

##### Documentation

- Services
- Howtos
- Wiki
- JavaDocs

##### Development

- Proposals
- How To Help
- Todo

##### Project Documentation

- Project Information
- Project Reports

##### Apache

- Apache Website
- License
- How the ASF works
- Sponsorship
- Thanks
- Security

Latest changes are available from Changes Report.

## Turbine 2.3

Changes between Turbine 2.2 and 2.3.

### Building

- It is now necessary to use Maven to build Turbine 2.3. The old, ant-based build system is no longer supported and actively removed from the distribution.
- Turbine requires the Maven Torque plugin to build. If you don't use at least Maven 1.0b9, you will have to install it manually before you can recompile the source code.

### Changes that could break older environments

- The IntakeService has been refactored, introducing two Abstract classes; the DefaultValidator and the NumberValidator. They both contain rules which are applicable to all Validator's and NumbeValidator's respectively. Unnecessary use was being made of (Old) NumberValidator which used BigDecimals, cleaned this up implementing concrete classes for all Number Types. Simplified definition of (number & required) rules in Intake.xml.
- The LoginUser action no longer checks to see if the user object is already in the session and returns if it is found. The user will always be there now. If you have a custom LoginUser action that still performs this check, you will need to remove it in order for your login action to work.
- AccessControlList is now an interface and its implementation is in TurbineAccessControlList. This is now configurable and can be replaced by a custom AccessControlList implementation. If older compiled code suddently throws IncompatibleClassChange errors, just recompile and they go away.
- All deprecated java code was removed (incl. support for webmacro, freemarker and castor). Make sure to not get any deprecation warnings before you switch to 2.3!
- The LoggingService was removed. Deprecated everything in the utils.Log class.
- The TurbineResources Service was removed and replaced with commons-configuration.
- The service initialization code has been changed. This is important if you write services yourself. You should supply a constructor which takes no parameters. The usage of a constructor which takes a RunData object is deprecated and might be removed later. If you're using the supplied services, you shouldn't notice any change.
- TTWS38: BaseValueParser.getInteger(String name) now returns null if the key name is not found - the old behaviour was to return new Integer(0). For consistency a similar change was made to getBool() and getBigInteger().
- The velocity mail classes (o.a.t.util.velocity package) now throw VelocityEmailException instead of MessagingException if a problem occurs.
- The handling of "," as a separator in template names was tightened and clarified. Many places where you could get away with using "/" as a separator or use a leading "/" for a template name now no longer work. There is a long description on how to use and not to use this in the javadoc for org.apache.turbine.services.template.TurbineTemplateService. If you want to volunteer for work on Turbine, feel free to whip this into an xdoc and put it into the documentation tree.
- Some classes have been moved into different packages to allow cleanup and clarification of their usage. The old locations are still available but deprecated. Examples are the parser classes from org.apache.turbine.util to org.apache.turbine.util.parser and some of the pull tools from org.apache.turbine.util.pull to org.apache.turbine.services.pull.tools
- getSizeMax() in the UploadService interface and implementations changed from int to long to reflect a change that was made in the underlying commons-fileupload component.

### Other changes

- Added ability to specify either the class TurbineResources.properties file or a new TurbineConfiguration.xml file. TurbineConfiguration.xml allows Turbine to pull it's configuration values from multiple locations. Please read the howto for more information.
- Added a Howto describing using Hibernate with Turbine. The actual code is currently not part of the Turbine distrib due to licensing issues, but is very easy to implement due to Turbine support of Avalon Components.
- Changed TurbineUser so that when either perment or temporary values are stored, if the required hashtable was missing, then it was created. This happened in conjunction with the PassiveUserManager. Additionally, the setTempStorage(Hashtable newTempStorage) did not actually assign the new Hashtable. Cleaned up some of the code so the parallel permanent and temp data storage methods followed the same patterns. Created a cactus testcase to test TurbineUser.
- Changed scheduler so that if it is NOT enabled, then it doesn't attempt to connect to the database and retrieve jobs. This prevents a spurious no data source error from showing up in the turbine logs on startup. Added a cactus test to test the fix.
- A new pull tool is available in the session scope called $sessionData. This tool can be used to store data that will persist for the duration of the session. This should be used instead of the getTemp() and setTemp() methods in TurbineUser.
- The use of getPerm() and setPerm() methods in Turbine user have been deprecated. See the Extending Turbine User how-to for using additional database columns for storage if you are using the DBSecurityService. You can also switch to the TorqueSecurityService where it is much easier to use additional columns.
- Perm scope pull tools have been deprecated. If you use these type of tools, you need to switch to authorized scope pull tools. These tools are initialized with a user object. Any state information that you were storing in the tools itself, you will now need to store in the user object.
- Turbine used to remove all data from the session before executing the login action. This no longer happens. Instead, the session is invalidated before calling to logout action.
- There is a new pull tool that makes it easy to format Date objects into Strings. See org.apache.turbine.services.pull.util.DateFormatter for details.
- Backported the Scheduler service from Fulcrum. Other Scheduler related changes include:
  - The scheduler can now be enabled/disabled while Turbine is running.
  - A new pull tool is available to allow access to the Scheduler service from Velocity templates. See org.apache.turbine.service.scheduler.SchedulerTool for details.
  - TurbineException is now thrown instead of Exception.
  - Torque generated objects are now used to for accessing the database. You can now add additional fields for the OM objects without modifing the source code. The OM objects are generated from scheduler-schema.xml
  - updateJob(job) can be used to add a new job. It will perform the correct action (insert or update) for you. addJob(job) simply calls updateJob(job).
  - A new fascade class has been created for easier access to the Scheduler Service. It is org.apache.turbine.services.schedule.TurbineScheduler.
- Backported the Crypto Service from Fulcrum.
- TTWS24: With this patch LDAP security services can have users, groups, roles and permissions in the LDAP repository. It also works with users in LDAP and the rest in the Database.
  Sample configuration files for Openldap can be found here
- TTWS34: Implemented the following functions in LDAPUserManager: store(), createAccount() and removeAccount().
- added new Logging code which uses commons-logging everywhere.
- added new Configuration code based on commons-configuration. Switched all configuration requests to commons-configuration.
  - Configuration values can now be stored in XML, .properties, as well as JNDI Tree.
  - Configuration values can be overridden. If you specify JNDI and the .xml, if a value is found in JNDI, then it is used. Useful for overriding environment specific values like mail servers or whether Velocity templates are reloadable.
- added Log4j configuration and startup.
- removed all remaining Torque code.
- VelocityLayout is now the proposed default layout. VelocityECSLayout might go away post-2.3. See Moving to VelocityOnlyLayout to see what changes need to be made to your application(s).
- TurbineException, TurbineRuntimeException, and TurbineError all extend the corresponding "Nestable" exception type from commons-lang.
- VelocityHtmlMail can now be used in a scheduled job. It has a new constructor accepting a velocity context object.
- Intake changes:
  - Backported changes from Fulcrum version
  - IntakeException is now thrown from intake methods instead of TurbineException and Exception.
  - Multiple XML definition files can be used.
  - Logging has been improved to give more information when an error occurs.
  - The DTD has been updated and fully documented!
  - Intake now uses commons-pool for pooling.
  - intake.dtd is now packaged in the turbine.jar file. If your intake.xml file validates against jakarta.apache.org/turbine/dtd/intake.dtd, then the DTD included in the jar file will be used instead of the online version.
  - The DTD resolved for intake will now look for intake.dtd on the class path when the DTD in the XMl file is http://jakarta.apache.org/turbine/dtd/intake_2_2_1.dtd. The application functions in the same way. This was done to allow XML editors to use the correct version of the DTD.
  - The field object has two new methods to help in creating the HTML input tags for the field. They are getDisplaySize() and getMaxSize(). The display size is set in the xml definition. The max size is pulled from the maxLength rule (if defined).
  - The setDefaultValue() method on the Field object is now public. This will allow you to assign a value to a field for display on a form that does come from a mapped object. Before this change, your only option was to defined the default value in intake.xml.
- All deprecated calls to the old org.apache.turbine.util.Log have been replaced with calls to org.apache.commons.logging.Log.
- A new SessionService has been added. This will allow access to all sessions in the current context if you use Servlet API 2.3 or better.
- The non-secure web server for handling xml-rpc requests will now use the services.XmlRpcService.address setting for the address on which to listen for requests. If the setting is not found in TR.props, it will use the default of 0.0.0.0. This address will cause the server to listen on all addresses of a multi-homed machine.
- Nearly all of the methods of o.a.t.util.StringUtils has been deprecated. You should change your application code to use StringUtils from commons-lang.
- All classed in the org.apache.turbine.util.mail package have been deprecated. You should change your application code to use commons-mail instead.
- Turbine now uses commons-fileupload. The org.apache.turbine.util.upload package has been deprecated.
- The Pull Service got a new scope: authorized tools. These are like Session Tools but only available after the user logged in.
- The Pull Service got a new type of tools: RunDataApplicationTools. These tools get the current RunData object passed at every refresh(). This type obviously makes sense only for non-request scope tools.
- Some services got static facade classes: FactoryService, JspService, RunDataService, SchedulerService.
- Turbine can use the ConfigurationFactory from commons-configuration to load all kinds of configuration types like XML, JNDI or (still) plain properties files.
- A completely new URI handling scheme was added and is now the proposed default method to handle URI representations in Turbine. The older URI handling classes like ContentURI and DynamicURI will go after the 2.3 release.
- A new Security Service is available: TorqueSecurityService. It has the same functionality as the DBSecurityService but allows the usage of arbitrary Torque generated peer classes and objects as security objects.
- The security object get methods from Security Service have been deprecated and replaced by methods which are able to reference Objects by Name and by Primary Key.
- The TurbineDB Service has been deprecated. Use Torque and the Component Service to start Torque.
- It is possible to debug pressure on the PoolService by setting services.PoolService.pool.debug to true in the TurbineResources.properties.
- Turbine now has some integration for Avalon Components. It can start Avalon based components with the new AvalonComponentService.
- Added a new TurbineMacros file to the turbine jar, which contains some helper macros for Velocity Templates. Currently there are only some macros to be used with VelocityOnlyLayout to render the page attributes like in VelocityECSLayout based pages.
- The ComponentService (using the stratum lifecycle interfaces) is deprecated. It will be removed after the 2.3 release as the stratum package is unmaintained. We use the new AvalonComponentService to initialize Torque.
- ActionEvent and VelocityActionEvent can "ignore" eventSubmit_<xxx> events if they contain an empty or a zero value. This behaviour is controlled by the "action.eventsubmit.needsvalue" property that defaults to "off", which means no change from the pre-2.3 behaviour. The new behaviour is useful if you have multiple event fields in a form and only one should be selected (e.g. by a client side java script application).
- VelocityService now uses the EventCartridge Code to catch and log invocation errors from templates. This is very useful when debugging pull tools, because you get the actual exception in the log and not only the velocity internal stack trace. You can switch this behaviour off by setting "services.VelocityService.catch.errors" to off or false.
- Intake can now assign "empty" values to fields which are not returned or left out by the browser. This is useful if you want your string fields not to map to null if the user does not enter anything.

### Fixed bugs

- TTWS25: Removed deprecated call to TurbineDB
- TRQD10: Extending Turbine User How-to for T2.2
- TTWS20: Intake can not set mapped attributes to null.
- Changed made to scheduled jobs are now recognized by the scheduler service. Before, it would only recognize changes to the next run time.
- Fixed null pointer exception during initialization of IntakeTool when there are no groups defined in intake.xml
- TTWS41: PrimaryKey not set on TurbineUser after insert.
- Cookies now work properly. A NullPointerException was being thrown during the call to data.getCookies() if no cookies were present. Also, the path for cookies was being set incorrectly. Both of these issues have been fixed.
- The pull service now really refreshes non-request tool every time a tool is requested.

## Turbine 2.2 (= 2.2-rc2)

Changes between Turbine 2.2-rc1 and 2.2.

### Other changes

- TTWS1: TemplatePageAttributes enhancements
- TTWS5: Reference support for DynamicURI
- TTWS13: IntakeTool.getGroups() should be public

## Turbine 2.2-rc1

Changes between Turbine 2.2-b2 and 2.2-rc1.

### Other changes

- Enhancements to support Apache XML-RPC versions 1.2 alpha 1 and 2.

### Fixed bugs

- TRQD2: Update to intake-howto to mention remove()

## Turbine 2.2-b2

Changes between Turbine 2.2-b1 and 2.2-b2.

The coupled version of Torque has been removed from Turbine 2.2!
Get a full list of changes at the Torque-site.

### Changes that could break older environments

- the coupled version of torque has been removed.

### Other changes

- Maven is used as build system for Turbine 2.2
- removed antiquated redirect logic.
- You can use log4j properties directly.
- The configuration package has been moved from stratum to commons
- BaseValueParser.setProperty() changed from private to protected

### Fixed bugs

- Fixed IllegalStateException when removing an attribute from an invalid session (patch by David Vandegrift - dvandegrift@bluearc.com)
- Fixed NumberFormatException in UUIdGenerator.

## Turbine 2.2b1

Changes between Turbine 2.1 and 2.2b1.

Torque and Fulcrum (the service framework) have been decoupled in preparation for Turbine 3.0. The decoupled versions can be used with Turbine 2.2. We strongly recommend to use the decoupled versions (some of the 'old' services must be used, because they are used internally by Turbine)

If you wrote your own services you should also change them to be Fulcrum services to make them work with Turbine 3.x

### Changes that could break older environments

- The Service interface was extended to allow integration of Service implementations:
  Service.getName()
  since most Service implementations extend BaseService (which implements a public getName method), this should not be an issue.

### Other changes

- ECS, Freemarker and Webmacro services/modules are marked deprecated. You should use Velocity instead.
- Castor service is marked as deprecated. You should use om/peer classes instead!
- The XSLT Service is updated to use Xalan 2.0
- Improved datatype mappings for mysql, oracle, postgresql, sapdb
- adding support for DB2 on AS400 (patch by Sweaver@rippe.com).
- adding support for secure connections in the xmlrpc service.
- Added a configuration parameter to torque, addTimeStamp, that allows the user to generate files without a timestamp. Default is true, timestamps will be generated.
- Criteria.Criterion implements Serializable
- DB implements Serializable
- torque: id-methods sequence and autoincrement are deprecated. You should use native. torque uses the method provided by your database
- added static strings for ISNULL and ISNOTNULL to Criteria.
- added getDateString() method to format date fields to DB.
- added VelocityDirectLayout/Screen to make it possible to embed servlet/JSP outputs into a Velocity template used within Turbine. (patch by raphael.luta@networks.groupvu.com)
- added an easy to use localization pull tool.
- Javadocs improvements.
- Documentation improvements.

### Fixed bugs

- fixed error in Mssql unique.vm template (removed a blank line)
- [2301] Embedding message parts in HtmlEmail throws NullPointerException.
- bugfix for BigDecimal attributes with default value
- fixed handling of sequences for db2, oracle, postgresql, sapdb
- fixed syntax for create index (postgresql)
- fixed problem for postgres with blob style column in TurbineUser table. (patch by Jerome Veryleyen)
- BaseUnicastRemoteService.java: Corrected method name (setName -> getName).
- fixed Roleset.add(RoleSet) (patch by lujin@yahoo.com)
- fixed database - defaultIdMethod (torque)
- fixed date formating problem with Oracle.
- fixed problem when ignoreCase was used with ISNULL or ISNOTNULL.
- fixed Option object initialisation in SelectorBox (patch by Kurt Grafius kurtg@jvoom.com)