joerg 2003/10/16 14:44:11
Modified: site/2.1/installing updating.html Log: additional comments added (reported by Lars Huttar) Revision Changes Path 1.10 +130 -81 cocoon-site/site/2.1/installing/updating.html Index: updating.html =================================================================== RCS file: /home/cvs/cocoon-site/site/2.1/installing/updating.html,v retrieving revision 1.9 retrieving revision 1.10 diff -u -r1.9 -r1.10 --- updating.html 12 Oct 2003 17:46:36 -0000 1.9 +++ updating.html 16 Oct 2003 21:44:11 -0000 1.10 @@ -216,13 +216,24 @@ <a href="#Pipelines+configuration+in+the+sitemap">Pipelines configuration in the sitemap</a> </li> <li> -<a href="#Individual+configuration+of+pipelines">Individual configuration of pipelines</a> +<a href="#FOP+Serializer">FOP Serializer</a> </li> <li> -<a href="#FOP+Serializer">FOP Serializer</a> +<a href="#Sitemap+components">Sitemap components</a> +</li> +<li> +<a href="#Error+handling">Error handling</a> +</li> +</ul> </li> <li> <a href="#Namespace+changes">Namespace changes</a> +<ul class="minitoc"> +<li> +<a href="#Request+Generator">Request Generator</a> +</li> +<li> +<a href="#I18nTransformer">I18nTransformer</a> </li> </ul> </li> @@ -273,47 +284,49 @@ </ul> </li> </ul> - - + <a name="N1001B"></a><a name="Updating+Cocoon"></a> <h3>Updating Cocoon</h3> <div style="margin-left: 0 ; border: 2px"> -<p>Please take your time to read this document completely before trying to upgrade from - a Cocoon 2.0.x installation to 2.1 (or above).</p> <p> - This is a brief discussion of the changes between the latest official release 2.1.2 - and the current development version of Apache Cocoon. - You only need this information if you are updating an existing Cocoon installation, or - if you want to know what is going on in the development of Cocoon. - </p> + Please take your time to read this document completely before trying to upgrade from + a Cocoon 2.0.x installation to 2.1 (or above). You can also read it if you want to + know what was going on in the development of Cocoon. + </p> <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. + improvements it has not been possible to be compatible in every little detail. If you follow the instructions of document closely, however, you should be able to quickly upgrade your Cocoon 2.0.x installation. - </p> + </p> <p> - The Cocoon team has developed many Avalon components that are not specific to Cocoon - and therefore have been donated to the Avalon Excalibur project and moved out - of Cocoon. This has led to some configuration changes which are also described - in this document. - </p> + The Cocoon team has developed many Avalon components that are not specific to Cocoon + and therefore have been donated to the Avalon Excalibur project and moved out + of Cocoon. This has led to some configuration changes which are also described + in this document. + </p> </div> -<a name="N1002D"></a><a name="Sitemap"></a> +<a name="N1002A"></a><a name="Sitemap"></a> <h3>Sitemap</h3> <div style="margin-left: 0 ; border: 2px"> -<p>There are some changes in the sitemap and in the configuration of some components in - the sitemap.</p> -<a name="N10035"></a><a name="Pipelines+configuration+in+the+sitemap"></a> +<div class="frame note"> +<div class="label">Note</div> +<div class="content">There are some changes in the sitemap and in the configuration of some + components in the sitemap. In general we recommend you to start with a new + sitemap from 2.1 and to adapt it to your needs. But for manual migration we + will list as many changes as possible.</div> +</div> +<a name="N10032"></a><a name="Pipelines+configuration+in+the+sitemap"></a> <h4>Pipelines configuration in the sitemap</h4> <div style="margin-left: 0 ; border: 2px"> <p> The configuration of the pipelines has moved from cocoon.xconf to the sitemap. - To update your installation, you have to remove the "event-pipeline" and "stream-pipeline" section - from your cocoon.xconf and add the <span class="codefrag">map:pipes</span> section to the <span class="codefrag">map:components</span> section + To update your installation, you have to remove the "event-pipeline" and "stream-pipeline" + section from your cocoon.xconf (see also the cocoon.xconf section) and add the + <span class="codefrag">map:pipes</span> section to the <span class="codefrag">map:components</span> section of your sitemap. You can find the pipelines components definition in the sample main sitemap of Cocoon. Here is an example: </p> @@ -347,76 +360,113 @@ </map:pipelines> </map:sitemap> </pre> -<p>This is similar to choosing the type of a generator or any other sitemap - component. If the type attribute is omitted, the default configuration from the <span class="codefrag">map:components</span> - section is used. +<p>This is similar to choosing the type of a generator or any other sitemap component. + If the type attribute is omitted, the default configuration from the + <span class="codefrag">map:components</span> section is used. </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> -<p>So it's not that bad, despite incompatible changes in the Cocoon code there is - little to do to update your Cocoon installation.</p> </div> -<a name="N10069"></a><a name="Individual+configuration+of+pipelines"></a> -<h4>Individual configuration of pipelines</h4> -<div style="margin-left: 0 ; border: 2px"> -<p>The sitemap now provides individual configuration of <span class="codefrag">map:pipeline</span> sections. - You can now define one pipeline using caching, another one not using - caching at all and a third one using a different caching implementation, for example. - </p> -</div> -<a name="N10075"></a><a name="FOP+Serializer"></a> +<a name="N1005A"></a><a name="FOP+Serializer"></a> <h4>FOP Serializer</h4> <div style="margin-left: 0 ; border: 2px"> -<p>Relative paths in FOP serializer's <user-config> are now resolved relatively - to the directory that contains the sitemap.</p> +<p>Relative paths in FOP serializer's <span class="codefrag"><user-config></span> are now resolved + relatively to the directory that contains the sitemap.</p> <p>All Cocoon URIs are supported too.</p> </div> -<a name="N10081"></a><a name="Namespace+changes"></a> -<h4>Namespace changes</h4> +<a name="N10069"></a><a name="Sitemap+components"></a> +<h4>Sitemap components</h4> +<div style="margin-left: 0 ; border: 2px"> +<p>Some of the sitemap components have been removed from Cocoon sources, others were renamed. + If you have the old declaration in your sitemap, you will get + <span class="codefrag">ClassNotFoundException</span>s. Trial and error will probably be the fastest way for + removing them and getting a clean and working sitemap. Hopefully you are not using one of the + removed components. The following components are known to be removed or renamed:</p> +<ul> + +<li> + +<span class="codefrag">o.a.c.XTTransformer</span> - use the TraxTransformer instead. + </li> + +<li> + +<span class="codefrag">o.a.c.webapps.authentication.selection.MediaSelector</span> - the full qualified class + name has changed to <span class="codefrag">o.a.c.webapps.session.selection.MediaSelector</span>. + </li> + +</ul> +</div> +<a name="N10087"></a><a name="Error+handling"></a> +<h4>Error handling</h4> +<div style="margin-left: 0 ; border: 2px"> +<p>The <span class="codefrag">map:handle-errors</span> section must now be a complete pipeline. This means the + old form</p> +<pre class="code"> + <map:handle-errors> + <map:transform src="stylesheets/system/error2html.xsl"/> + <map:serialize status-code="404"/> + </map:handle-errors> + </pre> +<p>is no longer valid, because the generator is missing. Therefore you can now describe + explicitely the error handling. The replacement of the above looks like the following:</p> +<pre class="code"> + <map:handle-errors> + <map:generate type="notifying"/> + <map:transform src="stylesheets/system/error2html.xsl"/> + <map:serialize status-code="404"/> + </map:handle-errors> + </pre> +<p>For a more detailed example have a look into the default sitemap delivered with Cocoon + sources or read the + <a href="../userdocs/concepts/errorhandling.html">documentation on error handling</a>. + </p> +</div> +</div> + +<a name="N100A8"></a><a name="Namespace+changes"></a> +<h3>Namespace changes</h3> <div style="margin-left: 0 ; border: 2px"> <p> - In order to have consistent namespaces, some transformers - and generators (listed below) use new namespaces. If you use any of these components, you will - need to use the new namespaces. + In order to have consistent namespaces, some transformers and generators + (listed below) use new namespaces. If you use any of these components, you + will need to use the new namespaces. </p> -<a name="N10089"></a><a name="Request+Generator"></a> -<h5>Request Generator</h5> +<a name="N100B0"></a><a name="Request+Generator"></a> +<h4>Request Generator</h4> <div style="margin-left: 0 ; border: 2px"> -<p>RequestGenerator changed its namespace from http://xml.apache.org/cocoon/requestgenerator/2.0 to - http://apache.org/cocoon/request/2.0. +<p>RequestGenerator changed its namespace from + <span class="codefrag">http://xml.apache.org/cocoon/requestgenerator/2.0</span> to + <span class="codefrag">http://apache.org/cocoon/request/2.0</span>. </p> </div> -<a name="N10092"></a><a name="I18nTransformer"></a> -<h5>I18nTransformer</h5> +<a name="N100BF"></a><a name="I18nTransformer"></a> +<h4>I18nTransformer</h4> <div style="margin-left: 0 ; border: 2px"> -<p>The I18nTransformer changed its namespace from - http://apache.org/cocoon/i18n/2.0 to http://apache.org/cocoon/i18n/2.1</p> -</div> +<p>The I18nTransformer supports both + <span class="codefrag">http://apache.org/cocoon/i18n/2.0</span> and + <span class="codefrag">http://apache.org/cocoon/i18n/2.1</span> namespace.</p> </div> </div> -<a name="N1009D"></a><a name="Changes+in+logging+interfaces+require+recompilation"></a> +<a name="N100CF"></a><a name="Changes+in+logging+interfaces+require+recompilation"></a> <h3>Changes in logging interfaces require recompilation</h3> <div style="margin-left: 0 ; border: 2px"> <p> Due to some interface changes in the Cocoon logging components, custom java - components (generators,transformers or actions for example) compiled for Cocoon 2.0.x will not run - under Cocoon 2.1 unless recompiled.</p> + components (generators, transformers or actions for example) compiled for Cocoon + 2.0.x will not run under Cocoon 2.1 unless recompiled.</p> <p>It's also advisable to change your implementations from using <em>Loggable</em> to <em>LogEnabled</em> when it comes to logging in your components. </p> </div> -<a name="N100AF"></a><a name="Components"></a> +<a name="N100E1"></a><a name="Components"></a> <h3>Components</h3> <div style="margin-left: 0 ; border: 2px"> <p> The Cocoon architecture has changed significantly. However, great care has been taken to preserve backwards compatibility. - This effort has been successful except for - one change which shouldn't affect anybody (see below). </p> -<a name="N100B7"></a><a name="Cocoon+Configuration+%28cocoon.xconf%29"></a> +<a name="N100E9"></a><a name="Cocoon+Configuration+%28cocoon.xconf%29"></a> <h4>Cocoon Configuration (cocoon.xconf)</h4> <div style="margin-left: 0 ; border: 2px"> <p>In order to reflect the new version, the version information in the <em>cocoon.xconf</em> @@ -424,21 +474,21 @@ </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> </div> -<a name="N100CF"></a><a name="Source+Resolver"></a> +<a name="N1010A"></a><a name="Source+Resolver"></a> <h4>Source Resolver</h4> <div style="margin-left: 0 ; border: 2px"> <p>The SourceResolver is now an Avalon component which can be accessed using <em>cocoon.manager.lookup(SourceResolver.ROLE).</em>. The package name of the component is <em>org.apache.excalibur.source</em>.</p> </div> -<a name="N100DE"></a><a name="XSLT+Processor"></a> +<a name="N10119"></a><a name="XSLT+Processor"></a> <h4>XSLT Processor</h4> <div style="margin-left: 0 ; border: 2px"> -<p> - There are some issues related to JDK 1.4 - </p> -<a name="N100E8"></a><a name="XML%2FXSLT+with+JDK+1.4"></a> +<p>There are some issues related to JDK 1.4.</p> +<a name="N10121"></a><a name="XML%2FXSLT+with+JDK+1.4"></a> <h5>XML/XSLT with JDK 1.4</h5> <div style="margin-left: 0 ; border: 2px"> <p>Another serious issue is the presence of the Xalan and Xerces @@ -455,7 +505,7 @@ </p> </div> </div> -<a name="N100FD"></a><a name="XML+Parser"></a> +<a name="N10136"></a><a name="XML+Parser"></a> <h4>XML Parser</h4> <div style="margin-left: 0 ; border: 2px"> <p>The XML parser component has been moved to Excalibur. @@ -467,7 +517,7 @@ <em>org.apache.excalibur.xml.sax.SAXParser.ROLE</em> instead. </p> </div> -<a name="N10115"></a><a name="XML+Entity+Resolver"></a> +<a name="N1014E"></a><a name="XML+Entity+Resolver"></a> <h4>XML Entity Resolver</h4> <div style="margin-left: 0 ; border: 2px"> <p>Similarly, the XML entity resolver component has been moved to Excalibur. @@ -482,7 +532,7 @@ WEB-INF/ directory. </p> </div> -<a name="N10130"></a><a name="Caching"></a> +<a name="N10169"></a><a name="Caching"></a> <h4>Caching</h4> <div style="margin-left: 0 ; border: 2px"> <p>Although the basic caching mechanism is still the same (each sitemap component @@ -500,7 +550,7 @@ same time, making your component runable in old and new Cocoon installations at the same time.</p> </div> -<a name="N10148"></a><a name="Stores"></a> +<a name="N10181"></a><a name="Stores"></a> <h4>Stores</h4> <div style="margin-left: 0 ; border: 2px"> <p>The Store and StoreJanitor components and implementations have been moved to @@ -519,7 +569,7 @@ <em>PERSISTENT_STORE</em> and <em>TRANSIENT_STORE</em>. The hold() method has been removed from the Store interface.</p> </div> -<a name="N1017E"></a><a name="SAXConnectors%2C+Stream+and+Event+Pipeline"></a> +<a name="N101B7"></a><a name="SAXConnectors%2C+Stream+and+Event+Pipeline"></a> <h4>SAXConnectors, Stream and Event Pipeline</h4> <div style="margin-left: 0 ; border: 2px"> <p>This is the only real incompatible change (But don't panic, this will @@ -535,16 +585,15 @@ The <em>SAXConnectors</em>, which were rarely used, have been removed to avoid overcomponentization.</p> </div> -<a name="N10199"></a><a name="File+Upload"></a> +<a name="N101D2"></a><a name="File+Upload"></a> <h4>File Upload</h4> <div style="margin-left: 0 ; border: 2px"> <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> + <em>Part.getUploadName()</em>. + </p> </div> -<a name="N101AE"></a><a name="RequestLifeCycleComponent"></a> +<a name="N101E7"></a><a name="RequestLifeCycleComponent"></a> <h4>RequestLifeCycleComponent</h4> <div style="margin-left: 0 ; border: 2px"> <p>If you are using the marker interface <em>RequestLifeCycleComponent</em> for your @@ -556,13 +605,13 @@ </div> </div> -<a name="N101CA"></a><a name="Components+from+the+scratchpad"></a> +<a name="N10203"></a><a name="Components+from+the+scratchpad"></a> <h3>Components from the scratchpad</h3> <div style="margin-left: 0 ; border: 2px"> <p>Cocoon 2.0.x had some components in the scratchpad area that have now moved into the main trunk as blocks. With this move some things have changed. </p> -<a name="N101D2"></a><a name="Session%2C+Authentication+and+Portal"></a> +<a name="N1020B"></a><a name="Session%2C+Authentication+and+Portal"></a> <h4>Session, Authentication and Portal</h4> <div style="margin-left: 0 ; border: 2px"> <p>The session framework (sunShine), the authentication framework (sunRise)