| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd"> |
| |
| <document> |
| <header> |
| <title>Updating Cocoon</title> |
| <authors> |
| <person name="Carsten Ziegeler" email="cziegeler@apache.org"/> |
| <person name="Jörg Heinicke" email="joerg@apache.org"/> |
| <person name="Bertrand Delacrétaz" email="bdelacretaz@apache.org"/> |
| </authors> |
| </header> |
| |
| <body> |
| <s1 title="Updating Cocoon"> |
| <p> |
| 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 the instructions |
| <link href="../installing/updating.html">here</link>, first. |
| </p> |
| <note>THIS DOCUMENTATION IS ALPHA AS WELL AS THE CURRENT DEVELOPMENT FOR 2.2, |
| so use this information with great care. It might be that we don't have added |
| everything and (more important) it might be that we revert some changes |
| detailed here.</note> |
| <p> |
| 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 every little detail. |
| If you follow the instructions of this document closely, however, |
| you should be able to quickly upgrade your Cocoon 2.1.x installation. |
| </p> |
| </s1> |
| <s1 title="Updating Your Application"> |
| <p>Currently, updating your application from an older version to the latest |
| version of Cocoon has do be done manually (but we are working on a better |
| solution!).</p> |
| <p>We suggest you, that you start from a clean Cocoon installation and |
| incorporate your changes into the cocoon.xconf, the sitemap etc. This |
| is in most cases much easier that starting with your old application |
| and adapting it for Cocoon 2.2.x.</p> |
| </s1> |
| <s1 title="Sitemap Changes"> |
| <s2 title="Mime-Types and Readers"> |
| <p>The way, a reader sets the mime-type has changed. Now the following algorithm is used:</p> |
| <ol> |
| <li>If the reader instance has a mime-type definition, it is used.</li> |
| <li>If the used reader has a mime-type definition, it is used.</li> |
| <li>If both are not set, the reader itself has to provide the mime-type.</li> |
| </ol> |
| <p>You can find further information in <link href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=10277">bug entry 10277</link>.</p> |
| </s2> |
| </s1> |
| <s1 title="Recompilation"> |
| <p> |
| 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. |
| </p> |
| </s1> |
| <s1 title="Internal Processing"> |
| <p> |
| The internal processing of Cocoon has been improved, therefore some |
| deprecated methods have been removed to clean up the code. |
| </p> |
| <s2 title="Environment Interface"> |
| <p>The deprecated <em>getOutputStream</em> method of the <em>Environment</em> |
| interface has been removed. Use the <em>getOutputStream(int)</em> method |
| instead.</p> |
| </s2> |
| <s2 title="Cocoon Source Resolver Interface"> |
| <p>The deprecated <em>resolve</em> method of the |
| <em>org.apache.cocoon.environment.SourceResolver</em> |
| interface has been removed. Use the <em>resolveURI</em> and |
| the <em>release</em> method instead.</p> |
| <p>In addition the following interfaces and implementations have been |
| removed in favour of their new versions:</p> |
| <ul> |
| <li><em>org.apache.cocoon.environment.Source</em> : Use the |
| <em>org.apache.excalibur.source.Source</em> interface instead.</li> |
| <li><em>org.apache.cocoon.environment.ModifiableSource</em> - Excalibur SourceResolver</li> |
| <li><em>org.apache.cocoon.environment.URLFactorySourceResolver</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.environment.WriteableSource</em> - Excalibur SourceResolver</li> |
| <li><em>org.apache.cocoon.components.source.AbstractSAXSource</em> - Not needed anymore></li> |
| <li><em>org.apache.cocoon.components.source.AbstractStreamSource</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.source.AbstractStreamWriteableSource</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.source.CocoonSourceFactory</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.source.DelayedRefreshSourceWrapper</em> - org.apache.cocoon.components.source.impl.DelayedRefreshSourceWrapper</li> |
| <li><em>org.apache.cocoon.components.source.FileSource</em> - Excalibur SourceResolver</li> |
| <li><em>org.apache.cocoon.components.source.FileSourceFactory</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.source.SitemapSource</em> - org.apache.cocoon.components.source.impl.SitemapSource</li> |
| <li><em>org.apache.cocoon.components.source.SourceFactory</em> - org.apache.cocoon.components.source.impl.SitemapSourceFactory</li> |
| <li><em>org.apache.cocoon.components.source.SourceHandler</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.source.SourceHandlerImpl</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.source.URLSource</em> - Excalibur SourceResolver</li> |
| <li><em>org.apache.cocoon.components.source.impl.AvalonToCocoonSource</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.source.impl.AvalonToCocoonSourceInvocationHandler</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.source.impl.CocoonToAvalonSource</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.source.impl.SourceFactoryWrapper</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.source.impl.URLFactoryWrapper</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.url.ContextURLFactory</em> - org.apache.cocoon.components.source.impl.ContextSourceFactory</li> |
| <li><em>org.apache.cocoon.components.url.ResourceURLFactory</em> - Excalibur SourceResolver</li> |
| <li><em>org.apache.cocoon.components.url.URLFactory</em> - Not needed anymore</li> |
| <li><em>org.apache.cocoon.components.url.URLFactoryImpl</em> - Not needed anymore</li> |
| </ul> |
| </s2> |
| <s2 title="XML Parsing"> |
| <ul> |
| <li><em>org.apache.cocoon.components.parser.JaxpParser</em> - Excalibur XMLUtils</li> |
| <li><em>org.apache.cocoon.components.parser.Parser</em> - Excalibur XMLUtils</li> |
| <li><em>org.apache.cocoon.components.parser.PooledJaxpParser</em> - Excalibur XMLUtils</li> |
| <li><em>org.apache.cocoon.components.parser.XercesParser</em> - Excalibur XMLUtils</li> |
| </ul> |
| </s2> |
| <s2 title="XML Entity Resolver"> |
| <ul> |
| <li><em>org.apache.cocoon.components.resolver.Resolver</em> - Excalibur XMLUtils</li> |
| <li><em>org.apache.cocoon.components.resolver.ResolverImpl</em> - Excalibur XMLUtils</li> |
| </ul> |
| </s2> |
| <s2 title="Stores"> |
| <ul> |
| <li><em>org.apache.cocoon.components.store.FilesystemStore</em> - Excalibur Store</li> |
| <li><em>org.apache.cocoon.components.store.JispFilesystemStore</em> - Excalibur Store</li> |
| <li><em>org.apache.cocoon.components.store.JispStringKey</em> - Excalibur Store</li> |
| <li><em>org.apache.cocoon.components.store.MemoryStore</em> - Excalibur Store</li> |
| <li><em>org.apache.cocoon.components.store.MRUMemoryStore</em> - Excalibur Store</li> |
| <li><em>org.apache.cocoon.components.store.Store</em> - Excalibur Store</li> |
| <li><em>org.apache.cocoon.components.store.StoreJanitor</em> - Excalibur Store</li> |
| <li><em>org.apache.cocoon.components.store.StoreJanitorImpl</em> - Excalibur Store</li> |
| </ul> |
| </s2> |
| <s2 title="XSLT Processor"> |
| <ul> |
| <li><em>org.apache.cocoon.components.xslt.XSLTProcessor</em> - Excalibur XMLUtils</li> |
| <li><em>org.apache.cocoon.components.xslt.XSLTProcessorImpl</em> - Excalibur XMLUtils</li> |
| </ul> |
| </s2> |
| <s2 title="Sitemap Components"> |
| <ul> |
| <li><em>org.apache.cocoon.matching.RegexpTargetHostMatcher</em> - org.apache.cocoon.matching.RegexpHostMatcher</li> |
| <li><em>org.apache.cocoon.matching.RequestParamMatcher</em> - org.apache.cocoon.matching.RequestParameterMatcher</li> |
| <li><em>org.apache.cocoon.matching.WildcardParameterValueMatcher</em> - org.apache.cocoon.matching.WildcardRequestParameterMatcher</li> |
| <li><em>org.apache.cocoon.matching.helpers.WildcardURIMatcher</em> - org.apache.cocoon.matching.helpers.WildcardHelper</li> |
| <li><em>org.apache.cocoon.selection.RequestSelector</em> - org.apache.cocoon.selection.RequestParameterSelector</li> |
| <li><em>org.apache.cocoon.selection.SessionStateSelector</em> - org.apache.cocoon.selection.SessionAttributeSelector</li> |
| <li><em>org.apache.cocoon.transformation.CachingCIncludeTransformer</em> - org.apache.cocoon.transformation.CIncludeTransformer</li> |
| </ul> |
| </s2> |
| </s1> |
| <s1 title="Caching"> |
| <p>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.</p> |
| <p>The following deprecated interfaces and classes have been removed from |
| the <em>org.apache.cocoon.caching</em> package:</p> |
| <ul> |
| <li><em>Cacheable</em> : Use the <em>CacheableProcessingComponent</em> interface that is very similar.</li> |
| <li><em>CacheValidity</em> : Is replaced by <em>SourceValidity</em>.</li> |
| <li><em>AggregatedCacheValidity</em></li> |
| <li><em>CompositeCacheValidity</em></li> |
| <li><em>DeltaTimeCacheValidity</em></li> |
| <li><em>IncludeCacheValidity</em></li> |
| <li><em>NOPCacheValidity</em></li> |
| <li><em>ParametersCacheValidity</em></li> |
| <li><em>TimeStampCacheValidity</em></li> |
| <li><em>CacheValidityToSourceValidity</em></li> |
| <li><em>SourceCacheValidity</em></li> |
| <li><em>CachedEventObject</em> : Is replaced by <em>CachedResponse</em>.</li> |
| <li><em>CachedStreamObject</em> : Is replaced by <em>CachedResponse</em>.</li> |
| </ul> |
| <p>Some other interfaces and implementations, like the validity of the cached |
| information have moved to the source packacke in Avalon Excalibur.</p> |
| </s1> |
| |
| <!-- |
| <s1 title="Components"> |
| <p> |
| The Cocoon architecture has changed significantly. However, great care has been |
| taken to preserve backwards compatibility. |
| </p> |
| <s2 title="Cocoon Configuration (cocoon.xconf)"> |
| <p>In order to reflect the new version, the version information in the <em>cocoon.xconf</em> |
| has changed from <em>2.0</em> to <em>2.1</em>. |
| </p> |
| <p>To update <em>cocoon.xconf</em>, we recommend that you start with the new cocoon.xconf from V2.1 and |
| incorporate your changes in it, instead of trying to migrate your old configuration file.</p> |
| <p>The SAXConnectors have been removed, so if you upgrade manually you have to remove |
| the <em>sax-connectors</em> configuration from <em>cocoon.xconf</em>.</p> |
| </s2> |
| <s2 title="XSLT Processor"> |
| <p>There are some issues related to JDK 1.4.</p> |
| <s3 title="XML/XSLT with JDK 1.4"> |
| <p>Another serious issue is the presence of the Xalan and Xerces |
| package in the JDK 1.4. For general information on this please read the |
| <link href="http://xml.apache.org/xalan-j/faq.html#jdk14">Xalan FAQ</link> and our own |
| <link href="http://wiki.cocoondev.org/Wiki.jsp?page=EndorsedLibsProblem">EndorsedLibsProblem</link> |
| wiki page. |
| </p> |
| <p> |
| Basically, you have to update your libraries in the endorsed dirs of the JDK |
| or the servlet containers with every new version of Xalan and Xerces delivered with Cocoon. |
| Strange errors can occur if you have different versions of these packages in the |
| classpath (independent of those in the JDK). |
| </p> |
| </s3> |
| </s2> |
| <s2 title="XML Parser"> |
| <p>The XML parser component has been moved to Excalibur. |
| In cocoon.xconf, the hint name has therefore changed from <em>parser</em> to |
| <em>xml-parser</em>. The configuration has not changed, so changing the hint |
| names is sufficent.</p> |
| <p>Java code should not use |
| <em>org.apache.cocoon.components.parser.Parser.ROLE</em> anymore; use |
| <em>org.apache.excalibur.xml.sax.SAXParser.ROLE</em> instead. |
| </p> |
| </s2> |
| <s2 title="XML Entity Resolver"> |
| <p>Similarly, the XML entity resolver component has been moved to Excalibur. |
| In cocoon.xconf the hint name has therefore changed from <em>resolver</em> to |
| <em>entity-resolver</em>. The configuration has not changed, so changing the hint |
| names is sufficent.</p> |
| <p>Java code should not use |
| <em>org.apache.cocoon.components.resolver.Resolver.ROLE</em> anymore; use |
| <em>org.apache.excalibur.xml.EntityResolver.ROLE</em> instead. |
| </p> |
| <p>The default entities (DTDs, entity sets, etc.) have moved to the |
| WEB-INF/ directory. |
| </p> |
| </s2> |
| <s2 title="Stores"> |
| <p>The Store and StoreJanitor components and implementations have been moved to |
| Avalon Excalibur.</p> |
| <p>To make upgrading easier, the class attributes of the store janitor |
| component have been removed in <em>cocoon.xconf</em> as the class names have changed. |
| The <em>cache-transient</em> and <em>cache-persistent</em> components do |
| not exist anymore, so any reference to them must be removed from cocoon.xconf. |
| Use the <em>persistent-store</em> and <em>transient-store</em> components instead. |
| </p> |
| <p>In general the package names changed from <em>org.apache.cocoon.components.store</em> |
| to <em>org.apache.excalibur.store</em> (and <em>org.apache.excalibur.store.impl</em>). So |
| if you have custom java code using these components, you have to change |
| your imports.</p> |
| <p>The roles <em>PERSISTENT_CACHE</em> and <em>TRANSIENT_CACHE</em> have been renamed to |
| <em>PERSISTENT_STORE</em> and <em>TRANSIENT_STORE</em>. The hold() method has been removed |
| from the Store interface.</p> |
| </s2> |
| <s2 title="SAXConnectors, Stream and Event Pipeline"> |
| <p>This is the only real incompatible change (But don't panic, this will |
| not affect you, or maybe just a little bit..). |
| </p> |
| <p> |
| The internal architecture of Cocoon |
| has changed: previously, the processing pipeline - consisting of |
| a generator, the transformers and a serializer - was represented by two components, |
| called <em>stream</em> and <em>event pipeline</em>.</p> |
| <p>For a simpler architecture, enhanced functionality and improved performance, |
| these components have been combined into one: the <em>processing pipeline</em>. |
| The <em>SAXConnectors</em>, which were rarely used, have been removed |
| to avoid overcomponentization.</p> |
| </s2> |
| <s2 title="File Upload"> |
| <p>The class name for file upload has changed from <em>org.apache.cocoon.components.request.multipart.FilePart</em> to |
| <em>org.apache.cocoon.servlet.multipart.Part</em>, and the <em>getFilePath()</em> has been renamed |
| <em>Part.getUploadName()</em>. |
| </p> |
| </s2> |
| <s2 title="RequestLifeCycleComponent"> |
| <p>If you are using the marker interface <em>RequestLifeCycleComponent</em> for your |
| own components, you have to make sure that your implementations still implement |
| the <em>Component</em> interface. The <em>RequestLifeCycleComponent</em> does no |
| longer extend the <em>Component</em> interface, so you have to declare it in your |
| own components together with <em>RequestLifeCycleComponent</em>. Otherwise you |
| will get a <em>ClassCastException</em> as soon as you access your component.</p> |
| </s2> |
| </s1> |
| --> |
| </body> |
| </document> |
