Apache Cocoon Tutorial for Beginners
2019-06-13 10:25:30

Apache Cocoon Tutorial for Beginners

What is Apache Cocoon?

  • Apache Cocoon is a framework, developed under Apache Software Foundation.
  • It is an open-source software(based on the Apache License 2.0) and being continued under the Apache Cocoon Project.
  • Apache Cocoon framework is built around two core concepts, first is the separation of concerns and second is component-based development.
  • Since version 2.2 of Cocoon, it has been migrated from Avalon-based component manager to Spring 2.0 based component manager.

Special Features of Apache Cocoon

  • Apache Cocoon implements its core concepts i.e., concepts of separation of concerns and component-based development, around the idea of component pipelining.
  • Each component of Cocoon which resides on the pipeline, specialized on a particular operation and this specialization hooks together components into pipelines by using a Lego(tm)-like approach in building web solutions, and this does not require any extra programming effort.
  • Cocoon works as webglue when used as a web framework for web application development. This cocoon web glue keeps concerns separate improves development pace and reduces the chance of conflicts.
  • Cocoon supports multiple output formats by offering continuation based web controller implementations that comes with a JSR-168 compatible portal implementation.
  • Advanced Control Flow feature: It separates the view and data components by hiding the complexity of request/ response processing using continuation-based page flow.
  • Cocoon tightly integrates many technologies but does not duplicate efforts.
  • It integrates Java data binding frameworks (Castor, Betwixt) and tightly integrates Spring Framework.
  • It provides support for easy integration of object-relational frameworks like Hibernate, OJB, etc.
  • It provides strong validation for form handling through Cocoon Forms.

What are Cocoon blocks?

Cocoon describes block as the unit of modularization technically. It is a jar file that follows a particular directory structure. Cocoon's core modules, i.e. Spring integration, Sitemap, and Pipeline implementation, serve as blocks. Even custom-made Cocoon applications are developed as blocks.

A block provided the following features:

    • General Service-Cocoon servlet-service framework can manage any type of servlet.
    • Special Service-Pipelines are provided as services.
  • Component Service-Provides component-based services such as spring beans, Avalon services/components.
  • Container Service-Serves as a container for classes and resources.
  • Package Service-It can be packaged as a JAR (java archive) by following certain conventions regarding the directory structure.

Cocoon blocks can be downloaded separately; you can find all available blocks here:

Cocoon Core Module
NAME VERSION OVERVIEW
Core 2.2 Cocoon's core module works like a wrapper for all dependencies and this makes Cocoon ready to use as a web application framework.
Cocoon core module is used as a dependency in Maven2, and it is further divided into sub-modules. Cocoon Core Sub Modules
NAME VERSION OVERVIEW
Expression Language API 1.0 It contains various interfaces for object model and expression language.
Expression Language Impl 1.0 Currently, the module provides the implementation for three languages (JXPath, Jexl, JavaScript) and the API also has Object Model Interface to operate data with expression language.
Pipeline API 1.0 The API contains interfaces for use by SAX pipelines.(namely ProcessingPipeline, Sitemap components, XML interface, etc.)
Pipeline Components 1.0 Provides implementation for several needed classes and components (for ex. Generators, transformers, serializers, XPointer, XSLT, etc.)
Sitemap API 1.0 Provides various interfaces for the sitemap (for ex. Processor, actions, modules, classloading, processing, notification, etc.)
Sitemap Components 1.0 Provides implementation for Sitemap API interfaces for being used in Cocoon web apps
Sitemap Implementation 1.0 Provides implementation to write sitemap components. It contains classes, Spring packages for Avalon support and also provides implementation with dependencies, for tree processor of the sitemap
Store Implementation 1.0 It contains several components which provide the implementation for the Excalibur Store Interface
Thread API 1.0 Contains various interfaces for the execution of background tasks, pools and thread factories
Thread Implementation 1.0 Provides implementation for Thread API interfaces
Util 1.0 Contains various utility classes
XML API 1.0 XML API Contains SAXParser and DOMParser interfaces
XML Implementation 1.0 Provides implementation for XML API interfaces
XML Resolver 1.0 It is a system resolver component with default entities
XML Util 1.0 It contains various utility classes, especially for XML
 
NAME VERSION DESCRIPTION
Ajax 1.0 Used for partial page and form reloads
Apples 1.0 It is a control flow implementation, it is java based but doesn't support continuations indifference to Flowscript and Javaflow.
Authentication 1.0 Used in control-flow based cocoon applications with authentication and authorization of pipelines.
Batik 1.0 By using cocoon pipelines, Scalable Vector Graphics (SVG) can be created.
Captcha 1.0 Used to create CAPTCHAs
Databases 1.0 Relational databases can be used directly with sitemap components
Flowscript 1.0 Implementation of control flow based on Rhino
FOP 1.0 Formats the prints to render pages to PDF or Postscript
Forms 1.0 Can create interactive web forms using Flow and JXTemplates, simple enough to use by non-java programmer
Hsqldb Client 1.0 Provide access to Hsql database
Hsqldb Server 1.0 Start a Hsql database server as part of Cocoon application
HTML 1.0 Deals with HTML
Linkrewriter 1.0 Links containing elements can be rewritten
Mail 1.0 Sitemap components to send emails
Template 1.0 XML-based templating

Where can Cocoon be used?

  • Cocoon can be used for multi-channel web publishing dynamically.
  • For separating data from the view and creating static content automatically.
  • Offline Generation Mode: Can be used offline with its own offline facilities like command-line interface, ant task, etc.
  • Forrest Run Mode: can be used for dynamic document preparation with Apache Forrest even using many different types of data input formats.
  • Cocoon Portal Framework: can be used for developing the company's portal.
  • Cocoon supports multiple clients, layouts, and languages (i18n) and without duplicity.
  • It can be used as the base for Content Management System, for producing mobile content and data warehouse reporting across multiple formats.

Data Conversion by Cocoon Pipelines

Cocoon pipelines can process multiple data types of data and can convert them to XML. See a list of different types of data that can be converted to XML:
  • XML files
  • XML databases
  • XML based web services
  • CVS which is supported by an external project CVSSource
  • WebDAV
  • SAP (r) systems by adding the SAP JavaConnector
  • Text-based file formats
  • Flash
  • JSP
  • XMidi
  • LDAP etc.

Data Type Conversion in Cocoon (from XML to other Formats)

As several types of data can be converted to XML. In the same way, XML format can be converted to several data types. For example:
  • XML
  • XHTML
  • HTML
  • PDF
  • RTF
  • Postscript
  • Charts
  • Flash
  • Plain text
  • ZIP archives
  • MIDI

Apache Cocoon Versions

From its birth in 1999, Cocoon has grown big till now with regularly updating to the newest version. Here is a list of all available version so far:
Version Latest Release
Cocoon 1.x Not recommended to use now
Cocoon 2.0 2.0.4 ( not recommended to use now)
Cocoon 2.1 2.1.11(stable)
Cocoon 2.2 2.2(stable)
Cocoon 3.0 3.0.0-alpha-3(not stable)

How to download Apache Cocoon?

Cocoon 2.2.0 is the most stable and latest version till now.Let's download the latest version. Go to official Apache Cocoon Project website (http://cocoon.apache.org/1284_1_1.html) and download the latest released version. As Cocoon comes with its core modules (i.e., pipelines, sitemaps, servlet, spring integration), you can also download other blocks, which can be used for different tasks as per your needs. A comprehensive list of all available blocks can be found here at official link: http://cocoon.apache.org/2.2/blocks/1204_1_1.html.

How to make an application using Cocoon 2.2

Step1: Before using Cocoon, Maven 2.0.9 or above version should be installed in your system. Maven installation can be verified by calling mvn -version from the command line. If it is not installed, then follow the steps given below:

Download and install Apache Maven 3.6.1 (latest version release)

  1. Ensure JDK 1.7 or above is installed in the system. Then, set JAVA_HOME environment variable as per JDK installation directory and points to the bin folder of JDK.
  2. Download the zip file of Apache Maven 3.6.1 from the official link: http://maven.apache.org/download.cgi
  3. Not extract distribution archive file in any directory by using the following command on the command line of that directory:
unzip apache-maven -3.6.1-bin.zip
  1. Now set the PATH environment variable by adding its value to the bin directory of the apache-maven-3.6.1 directory.
  2. Confirm the Maven installation by the command mvn –v
This command will display some result specifying Apache Maven version, Java Version, etc. Step2: Now, we will create a new directory for our new Cocoon application with the name myFirstCocoonApp. All the applications reside inside Cocoon block, so now we will create a Cocoon block using the following Maven command: mvn archetype: generate –DarchetypeCatalog=http://cocoon.apache.org Here, some output will be generated asking some information, select here item no.2 as the choice, again it will ask some other questions and answer accordingly. This will create the following type of directory structure: 
 
myFirstCocoonApp
 +-myCocoonBlock1
 +-pom.xml
 +-src
 +-[...]
Step3: Now, we will import the block in Eclipse IDE. Open the command prompt in block1 directory and enter the command: mvn eclipse:eclipse. This command will create the necessary descriptors required for the project set up in Eclipse. Now, import the project in the following workspace: File -> Import -> Existing Projects into Workspace. Step4: Now, we will run this block as a Java web application by invoking mvn jetty:runcommand, this command will automatically create a minimal hello world page web application. Now go to the address http://localhost:8888/myCocoonBlock1/ in the web browser, this will display a hello world page. And that's all done.

Modularization of Cocoon apps (using Blocks)

As the concept of modularization says that any large structure should be split up in small modules (section) to understand it better, and to work smoothly and efficiently with its parts. This concept is achieved in Cocoon based application by using blocks. Here the whole application is separated in blocks as per its purpose, for example, one block for view section, the other for design purpose, the other one for the business logic purpose, etc. Now we will create a second block and connect them to merge into a single application.

Creating a second Cocoon block

Step1: Go to the myFirstCocoonApp directory and use the Maven command again as follows: mvnarchetype:generate –DarchetypeCatalog=http://cocoon.apache.org andchoose the archetype as option no.2 (option no. 2 creates a Cocoon block containing some small samles) and set the artifactId as myCocoonBlock2. This will create the following directory structure: 
myFirstCocoonApp
 +-myCocoonBlock1
 +-pom.xml
 +-src
 +-[...]
 +-myCocoonBlock2
 +-pom.xml
 +-src
 +-[...]
Step2: Now, go to myCocoonBlock2 folder and execute the command as follows: mvn install eclipse:eclipse and this will build and copy the second block into the local Maven repository after it other blocks and projects can see it and the block can be imported in Eclipse as a project.

Connecting the two blocks

Step1: Now, we will establish a connection between these two blocks using pipeline by editing myFirstCocoonApp/myCocoonBlock1/src/main/resources/META-INF/cocoon/spring/block-servlet-service.xml as follows: 
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:servlet="http://cocoon.apache.org/schema/servlet"
 xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
 http://cocoon.apache.org/schema/servlet http://cocoon.apache.org/schema/servlet/cocoon-servlet-1.0.xsd">
<bean id="com.myExample.myCocoonBlock1.service" class="org.apache.cocoon.sitemap.SitemapServlet">
<servlet:context mount-path="/myCocoonBlock1" context-path="blockcontext:/myCocoonBlock1/">
<servlet:connections>
<entry key="myCocoonBlock2" value-ref="com.myExample.myCocoonBlock2.service"/>
</servlet:connections>
</servlet:context>
</bean>
</beans>
Here, com.myExample is the groupId which was created during block creation. Step2:Now, add the dependency in myCoccoonBlock1 for myCocoonBlock2 by modifying the first block i.e. myCocoonBlock1 project descriptor in myfirstCocoonApp/myCocoonBlock1/pom.xml file as follows: 
<?xml version="1.0" encoding="UTF-8"?>
<project>
 [...]
<dependencies>
 [...]
<dependency>
<groupId>com.myExample</groupId>
<artifactId>myCocoonBlock2</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
</dependencies>
 [...]
</project>
Step3: Now, we will add the location of myCocoonBlock2 into the configuration file of myCocoonBlock1. By adding this location, we will get the advantage that whenever any changes take place in myCocoonBlock2, all the changes will immediately reflect in myCocoonBlock1. Update the configuration file by opening myFirstCocoonApp/myCocoonBlock1/rcl.properties and add the following code: Apache Cocoon Step4: Now, restart the servlet container by invoking the following command: mvn jetty:run Step5: To test the connection and all updates, add a pipeline to the sitemap of myCocoonBlock1 in the file: myFirstCocoonApp/myCocoonBlock1/src/main/resources/COB-INF/sitemap.xmapas follows: 
<?xml version="1.0" encoding="UTF-8"?>
<map:sitemapxmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:pipelines>
 [...]
<map:pipeline>
<map:match pattern="callingBlock2">
<map:generatesrc="servlet:myCocoonBlock2:/spring-bean" type="file"/>
<map:serialize type="xml"/>
</map:match>
</map:pipeline>
 [...]
</map:pipelines>
</map:sitemap>
The servlet protocol, a special purpose protocol, is used here to access a pipeline that is defined in another block. Step6: Now, access the block through a web browser at http://localhost:8888/myCocoonBlock1/callingBlock2. The output will be shown as per the content of myCocoonBlock2, but it will be routed through myCocoonBlock1.