apache > cocoon
 
 

Updating Cocoon

THIS DOCUMENT REQUIRES AN UPDATE!
2005/10/14

The following items/topics are missing:

Updating To Cocoon 2.2.x

Please take your time to read this document completely before trying to upgrade from a Cocoon 2.1.x installation to 2.2 (or above). You can also read it if you want to know what was going on in the development of Cocoon. If you want to upgrade from an 2.0.x installation, please read Updating to Cocoon 2.1.5 document first.

Note
THIS DOCUMENTATION IS ALPHA AS WELL AS THE CURRENT DEVELOPMENT FOR 2.2, so treat this information with great care. It might be that we have not added everything and (more important) it might be that we will revert some of the changes detailed here.

The Cocoon team took great care in making this new version as compatible as possible. However, in order to achieve even more flexibility, usability and performance, the internal architecure of Cocoon has been improved. Due to these improvements it has not been possible to be compatible in each and every little detail. However, if you follow the instructions of this document closely, you should be able to quickly upgrade your Cocoon 2.1.x installation.

In general, it is a good idea to avoid any calls to private or deprecated API. If you are calling deprecated API, look up for an alternative. In most cases this is documented in the javadoc of the deprecated class. If not, or if you are calling private API, please ask on the mailing lists for the "right way".

Updating Your Application

Currently, updating your application from an older version to the latest version of Cocoon has to be done manually (but we are working on a better solution!).

We suggest that you start from a clean Cocoon 2.2.x installation and incorporate your changes into the cocoon.xconf, the sitemap etc. In most cases this is much easier than starting with your old application's files and adapting them to Cocoon 2.2.x.

Sitemap Changes

Mime-Types and Readers

The way, a reader sets the mime-type has changed. Now the following algorithm is used:

  1. If the reader instance has a mime-type definition, it is used.
  2. If the used reader has a mime-type definition, it is used.
  3. If both are not set, the reader itself has to provide the mime-type.

You can find further information in bug entry 10277.

Recompilation

As detailed below some deprecated classes and methods have been removed, therefore the easiest way to detect if you are affected is to recompile your code. If during compilation an error occurs have a look in the sections below on what to change.

Internal Processing

The internal processing of Cocoon has been improved, therefore some deprecated methods have been removed to clean up the code.

Environment Interface

The deprecated getOutputStream method of the Environment interface has been removed. Use the getOutputStream(int) method instead.

In addition some methods of the Environment interface have been changed, removed and added. The environment is now free from any dependencies to the Cocoon core and it is easier to create own environments.

Cocoon Source Resolver Interface

The deprecated resolve method of the org.apache.cocoon.environment.SourceResolver interface has been removed. Use the resolveURI and the release method instead.

In addition the following interfaces and implementations have been removed in favour of their new versions:

  • org.apache.cocoon.environment.Source : Use the org.apache.excalibur.source.Source interface instead.
  • org.apache.cocoon.environment.ModifiableSource - Excalibur SourceResolver
  • org.apache.cocoon.environment.URLFactorySourceResolver - Not needed anymore
  • org.apache.cocoon.environment.WriteableSource - Excalibur SourceResolver
  • org.apache.cocoon.components.source.AbstractSAXSource - Not needed anymore>
  • org.apache.cocoon.components.source.AbstractStreamSource - Not needed anymore
  • org.apache.cocoon.components.source.AbstractStreamWriteableSource - Not needed anymore
  • org.apache.cocoon.components.source.CocoonSourceFactory - Not needed anymore
  • org.apache.cocoon.components.source.DelayedRefreshSourceWrapper - org.apache.cocoon.components.source.impl.DelayedRefreshSourceWrapper
  • org.apache.cocoon.components.source.FileSource - Excalibur SourceResolver
  • org.apache.cocoon.components.source.FileSourceFactory - Not needed anymore
  • org.apache.cocoon.components.source.ModifiableTraversableSource - Excalibur SourceResolver
  • org.apache.cocoon.components.source.SitemapSource - org.apache.cocoon.components.source.impl.SitemapSource
  • org.apache.cocoon.components.source.SourceFactory - org.apache.cocoon.components.source.impl.SitemapSourceFactory
  • org.apache.cocoon.components.source.SourceHandler - Not needed anymore
  • org.apache.cocoon.components.source.SourceHandlerImpl - Not needed anymore
  • org.apache.cocoon.components.source.TraversableSource - Excalibur SourceResolver
  • org.apache.cocoon.components.source.URLSource - Excalibur SourceResolver
  • org.apache.cocoon.components.source.impl.AvalonToCocoonSource - Not needed anymore
  • org.apache.cocoon.components.source.impl.AvalonToCocoonSourceInvocationHandler - Not needed anymore
  • org.apache.cocoon.components.source.impl.CocoonToAvalonSource - Not needed anymore
  • org.apache.cocoon.components.source.impl.SourceFactoryWrapper - Not needed anymore
  • org.apache.cocoon.components.source.impl.URLFactoryWrapper - Not needed anymore
  • org.apache.cocoon.components.url.ContextURLFactory - org.apache.cocoon.components.source.impl.ContextSourceFactory
  • org.apache.cocoon.components.url.ResourceURLFactory - Excalibur SourceResolver
  • org.apache.cocoon.components.url.URLFactory - Not needed anymore
  • org.apache.cocoon.components.url.URLFactoryImpl - Not needed anymore
  • org.apache.cocoon.xml.XMLizable - Excalibur SourceResolver

XML Parsing

  • org.apache.cocoon.components.parser.JaxpParser - Excalibur XMLUtils
  • org.apache.cocoon.components.parser.Parser - Excalibur XMLUtils
  • org.apache.cocoon.components.parser.PooledJaxpParser - Excalibur XMLUtils
  • org.apache.cocoon.components.parser.XercesParser - Excalibur XMLUtils

XML Entity Resolver

  • org.apache.cocoon.components.resolver.Resolver - Excalibur XMLUtils
  • org.apache.cocoon.components.resolver.ResolverImpl - Excalibur XMLUtils

Stores

  • org.apache.cocoon.components.store.FilesystemStore - Excalibur Store
  • org.apache.cocoon.components.store.JispFilesystemStore - Excalibur Store
  • org.apache.cocoon.components.store.JispStringKey - Excalibur Store
  • org.apache.cocoon.components.store.MemoryStore - Excalibur Store
  • org.apache.cocoon.components.store.MRUMemoryStore - Excalibur Store
  • org.apache.cocoon.components.store.Store - Excalibur Store
  • org.apache.cocoon.components.store.StoreJanitor - Excalibur Store
  • org.apache.cocoon.components.store.StoreJanitorImpl - Excalibur Store
  • org.apache.cocoon.components.store.impl.DefaultPersistentStore - JCS Store

XSLT Processor

  • org.apache.cocoon.components.xslt.XSLTProcessor - Excalibur XMLUtils
  • org.apache.cocoon.components.xslt.XSLTProcessorImpl - Excalibur XMLUtils

Sitemap Components

  • org.apache.cocoon.components.treeprocessor.MapStackResolver - org.apache.cocoon.components.treeprocessor.variables.VariableResolverFactory
  • org.apache.cocoon.matching.RegexpTargetHostMatcher - org.apache.cocoon.matching.RegexpHostMatcher
  • org.apache.cocoon.matching.RequestParamMatcher - org.apache.cocoon.matching.RequestParameterMatcher
  • org.apache.cocoon.matching.WildcardParameterValueMatcher - org.apache.cocoon.matching.WildcardRequestParameterMatcher
  • org.apache.cocoon.matching.helpers.WildcardURIMatcher - org.apache.cocoon.matching.helpers.WildcardHelper
  • org.apache.cocoon.selection.RequestSelector - org.apache.cocoon.selection.RequestParameterSelector
  • org.apache.cocoon.selection.SessionStateSelector - org.apache.cocoon.selection.SessionAttributeSelector
  • org.apache.cocoon.sitemap.SitemapRedirector - Removed
  • org.apache.cocoon.sitemap.XSLTFactoryLoader - Removed
  • org.apache.cocoon.transformation.CachingCIncludeTransformer - org.apache.cocoon.transformation.CIncludeTransformer
  • org.apache.cocoon.transformation.helpers.MirrorRecorder - Different alternatives, e.g. ParamSaxBuffer

Request Lifecycle Components

The deprecated class org.apache.cocoon.components.RequestLifecycleComponent and the deprecated class org.apache.cocoon.components.GlobalRequestLifecycleComponent have been removed. Use the org.apache.cocoon.components.persistence.RequestDataStore component instead.

Caching

Although the basic caching mechanism is still the same (each sitemap component in the pipeline is queried), the interfaces for a component have been improved as well.

The following deprecated interfaces and classes have been removed from the org.apache.cocoon.caching package:

  • Cacheable : Use the CacheableProcessingComponent interface that is very similar.
  • CacheValidity : Is replaced by SourceValidity.
  • AggregatedCacheValidity - Excalibur SourceResolver
  • CompositeCacheValidity - Excalibur SourceResolver
  • DeltaTimeCacheValidity - Excalibur SourceResolver
  • IncludeCacheValidity - Excalibur SourceResolver
  • NOPCacheValidity - Excalibur SourceResolver
  • ParametersCacheValidity - Excalibur SourceResolver
  • TimeStampCacheValidity - Excalibur SourceResolver
  • CacheValidityToSourceValidity
  • SourceCacheValidity
  • CachedEventObject : Is replaced by CachedResponse.
  • CachedStreamObject : Is replaced by CachedResponse.

Some other interfaces and implementations, like the validity of the cached information have moved to the source packacke in Avalon Excalibur.

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).