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)
