cziegeler 2003/10/19 23:48:25
Modified: src/documentation/xdocs/plan release.xml
Added: src/documentation/xdocs/plan updating.xml
Removed: src/blocks/jms/java/org/apache/cocoon/components/jms
JMSConnectionImpl.java JMSConnection.java
JMSEventListener.java JMSPublisherAction.java
src/blocks/jms/java/org/apache/cocoon/samples/jms
HTTPTrigger.java JMSTrigger.java
Log:
Starting migration doc for 2.2
Revision Changes Path
1.7 +3 -1 cocoon-2.1/src/documentation/xdocs/plan/release.xml
Index: release.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/plan/release.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- release.xml 7 Oct 2003 08:52:20 -0000 1.6
+++ release.xml 20 Oct 2003 06:48:24 -0000 1.7
@@ -32,6 +32,8 @@
<li>Move to a new Avalon container implementation (Fortress)</li>
<li>Implement parameters for selectors (closed bug #14745)</li>
</ul>
+ <p>The <link href="updating.html">updating to 2.2</link> document contains
more information
+ on how to prepare your application for the next major release.</p>
</s1>
<s1 title="General tasks for a release">
<ul>
1.1 cocoon-2.1/src/documentation/xdocs/plan/updating.xml
Index: updating.xml
===================================================================
<?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="[EMAIL PROTECTED]"/>
<person name="Jörg Heinicke" email="[EMAIL PROTECTED]"/>
<person name="Bertrand Delacrétaz" email="[EMAIL PROTECTED]"/>
</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="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 have been removed:</p>
<ul>
<li><em>org.apache.cocoon.environment.Source</em> : Use the
<em>org.apache.excalibur.source.Source</em> interface instead.</li>
</ul>
</s2>
</s1>
<!--
<s1 title="Sitemap">
<note>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.</note>
<s2 title="Pipelines configuration in the sitemap">
<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 (see also the cocoon.xconf section) and
add the
<code>map:pipes</code> section to the <code>map:components</code>
section
of your sitemap. You can find the pipelines components definition in
the sample
main sitemap of Cocoon. Here is an example:
</p>
<source><![CDATA[
<map:sitemap>
<map:components>
...
<map:pipes default="caching">
<map:pipe name="caching"
src="org.apache.cocoon.components.pipeline.impl.CachingProcessingPipeline"/>
<map:pipe name="noncaching"
src="org.apache.cocoon.components.pipeline.impl.NonCachingProcessingPipeline"/>
</map:pipes>
</map:components>
...
</map:sitemap>
]]></source>
<p>You can choose these different pipeline implementations
in the <code>map:pipeline</code> section by specifying their
<code>type</code> attribute:
</p>
<source><![CDATA[
<map:sitemap>
...
<map:pipelines>
<map:pipeline type="noncaching">
<map:match pattern="welcome">
...
</map:match>
..
</map:pipeline>
</map:pipelines>
</map:sitemap>
]]></source>
<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
<code>map:components</code> section is used.
</p>
</s2>
<s2 title="FOP Serializer">
<p>Relative paths in FOP serializer's <code><user-config></code>
are now resolved
relatively to the directory that contains the sitemap.</p>
<p>All Cocoon URIs are supported too.</p>
</s2>
<s2 title="Sitemap components">
<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
<code>ClassNotFoundException</code>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>
<code>o.a.c.XTTransformer</code> - use the TraxTransformer instead.
</li>
<li>
<code>o.a.c.webapps.authentication.selection.MediaSelector</code> - the
full qualified class
name has changed to
<code>o.a.c.webapps.session.selection.MediaSelector</code>.
</li>
</ul>
</s2>
<s2 title="Error handling">
<p>The <code>map:handle-errors</code> section must now be a complete
pipeline. This means the
old form</p>
<source><![CDATA[
<map:handle-errors>
<map:transform src="stylesheets/system/error2html.xsl"/>
<map:serialize status-code="404"/>
</map:handle-errors>
]]></source>
<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>
<source><![CDATA[
<map:handle-errors>
<map:generate type="notifying"/>
<map:transform src="stylesheets/system/error2html.xsl"/>
<map:serialize status-code="404"/>
</map:handle-errors>
]]></source>
<p>For a more detailed example have a look into the default sitemap
delivered with Cocoon
sources or read the
<link href="../userdocs/concepts/errorhandling.html">documentation on
error handling</link>.
</p>
</s2>
</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="Caching">
<p>Although the basic caching mechanism is still the same (each sitemap
component
in the pipeline is queried), the interface for a component have been
improved as well.</p>
<p>The old interface <em>Cacheable</em> is deprecated in favour of the new
<em>CacheableProcessingComponent</em> interface. The basic behaviour of
this
interface has been preserved, however the method names and the
signatures
have changed a little bit.
</p>
<p>Some other interfaces, like the validity of the cached information has
moved to the source packacke in Avalon Excalibur.</p>
<p>The old interfaces are still support but deprecated, so it's advisable
to
update your components. However, you can support both interfaces at the
same time, making your component runable in old and new Cocoon
installations
at the same time.</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>
