DBPrism - DBPrismGenerator for Cocoon2 ::-

DBPrism Generator for Apache Cocoon 2

Definition:

DBPrismGenerator is the key component which provides the connection between Apache Cocoon Framework and DBPrism.

DBPrismGenerator is an Apache Cocoon Generator, it implements the first step into the cocoon pipeline structure. DBPrismGenerator generates the XML content through the excecution of an stored procedure extracted from the caller url. It extend Apache Cocoon's ComposerGenerator class.

In a Cocoon architecture every Generator is an Avalon component and implements several interfaces that defines different aspect (contracts). DBPrismGenerator implements Composable, Configurable, Recyclable, Cacheable and Contextualizable. The most important interfaces here are described below.

Interfaces

Composable, defines compose() method implemented into the parent class ComposerGenerator.
Configurable, defines configure() method used by DBPrismGenerator to extract the configuration filename and to initialize the DBPrism engine.
Recyclable, defines recycle() method which is called by the Avalon framework to free components that are no longer valid.
Cacheable, defines genrateKey() and generateValidity() methods used by Cocoon's cache system and the key components to implement the ESI Invalidator Server
Contextualizable, defines contextualize() method which provide the HttpServlet context object.

Instance variables

Request request, Cocoon Servlet Request object.
Response response, Cocoon Servlet Response object.
Context context, Cocoon Context object
HttpServletRequest httpRequest, Http Servlet Request object.
DBPrism engine, DBPrism engine instance, which connects this generator with a DBPrism engine.
CocoonRequestWrapper req , wrapper object which provides standard Http Servlet Request methods over a Cocoon's request instance.
Block blocker, simple synchronization object to serialize the parallel content aggregation at the generation stage.
Delayer delayer, private thread object which is responsable for making the excecution of the stored procedure without blocking the Cocoon generation stage.
Server cacheServer , External Cache Invalidator Server instance.
ESIKey key, key value that defines the page, unique in a DBPrismGenerator space.
int cacheControl, which cache control is defined into the sitemap for the current request.

Methods

public void configure(Configuration conf), called by the Avalon Component Manager when this Generator is created. At this point the DBPrismGenerator calls to the init method of DBPrism engine passing the generator argument " prism.xconf" which defines the path and the filename of the DBPrism's configuration file.
public long generateKey(), Returns a long value returned by the execution of the method this.key.getKey(). This key is unique for every call of an stored procedure because there is no information about the content returned by stored procedure, to avoid key duplications into Cocoon MRU Store it includes a random component initialized at Cocoon startup.
public CacheValidity generateValidity(), returns an instance of CacheValidity class, according to sitemap parameter Cache-Control it returns a null value (no-cache), an ExternalCacheValidity (External) or a NOPCacheValidity (NOP).
public void recycle(), called by Avalon Component Manager when this generator is no longer valid, frees all the resources.
public void setup(SourceResolver resolver, Map objectModel, String src, Parameters par), receives all the information needed to make an stored procedure call. At this point DBPrismGenerator creates a private thread (Delayer) which calls to DBPrism engine with the information of the corresponding stored procedure, then the time involved into the execution is parallelized with other calls, this optimization reduces the total execution time when you use Cocoon Content Aggregation.
public void generate(), with this method Cocoon engine will collect the generated XML, DBPrismGenerator first wait until the execution of the stored procedure finish and then execute the method engine.getPage(req) which gets the generated XML page in the database side and is transformed to SAX events by the parser (parser.parse(new InputSource(...));). Before parsing the generated page, it calls the method showPage which analizes the header finding Cookies definitions, authorization response and so on.

Setup

DBPrismGenerator requires configuration into the Cocoon's configurations files. These files are sitemap.xmap, cocoon.xconf and user.roles, the last two files contains confguration for the External Cache Invalidator Server, but DBPrismGenerator is strongly depend on this component.

sitemap.xmap

In this file a new generator has been added on the generator's section, also is defined the pipelines entries for the DBPrism / Cocoon applications. Here an example of an sitemap.xmap file mounted as sub-sitemap using the mount point xmlj/**:

<?xml version="1.0"?>

<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

<!-- =========================== Components ================================ -->

 <map:components>

  <map:generators default="dbprism">
   <!-- ======================= DBPrism 2.0.1-production Generator 
        ========================== -->
   <map:generator  name="dbprism" src="org.apache.cocoon.generation.DBPrismGenerator" 
                   logger="sitemap.generator.dbprism"    label="content,data"
                   properties="/WEB-INF/prism.xconf"/>

   .... other components here ....
   
 </map:components>

<!-- =========================== Pipelines ================================= -->

 <map:pipelines>
  <map:pipeline>

   <!-- ================  DBPrism 2.0.1-production begin here  
        =========================== -->
   <map:match pattern="">
    <map:redirect-to uri="DEMOj.startup"/>
   </map:match>

   <map:match pattern="DEMOj.list*">
    <map:generate src="/xmlj/DEMOj.list{1}"/>
    <map:transform src="stylesheets/query.xsl"/>
    <map:serialize type="html"/>
   </map:match>

   <map:match pattern="DEMOj.excel">
    <map:generate src="/xmlj/DEMOj.excel"/>
    <map:transform src="stylesheets/excel.xsl"/>
    <map:serialize type="excel"/>
   </map:match>

   <map:match pattern="icons/*.gif">
    <map:read src="icons/{1}.gif" mime-type="image/gif"/>
   </map:match>

   <map:match pattern="**">
    <map:generate src="/xmlj/{1}"/>
    <map:transform src="stylesheets/simple-page2html.xsl"/>
    <map:serialize type="html"/>
   </map:match>

  <!-- ================  DB Prism 2.0.1-production end here  
       =========================== -->
  </map:pipeline>

 </map:pipelines>

</map:sitemap>

In this example, the generator entry defines the implementation class for the DBPrismGenerator (src="org.apache.cocoon.generation.DBPrismGenerator"), the short name for it (name="dbprism"), and the configuration file location (properties="/WEB-INF/prism.xconf") which is relative to the context root of the servlet engine.

A relative location for the properties file is new since DBPrism 2.0.0-alpha1, it mean that this properties file is located relative to context root of the application resource. For example dbprism.ear is expanded by the oc4j container in a directory $OC4J_HOME/applications/dbprism/dbprism, this directory is the context root, then properties="/WEB-INF/prism.xconf" means that the phisical location will be $OC4J_HOME/applications/dbprism/dbprism/WEB-INF/prism.xconf .

<map:match> section defines an special mount point for the example. In this example every url starting at xmlj/** will be generated by the generator dbprism (DBPrismGenerator) passing as argument the url rewrited by the regular expresion /xmlj/{1}, that is, for an url http://localhost:8888/dbprism/xmlj/DEMOj.hello?arg=xx DBPrismGenerator will execute the stored procedure hello of the package DEMOj with the argument arg=xx, the DAD (which defines the database connection information) is defined in the prism.xconf file and is located by the name xmlj (first path of the url following the context mount point /dbprism). The xml returned by the execution of the stored procedure is tranformed by the stylesheet simple-page2html.xsl and the output is serialized to html.

This work is licensed under a Creative Commons License .