Cocoon2NetKernel Adaption Kit V0.3.x

Welcome to the Cocoon2NetKernel Adaption Kit. This kit provides a mechanism for using many of the components of the Apache Cocoon project from within 1060 NetKernel. It is provided under the Apache License Version 2.0 licence.

Motivation

In many ways 1060 NetKernel can be seen as a generalisation of a proven sucessful concept of Apache Cocoon. Because Cocoon has been been around for over 5 years it has built up a large community of contributors and a wealth of reuseable components. This project allows this wealth to be leveraged allowing:

NetKernel developers access to the library of Cocoon components
NetKernel and Cocoon developers to more easily make comparisions between the different approaches of NetKernel and Cocoon.

Guide to Setting Up

1) Prerequisites

Cocoon2NetKernel Adaption Kit requires that you have a distribution of Apache Cocoon and an installed version of NetKernel Standard Edition. This release has been tested with version v2.1.5 of Cocoon and v1.3.0 of NetKernel. Cocoon can be obtained from the Cocoon Site. NetKernel can be obtained from 1060.org.

2) Install NetKernel

If NetKernel is not already installed use the installation process described here.

3) Build Cocoon

Cocoon ships in source code form. Use the supplied build script first.

Certain files from the Cocoon distribution are required to be copied into the Cocoon2NetKernel Adaption Kit module and NetKernel restarted before any Cocoon functionality will be available. How to do this depends upon how you wish to install the Adaption Kit.

3a) Install using a checked out CVS directory from SourceForge

Checkout the latest files from the CVS repository into a local directory under [NetKernel-Install-Path]/modules/
Copy all the JAR files from [Cocoon-Install-Path]/build/webapp/WEB-INF/lib/ to the lib directory directly below your expanded adaption kit module directory. (Two exceptions- don't copy axis-jaxrpc-1.1.jar, xml-apis.jar - they overrides the XML APIs shipped with the JDK). Also copy the file [Cocoon-Install-Path]/lib/optional/servlet_2_2.jar which is needed by the build process.
Build the Adaption Kit using the supplied ANT build script build_mod_cocoon.xml. You will first need to edit this file to specify the location you installed NetKernel.
Edit the file [NetKernel-Install-Path]/etc/deployedModules.xml and add a line to it to reference the new module. Add a line which contains the path to the Adaption Kit module directory. (It must end with a slash.)
Start NetKernel as described in the NetKernel install instructions.

3b) Install using Install Wizard

Start NetKernel and use the Install Wizard to download and install the Cocoon2NetKernel Adaption Kit from one of the 1060 mirrors. You must ensure Display Libraries is select in the wizard.
The Adaption Kit will have been installed as a JAR file this must be expanded so that the cocoon libraries can be added. Expand the JAR to a directory in the same location as the JAR (The directory of this will be [NetKernel-Install-Path]/modules/ )
Edit the file [NetKernel-Install-Path]/etc/deployedModules.xml and change the line which references the adaption kit module jar to reference the new adaption kit module directory. (Take off the .jar and replace with forward slash.
Copy all the JAR files from [Cocoon-Install-Path]/build/webapp/WEB-INF/lib/ to the lib directory directly below your expanded adaption kit module directory. (Two exceptions- don't copy axis-jaxrpc-1.1.jar, xml-apis.jar - they overrides the XML APIs shipped with the JDK).
Perform a NetKernel cold restart.

Check it works

Try out some of the examples below.

Features and Limitations

Limitations

This adaption kit does not aim to provide complete Cocoon site compatibility:

Only Generators, Transformers and Serializers are supported. Matchers, Selectors, Actions and Readers are not. However the equivalent functionality can be provided in NetKernel specific ways.
Sitemaps are not supported. However alternate pipeline scripting mechanisms such as DPML or XRL can be used.
No access to Object Model. Components do not have access to the underlying object model/environment which is used as a global variable store shared between all components and pipelines executed to satisfy a request. In NetKernel all components must explicitly declare and have passed to them any arguments they require to execute. This enables a strict dependency chain to be generated for any resource improving cacheability and enabling functional programming style lazy evaluation to be acheived. This factor alone is the major reason why some cocoon components may not be useful when running within NetKernel and as such may be addressed in future releases of this Adaption Kit.
No component pooling. NetKernel already caches its components, accessors, so component pooling was deemed unecessary.

Features

If you are new to NetKernel some of the following features may be of interest:

Strict dependency caching. The result of every pipeline is guaranteed to depend upon all resource which it used in its execution. This has two advantages. Optimal caching and reuse is acheived in production and development is easier as results are always recomputed when necessary (just like in a spreadsheet)
Mix SAX with DOM. SAX is more efficient when dealing with large documents in limited memory environments, DOM is necessary for certain classes of complex manipulation. Mix and match within a pipeline if necessary. Indeed you can also use non-XML data types or extend with alternate XML representations such as JDOM or DOM4J. Conversion between representations is usually implicit using NetKernels representation/aspect/transrepresentation abstraction.
Modular configuration. Only the lowest level configuration of the NetKernel kernel is global. All other configuration is modularised within modules this allows concurrent versions to deployed simultaneously without interference. It also allows parts of your application or libraries to be deployed or upgraded safely.
Extensible language support. You are not limited to linear pipelines where components have one input and one output. DPML provides support for components with multiple inputs, conditional and iterative processing and exception handling. New language runtimes can be developed and deployed.
More deployment options. In addition to the deployment options presented by Cocoon, NetKernel can be deployed as an embedded co-processor within an existing Java application. Alternatively custom transports can be developed to create services such as email servers, instant messaging, p2p and mobile messaging services that are not served over HTTP.
Web based management console. Full control and remote admistration of a NetKernel instance is provided with the control panel.
Debugger Breakpoints can be set on instructions within pipelines. When a breakpoint occurs the inputs and outputs can be introspected.

Examples

See the examples here.

Errors and Troubleshooting

Error	Description
Error sourcing resource resource /org/apache/cocoon/cocoon.roles not found	You have not copied the Cocoon jars into the module- see the install guide.
Failed to access Cocoon Object Model	See the limitations section above.
Unsupported Generator Unsupported Transformer Unsupported Serializer	You have mispelled the name of the component class.

Further non Adaption Kit errors are documented here.