You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by il...@apache.org on 2012/04/24 14:40:02 UTC
svn commit: r1329677 [8/27] - in /cocoon/site/site/2.2/core-modules: ./
core/ core/2.2/ core/2.2/css/ core/2.2/images/ core/2.2/js/ core/css/
core/images/ core/images/logos/ core/js/ css/ images/ js/
Modified: cocoon/site/site/2.2/core-modules/core/2.2/675_1_1.html
URL: http://svn.apache.org/viewvc/cocoon/site/site/2.2/core-modules/core/2.2/675_1_1.html?rev=1329677&r1=1329676&r2=1329677&view=diff
==============================================================================
--- cocoon/site/site/2.2/core-modules/core/2.2/675_1_1.html (original)
+++ cocoon/site/site/2.2/core-modules/core/2.2/675_1_1.html Tue Apr 24 12:39:52 2012
@@ -29,17 +29,13 @@
<head>
<title> Cocoon Core - CacheableProcessingComponent Contracts
</title>
- <style type="text/css" media="all">
- @import url("./css/maven-base.css");
- @import url("./css/maven-theme.css");
- @import url("./css/site.css");
- </style>
+ <link rel="stylesheet" href="./css/apache-cocoon-thien-maven-skin.min.css" />
<link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
- <script src="./js/getBlank.js" language="javascript" type="text/javascript"></script>
- <meta name="author" content="The Cocoon Community" />
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+ <script src="./js/apache-cocoon-thien-maven-skin.min.js" language="javascript" type="text/javascript"></script>
+ <meta name="author" content="Apache Cocoon Documentation Team" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
- <body>
+ <body onload="javascript:prettyPrint();">
<div id="breadtrail">
<p><a href="http://www.apache.org">Apache</a> » <a href="../../../../">Cocoon</a> »</p>
</div>
@@ -77,7 +73,7 @@
<li><a href="../../../../2.2/core-modules/">Core <span class="pl-version-small">2.2</span></a></li>
<li><a href="../../../../2.2/blocks/">Blocks <span class="pl-version-small">2.2</span></a></li>
<li><a href="../../../../2.2/maven-plugins/">Maven Plugins <span class="pl-version-small">2.2</span></a></li>
- <li><strong><a href="../../../..//3.0/">Cocoon 3.0 <span class="pl-version-small">[alpha]</span></a></em></strong></li>
+ <li><strong><a href="../../../..//3.0/">Cocoon 3.0</a></em></strong></li>
<li><strong><a href="../../../../subprojects/">Subprojects</a></strong></li>
</ul>
</div>
@@ -92,7 +88,7 @@
<ul>
<li >
- <a href="1270_1_1.html">Introduction</a>
+ <a href="index.html">Introduction</a>
</li>
</ul>
</li>
@@ -315,8 +311,6 @@
-
-
<li class='menuCollapse'>
<a href="842_1_1.html">Reference</a>
@@ -604,7 +598,7 @@
</li>
<li >
- <a href="1380_1_1.html">Using Control Flow</a>
+ <a href="1380_1_1.html">Using Control Flow</a>
</li>
</ul>
</li>
@@ -638,11 +632,11 @@
</li>
<li >
- <a href="1399_1_1.html">Logging configuration</a>
+ <a href="1399_1_1.html">Logging Configuration</a>
</li>
<li >
- <a href="1259_1_1.html">Component Configurations</a>
+ <a href="1259_1_1.html">Component Configuration</a>
</li>
<li >
@@ -651,43 +645,37 @@
</ul>
</li>
<li>
- Project Documentation
+ Project Reports
<ul>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li class='menuCollapse'>
- <a href="project-info.html">Project Information</a>
- </li>
+ <li >
+ <a href="changes-report.html">Changes Report</a>
+ </li>
-
-
-
-
-
-
-
-
- <li class='menuCollapse'>
- <a href="project-reports.html">Project Reports</a>
- </li>
+ <li >
+ <a href="apidocs/">JavaDocs</a>
+ </li>
</ul>
</li>
</ul>
<div class="main">
- <div id="contentBody"><div id="bodyText"><h1 class="docTitle">CacheableProcessingComponent Contracts</h1><h1 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">CacheableProcessingComponent Contracts</h1><p>Just about everything can be cached, so it makes sense to provide some
+ <!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License. -->
+ <div id="contentBody"><div id="bodyText"><h1 class="docTitle">CacheableProcessingComponent Contracts</h1><h1>CacheableProcessingComponent Contracts</h1><p>Just about everything can be cached, so it makes sense to provide some
controls to make sure that the user always gets valid results. There are two
aspects to a cacheable component: the key and the validition. The key is used to
determine within the component's scheme of things whether a result is unique.
@@ -700,7 +688,7 @@ value if there is one. If the cache has
CachingPipeline will return the cached results. If either condition is false,
then the CachingPipeline will generate the results and cache it for later use.
It is important to realize that only the CachingPipeline will respect the
-contracts outlined in this document.</p><h2 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">The Cache Key</h2><p>The cache key is the single most important part of the caching
+contracts outlined in this document.</p><div class="section" style="background:none;padding:0;"><h2 style="background:none;padding:0;">The Cache Key<a name="The_Cache_Key"></a></h2></div><p>The cache key is the single most important part of the caching
implementation. If you don't get it right, you can introduce more load on the
caching engine than is necessary. It is important that the cache key has the
following attributes:</p><ul>
@@ -710,22 +698,22 @@ method).</li>
<li>It must be Unique within the space of the component (i.e. the key "1" for
<tt>MyCacheableComponent </tt>must be for the same resource every time, but we
don't have to worry about the key "1" for YourCacheableComponent).</li>
-<li>The <tt>equals()</tt> and <tt><tt><tt>hashCode()</tt></tt></tt> methods must
+<li>The <tt>equals()</tt> and <tt>hashCode()</tt> methods must
be consistent (i.e. if two keys are equal, the hashCode must also be equal).
</li>
</ul>Thankfully there is a perfectly suitable object that satisfies these
obligations from Java's core: <tt>java.lang.String</tt>. You can also use your
own specific key objects provided they respect those contracts.If the cache key is <tt>null</tt> then your component will not be cached at
all. You can use this to your advantage to cache some things but not others.
-<h2 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">The Source Validity</h2>The caching contracts use the Excalibur SourceValidity interface to determine
+<div class="section" style="background:none;padding:0;"><h2 style="background:none;padding:0;">The Source Validity<a name="The_Source_Validity"></a></h2></div>The caching contracts use the Excalibur SourceValidity interface to determine
whether a resource is valid or not. The validity can be a compound check that
incorporates time since creation, parameter values, etc. As long as the sitemap
can determine whether the cached resource is valid or not. More information is
available on the
-<a href="http://excalibur.apache.org/sourceresolve/index.html">Apache Excalibur
+<a class="externalLink" href="http://excalibur.apache.org/sourceresolve/index.html">Apache Excalibur
site</a>. Alternatively you can use the built in CacheValidity objects in the
<tt>org.apache.cocoon.caching</tt> package and then use the
-<a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/caching/CacheValidityToSourceValidity.html">CacheValidityToSourceValidity</a>
+<a class="externalLink" href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/caching/CacheValidityToSourceValidity.html">CacheValidityToSourceValidity</a>
adaptor object.The SourceValidity interface provides two <tt>isValid()</tt> methods, which
are used to check the validity of a source. The first call is to the version
without parameters, which the SourceValidity will return
@@ -753,25 +741,25 @@ component are (in the order of commonali
long as all the encapsulated validity objects are valid</li>
<li><tt>DeferredAggregatedValidity</tt>--a compound validity object that only
gets validity objects if they are needed.</li>
-</ul><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">NOPValidity</h3>Use the NOPValidity if you want to manually invalidate the cache entry for an
+</ul><div class="section"><h3>NOPValidity<a name="NOPValidity"></a></h3>Use the NOPValidity if you want to manually invalidate the cache entry for an
item, or if you have an object that is created once and simply reused. It has
limited use, but it is the easiest to set up. Just implement the
-<tt>getValidity()</tt> method like this:<pre>public SourceValidity getValidity()
+<tt>getValidity()</tt> method like this:<div><pre>public SourceValidity getValidity()
{
return NOPValidity.SHARED_INSTANCE;
}
-</pre><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">TimeStampValidity</h3>The TimeStampValidity object is most commonly used with blobs retrieved from
+</pre></div></div><div class="section"><h3>TimeStampValidity<a name="TimeStampValidity"></a></h3>The TimeStampValidity object is most commonly used with blobs retrieved from
the database, or some other information that only needs to be refreshed when a
newer version exists. The TimeStampValidity will always return
<tt>SourceValidity.UNKNOWN</tt> until it is compared against a new
TimeStampValidity object so that it can compare the dates. You can use this
-validity object like this:<pre>SourceValidity validity = new TimeStampValidity(timestamp.getTime());
+validity object like this:<div><pre>SourceValidity validity = new TimeStampValidity(timestamp.getTime());
public SourceValidity getValidity()
{
return validity;
}
-</pre><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">ExpiresValidity</h3>The ExpiresValidity object is used for items you want to keep around for a
+</pre></div></div><div class="section"><h3>ExpiresValidity<a name="ExpiresValidity"></a></h3>The ExpiresValidity object is used for items you want to keep around for a
while, but you know they will change within a certain amount of time. One
example would be a clock snippet generator for your site. The clock is not going
to change for the granularity that you are displaying. If the clock is
@@ -779,13 +767,13 @@ displaying the hour and minute, then you
System.currentTimeMillis() plus one minute. All calls during that minute would
reuse the same information. While I doubt we would have a component that only
generates the time of day, you get the general idea. You would set it up like
-this:<pre>SourceValidity validity = new ExpiresValidity(System.currentTimeMillis() + (60 * 1000));
+this:<div><pre>SourceValidity validity = new ExpiresValidity(System.currentTimeMillis() + (60 * 1000));
public SourceValidity getValidity()
{
return validity;
}
-</pre><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">FileTimeStampValidity</h3>The FileTimeStampValidity is used most often by components that depend on an
+</pre></div></div><div class="section"><h3>FileTimeStampValidity<a name="FileTimeStampValidity"></a></h3>The FileTimeStampValidity is used most often by components that depend on an
external file to produce its output. The most common examples would be your
FileGenerator and the XSLTransformer components. The FileTimeStampValidity
always checks the source file itself and uses the file system's timestamp to
@@ -793,17 +781,17 @@ verify if the entry is still valid. You
passing in the File reference, passing in the filename as a string, and passing
in a combination of the File and the original timestamp. The
FileTimeStampValidity is commonly used by the FileSource object. Below is an
-example of using the validity object:<pre>SourceValidity validity = new FileTimeStampValidity( sourceFile );
+example of using the validity object:<div><pre>SourceValidity validity = new FileTimeStampValidity( sourceFile );
public SourceValidity getValidity()
{
return validity;
}
-</pre><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">AggregatedValidity</h3>The AggregatedValidity is the mechanism that you would usually use to combine
+</pre></div></div><div class="section"><h3>AggregatedValidity<a name="AggregatedValidity"></a></h3>The AggregatedValidity is the mechanism that you would usually use to combine
any of the above validity types together and validate against all of them. For
example, let's assume your Generator depends on a source file, but it also
depends on some time dependant information that needs to be calculated every
-minute. We would set it up like this:<pre>AggregatedValidity validity = new AggregatedValidity();
+minute. We would set it up like this:<div><pre>AggregatedValidity validity = new AggregatedValidity();
validity.add( fileSource.getValidity() );
validity.add( new ExpiresValidity( System.currentTimeMillis() + (60 * 1000) ) );
@@ -811,25 +799,29 @@ public SourceValidity getValidity()
{
return validity;
}
-</pre><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">DefferedAggregatedValidity</h3>We usually don't use this validity object directly for Sitemap components,
+</pre></div></div><div class="section"><h3>DefferedAggregatedValidity<a name="DefferedAggregatedValidity"></a></h3>We usually don't use this validity object directly for Sitemap components,
but it is referenced for the sake of completeness. It is used just like the
AggregatedValidity object, only it adds an additional method to add
DeferredValidity objects. The purpose is presumably to perform lazy
initialization on some expensive validity objects so that the normal validity
objects are evaluated first, and the other validity objects are created on
demand. There are no stock DeferredValidity object implementations that I know
-of, so this is of little more than academic value for Cocoon components.</div><div class="editUrl"><div><em>Errors and Improvements?</em> If you see any errors or potential improvements in this document please help
- us: <a href="http://cocoon.zones.apache.org/daisy/cdocs/675?branch=1&language=1">View, Edit or comment</a> on the latest development version (registration required).
- </div></div></div>
+of, so this is of little more than academic value for Cocoon components.</div></div>
+ </div>
</div>
</div>
<!-- end of content -->
<div id="footer">
- <p>©
- 1999-2008
+ <p>Copyright ©
+ 1999-2012
The Apache Software Foundation
+ All Rights Reserved.</p>
+
+ <p>
+ Apache Cocoon, Apache, the Apache feather logo, and the Apache Cocoon project logos are trademarks of The Apache Software Foundation.
+ All other marks mentioned may be trademarks or registered trademarks of their respective owners.
</p>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
Modified: cocoon/site/site/2.2/core-modules/core/2.2/676_1_1.html
URL: http://svn.apache.org/viewvc/cocoon/site/site/2.2/core-modules/core/2.2/676_1_1.html?rev=1329677&r1=1329676&r2=1329677&view=diff
==============================================================================
--- cocoon/site/site/2.2/core-modules/core/2.2/676_1_1.html (original)
+++ cocoon/site/site/2.2/core-modules/core/2.2/676_1_1.html Tue Apr 24 12:39:52 2012
@@ -29,17 +29,13 @@
<head>
<title> Cocoon Core - Creating an Action
</title>
- <style type="text/css" media="all">
- @import url("./css/maven-base.css");
- @import url("./css/maven-theme.css");
- @import url("./css/site.css");
- </style>
+ <link rel="stylesheet" href="./css/apache-cocoon-thien-maven-skin.min.css" />
<link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
- <script src="./js/getBlank.js" language="javascript" type="text/javascript"></script>
- <meta name="author" content="The Cocoon Community" />
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+ <script src="./js/apache-cocoon-thien-maven-skin.min.js" language="javascript" type="text/javascript"></script>
+ <meta name="author" content="Apache Cocoon Documentation Team" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
- <body>
+ <body onload="javascript:prettyPrint();">
<div id="breadtrail">
<p><a href="http://www.apache.org">Apache</a> » <a href="../../../../">Cocoon</a> »</p>
</div>
@@ -77,7 +73,7 @@
<li><a href="../../../../2.2/core-modules/">Core <span class="pl-version-small">2.2</span></a></li>
<li><a href="../../../../2.2/blocks/">Blocks <span class="pl-version-small">2.2</span></a></li>
<li><a href="../../../../2.2/maven-plugins/">Maven Plugins <span class="pl-version-small">2.2</span></a></li>
- <li><strong><a href="../../../..//3.0/">Cocoon 3.0 <span class="pl-version-small">[alpha]</span></a></em></strong></li>
+ <li><strong><a href="../../../..//3.0/">Cocoon 3.0</a></em></strong></li>
<li><strong><a href="../../../../subprojects/">Subprojects</a></strong></li>
</ul>
</div>
@@ -92,7 +88,7 @@
<ul>
<li >
- <a href="1270_1_1.html">Introduction</a>
+ <a href="index.html">Introduction</a>
</li>
</ul>
</li>
@@ -319,8 +315,6 @@
-
-
<li class='menuCollapse'>
<a href="842_1_1.html">Reference</a>
@@ -608,7 +602,7 @@
</li>
<li >
- <a href="1380_1_1.html">Using Control Flow</a>
+ <a href="1380_1_1.html">Using Control Flow</a>
</li>
</ul>
</li>
@@ -642,11 +636,11 @@
</li>
<li >
- <a href="1399_1_1.html">Logging configuration</a>
+ <a href="1399_1_1.html">Logging Configuration</a>
</li>
<li >
- <a href="1259_1_1.html">Component Configurations</a>
+ <a href="1259_1_1.html">Component Configuration</a>
</li>
<li >
@@ -655,43 +649,37 @@
</ul>
</li>
<li>
- Project Documentation
+ Project Reports
<ul>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li class='menuCollapse'>
- <a href="project-info.html">Project Information</a>
- </li>
+ <li >
+ <a href="changes-report.html">Changes Report</a>
+ </li>
-
-
-
-
-
-
-
-
- <li class='menuCollapse'>
- <a href="project-reports.html">Project Reports</a>
- </li>
+ <li >
+ <a href="apidocs/">JavaDocs</a>
+ </li>
</ul>
</li>
</ul>
<div class="main">
- <div id="contentBody"><div id="bodyText"><h1 class="docTitle">Creating an Action</h1><h1 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Creating an Action</h1><p>Actions are unique in the world of Sitemap components. They don't implement
+ <!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License. -->
+ <div id="contentBody"><div id="bodyText"><h1 class="docTitle">Creating an Action</h1><h1>Creating an Action</h1><p>Actions are unique in the world of Sitemap components. They don't implement
the SitemapModelComponent and they merely exist to perform processing. For most
business level processing, flowscript usually works better. However there are
some systemic things we can implement using actions quite nicely. Actions are
@@ -705,16 +693,16 @@ supplying several pieces of information
<tt>java.util.Map</tt>. There are three outcomes from processing an action: the
action succeeds and returns a java.util.Map, the action fails and return
<tt>null</tt>, or the action throws an Exception. In the sitemap, an Action is
-invoked like this:</p><pre><map:act type="my-action" src="foo">
+invoked like this:</p><div><pre><map:act type="my-action" src="foo">
<map:generate src="{actionval}.xml"/>
<map:serialize/>
</map:act>
-</pre><p>The sitemap only executes the elements internal to the <tt>map:act</tt>
+</pre></div><p>The sitemap only executes the elements internal to the <tt>map:act</tt>
element when the Action returns a Map. If the Action returns null, that snippet
is skipped. Using this to your knowledge you can provide confirmation pages that
only show up when everything is processed successfully, otherwise we fall
through to the remainder of the sitemap. Obviously we don't want to throw an
-exception if we can help it.</p><h2 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">What the Sitemap Provides</h2><p>The sitemap provides the following elements:</p><ul>
+exception if we can help it.</p><div class="section" style="background:none;padding:0;"><h2 style="background:none;padding:0;">What the Sitemap Provides<a name="What_the_Sitemap_Provides"></a></h2></div><p>The sitemap provides the following elements:</p><ul>
<li>Redirector--to perform redirects within the Action based on your logic.</li>
<li>SourceResolver--to find resources.</li>
<li>Object Model--to gain access to the request, context, and session objects.
@@ -724,28 +712,28 @@ exception if we can help it.</p><h2 xmln
</ul>Most of these items were covered in the
<a href="673_1_1.html">SitemapModelComponent Contracts</a> documentation. The only
item not covered so far is the Redirector. The
-<a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/environment/Redirector.html">org.apache.cocoon.environment.Redirector</a>
+<a class="externalLink" href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/environment/Redirector.html">org.apache.cocoon.environment.Redirector</a>
provides an interface to send a redirect so tha the browser requests a new
-document and we stop processing this one.<div class="fixme"><div><strong>Fixme: </strong>We need more information on when to call which method on the
-Redirector</div></div><h2 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Creating the Action</h2>It's not too hard to create an Action, but it can be difficult to keep track
+document and we stop processing this one.<div class="fixme"><div><b>Fixme: </b>We need more information on when to call which method on the
+Redirector</div></div><div class="section" style="background:none;padding:0;"><h2 style="background:none;padding:0;">Creating the Action<a name="Creating_the_Action"></a></h2></div>It's not too hard to create an Action, but it can be difficult to keep track
of what you are expecting the Sitemap to give you and what you give the Sitemap.
As long as the purpose for your action is small and focused we can keep
everything straight. What we are going to do here is create a "theming" action.
The responsibility of the action is to select the stylesheet for the theme, but
if the source is "xml" then we don't apply a stylesheet at all. It's actually
-not too difficult to perform. First let's set up our Sitemap:<pre><map:choose pattern="**.xhtml"
+not too difficult to perform. First let's set up our Sitemap:<div><pre><map:choose pattern="**.xhtml"
<map:generate src="{1}.xml"/>
<map:act type="theme">
<map:transform src="{theme}2xhtml.xsl"/>
</map:act>
<map:serialize/>
</map:choose/>
-</pre>The plan is to use a parameter passed in to determine the theme. That means
+</pre></div>The plan is to use a parameter passed in to determine the theme. That means
we aren't going to need the Source or SourceResolver parameters to perform our
processing. We will need to extract the request parameter "theme" and interpret
it. If "theme" has the value "xml" we don't do any transformations. If "theme"
doesn't exist, we will provide a default value. And lastly, we will copy the
-request parameter "theme" to the returned Map so it is accessible inside.First the boiler plate code:<pre>import java.util.Map;
+request parameter "theme" to the returned Map so it is accessible inside.First the boiler plate code:<div><pre>import java.util.Map;
import java.util.HashMap;
import org.apache.avalon.framework.parameters.Parameters;
import org.apache.avalon.framework.thread.ThreadSafe;
@@ -765,42 +753,46 @@ public class ThemeAction implements Acti
// .... the contents will be called out specifically below.
}
}
-</pre>Now we can concentrate on the method itself. First things first, we need to
+</pre></div>Now we can concentrate on the method itself. First things first, we need to
get the "theme" request parameter. We do this by accessing the Request object
-from the object model:<pre>Request request = ObjectModelHelper.getRequest( objectModel );
+from the object model:<div><pre>Request request = ObjectModelHelper.getRequest( objectModel );
String theme = request.getParameter("theme");
-</pre><p>Ok, so we have the theme from the request object. Now lets check if it is
-empty and provide a default value if it is empty..</p><pre>if ( null == theme || theme.length() == 0 )
+</pre></div><p>Ok, so we have the theme from the request object. Now lets check if it is
+empty and provide a default value if it is empty..</p><div><pre>if ( null == theme || theme.length() == 0 )
{
theme = DEFAULT_THEME;
}
-</pre><p>Next, let's check to see if the theme is the "xml" theme. We'll do it in a
+</pre></div><p>Next, let's check to see if the theme is the "xml" theme. We'll do it in a
way that does not matter what case the "xml" value is. We return <tt>null</tt>
in this case so that the transformer in the sitemap snippet above does not get
-added to the pipeline.</p><pre>if ( "xml".equalsIgnoreCase(theme.trim()) )
+added to the pipeline.</p><div><pre>if ( "xml".equalsIgnoreCase(theme.trim()) )
{
return null;
}
-</pre><p>Now we can assume that the value we have in the parameter "theme" is the name
+</pre></div><p>Now we can assume that the value we have in the parameter "theme" is the name
of a valid theme. We aren't going to do validation here, that's something you
-can have if you have inclination.</p><pre>Map returnValues = new HashMap();
+can have if you have inclination.</p><div><pre>Map returnValues = new HashMap();
returnValues.put("theme", theme);
return returnValues;
-</pre><p>That's it! We're done. We have an action that does not have to be pooled,
+</pre></div><p>That's it! We're done. We have an action that does not have to be pooled,
selects a theme, provides a default, and does not apply formatting if the theme
-is "xml".</p></div><div class="editUrl"><div><em>Errors and Improvements?</em> If you see any errors or potential improvements in this document please help
- us: <a href="http://cocoon.zones.apache.org/daisy/cdocs/676?branch=1&language=1">View, Edit or comment</a> on the latest development version (registration required).
- </div></div></div>
+is "xml".</p></div></div>
+
</div>
</div>
<!-- end of content -->
<div id="footer">
- <p>©
- 1999-2008
+ <p>Copyright ©
+ 1999-2012
The Apache Software Foundation
+ All Rights Reserved.</p>
+
+ <p>
+ Apache Cocoon, Apache, the Apache feather logo, and the Apache Cocoon project logos are trademarks of The Apache Software Foundation.
+ All other marks mentioned may be trademarks or registered trademarks of their respective owners.
</p>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
Modified: cocoon/site/site/2.2/core-modules/core/2.2/681_1_1.html
URL: http://svn.apache.org/viewvc/cocoon/site/site/2.2/core-modules/core/2.2/681_1_1.html?rev=1329677&r1=1329676&r2=1329677&view=diff
==============================================================================
--- cocoon/site/site/2.2/core-modules/core/2.2/681_1_1.html (original)
+++ cocoon/site/site/2.2/core-modules/core/2.2/681_1_1.html Tue Apr 24 12:39:52 2012
@@ -29,17 +29,13 @@
<head>
<title> Cocoon Core - Creating a Reader
</title>
- <style type="text/css" media="all">
- @import url("./css/maven-base.css");
- @import url("./css/maven-theme.css");
- @import url("./css/site.css");
- </style>
+ <link rel="stylesheet" href="./css/apache-cocoon-thien-maven-skin.min.css" />
<link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
- <script src="./js/getBlank.js" language="javascript" type="text/javascript"></script>
- <meta name="author" content="The Cocoon Community" />
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+ <script src="./js/apache-cocoon-thien-maven-skin.min.js" language="javascript" type="text/javascript"></script>
+ <meta name="author" content="Apache Cocoon Documentation Team" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
- <body>
+ <body onload="javascript:prettyPrint();">
<div id="breadtrail">
<p><a href="http://www.apache.org">Apache</a> » <a href="../../../../">Cocoon</a> »</p>
</div>
@@ -77,7 +73,7 @@
<li><a href="../../../../2.2/core-modules/">Core <span class="pl-version-small">2.2</span></a></li>
<li><a href="../../../../2.2/blocks/">Blocks <span class="pl-version-small">2.2</span></a></li>
<li><a href="../../../../2.2/maven-plugins/">Maven Plugins <span class="pl-version-small">2.2</span></a></li>
- <li><strong><a href="../../../..//3.0/">Cocoon 3.0 <span class="pl-version-small">[alpha]</span></a></em></strong></li>
+ <li><strong><a href="../../../..//3.0/">Cocoon 3.0</a></em></strong></li>
<li><strong><a href="../../../../subprojects/">Subprojects</a></strong></li>
</ul>
</div>
@@ -92,7 +88,7 @@
<ul>
<li >
- <a href="1270_1_1.html">Introduction</a>
+ <a href="index.html">Introduction</a>
</li>
</ul>
</li>
@@ -319,8 +315,6 @@
-
-
<li class='menuCollapse'>
<a href="842_1_1.html">Reference</a>
@@ -608,7 +602,7 @@
</li>
<li >
- <a href="1380_1_1.html">Using Control Flow</a>
+ <a href="1380_1_1.html">Using Control Flow</a>
</li>
</ul>
</li>
@@ -642,11 +636,11 @@
</li>
<li >
- <a href="1399_1_1.html">Logging configuration</a>
+ <a href="1399_1_1.html">Logging Configuration</a>
</li>
<li >
- <a href="1259_1_1.html">Component Configurations</a>
+ <a href="1259_1_1.html">Component Configuration</a>
</li>
<li >
@@ -655,53 +649,47 @@
</ul>
</li>
<li>
- Project Documentation
+ Project Reports
<ul>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li class='menuCollapse'>
- <a href="project-info.html">Project Information</a>
- </li>
+ <li >
+ <a href="changes-report.html">Changes Report</a>
+ </li>
-
-
-
-
-
-
-
-
- <li class='menuCollapse'>
- <a href="project-reports.html">Project Reports</a>
- </li>
+ <li >
+ <a href="apidocs/">JavaDocs</a>
+ </li>
</ul>
</li>
</ul>
<div class="main">
- <div id="contentBody"><div id="bodyText"><h1 class="docTitle">Creating a Reader</h1><h1 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Creating a Reader</h1><p>Readers are the components that send you a stream without the XML processing
+ <!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License. -->
+ <div id="contentBody"><div id="bodyText"><h1 class="docTitle">Creating a Reader</h1><h1>Creating a Reader</h1><p>Readers are the components that send you a stream without the XML processing
that normally happens in a pipeline. Cocoon already comes with some readers out
of the box such as your FileReader which serializes files from your webapp
context. What if you need something that doesn't come from the file system? What
if you need to create content on the fly but the XML processing gets in the way?
That's where the Reader comes to play. Even though there is a DatabaseReader in
the Cocoon's SQL block, we are going to go through the process of creating a
-cacheable database reader here.</p><p>In the sitemap we use the reader we are going to develop like this:</p><pre><map:match pattern="attachment/*">
+cacheable database reader here.</p><p>In the sitemap we use the reader we are going to develop like this:</p><div><pre><map:match pattern="attachment/*">
<map:read type="db-attachments" src="{1}"/>
</map:match>
-</pre><p>The sitemap snippet above matches anything in the attachment path followed by
+</pre></div><p>The sitemap snippet above matches anything in the attachment path followed by
the ID for the attachment. It then passes the ID into the <tt>src</tt>
attribute for our reader. Why not include the nice neat little extension for the
file after the ID? We actually have a very good reason: Microsoft. If you recall
@@ -709,8 +697,8 @@ from the <a href="674_1_1.html">SitemapO
Explorer likes to pretend its smarter than you are. If you have a file extension
on the URL that IE knows, it will ignore your mime-type settings that you
provide. However, if you don't provide any clues then IE has to fall back to
-respecting the standard.</p><h2 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">How Does the Sitemap Treat a Reader?</h2><p>A Sitemap fills two of the core contracts with the Sitemap. It is both a
-SitemapModelComponent and a SitemapOutputComponent. You <em>can</em> make it a
+respecting the standard.</p><div class="section" style="background:none;padding:0;"><h2 style="background:none;padding:0;">How Does the Sitemap Treat a Reader?<a name="How_Does_the_Sitemap_Treat_a_Reader"></a></h2></div><p>A Sitemap fills two of the core contracts with the Sitemap. It is both a
+SitemapModelComponent and a SitemapOutputComponent. You <i>can</i> make it a
CacheableProcessingComponent as well, which will help reduce the load on your
database by avoiding the need to retrieve your attachments all the time. In
fact, unless you have a good reason not to, you should always make your
@@ -723,14 +711,14 @@ is only done for the CachingPipeline. La
<tt>generate()</tt> method to create and send the results back to the client.
It's a one stop shop, and because the Reader is both a SitemapModelComponent and
a SitemapOutputComponent it is the beginning and the end of your pipeline.</p><p>Considering the order in which the processing happens, the sooner you can
-send a response to the Sitemap because of a failure the better.</p><h2 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">ServiceableReader: A Good Start</h2><p>The ServiceableReader provides a good basis for building our database bound
+send a response to the Sitemap because of a failure the better.</p><div class="section" style="background:none;padding:0;"><h2 style="background:none;padding:0;">ServiceableReader: A Good Start<a name="ServiceableReader:_A_Good_Start"></a></h2></div><p>The ServiceableReader provides a good basis for building our database bound
AttachmentReader. The ServiceableReader implements the Recyclable, LogEnabled
and Serviceable interfaces and captures some of the information you will need
for you. We will need these three interfaces to get a reference to the
DataSourceComponent, our Logger, and to clean up our request based artifacts.
You might want to implement the Parameterizable or Configurable interfaces if
you want to decide which particular database we will be hitting in your own
-code. For now, we are going to hard code the information.</p><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">The Skeleton</h3><p>Our skeleton code will look like this:</p><pre>import org.apache.avalon.excalibur.datasource.DataSourceComponent;
+code. For now, we are going to hard code the information.</p><div class="section"><h3>The Skeleton<a name="The_Skeleton"></a></h3><p>Our skeleton code will look like this:</p><div><pre>import org.apache.avalon.excalibur.datasource.DataSourceComponent;
import org.apache.avalon.framework.activity.Disposable;
import org.apache.avalon.framework.parameters.Parameters;
import org.apache.avalon.framework.service.ServiceException;
@@ -772,19 +760,19 @@ public class AttachmentReader extends Se
// ... skip generate code for now
}
}
-</pre><p>If you'll notice we added the Disposable interface to the contract as well.
+</pre></div><p>If you'll notice we added the Disposable interface to the contract as well.
This is so that we can be good citizens and release our components when we are
-done with them. Anything pooled needs to be released.</p><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Getting a Reference to Our DataSourceComponent</h3><p>While it's probably safe to treat your DataSourceComponent and your
+done with them. Anything pooled needs to be released.</p></div><div class="section"><h3>Getting a Reference to Our DataSourceComponent<a name="Getting_a_Reference_to_Our_DataSourceComponent"></a></h3><p>While it's probably safe to treat your DataSourceComponent and your
ServiceManager as singletons in the system, we still want to be responsible.
First things first, let's get our DataSourceComponent and hold on to it as long
as this Reader is around. To do this we will need to add two more class fields:
-</p><pre> private DataSourceComponent datasource;
+</p><div><pre> private DataSourceComponent datasource;
private ServiceSelector dbselector;
-</pre><p>Now we are going to override the <tt>service()</tt> method and implement the
+</pre></div><p>Now we are going to override the <tt>service()</tt> method and implement the
<tt>dispose()</tt> method to get and cleanup after ourselves. First lets start
with getting the DataSourceComponent. Because Cocoon is configured to deal with
multiple databases, you will need to use a ServiceSelector to choose the
-DataSourceComponent corresponding to your desired database.</p><pre> @Override
+DataSourceComponent corresponding to your desired database.</p><div><pre> @Override
public void service(ServiceManager services) throws ServiceException
{
super.service(services);
@@ -792,7 +780,7 @@ DataSourceComponent corresponding to you
dbselector = (ServiceSelector) manager.lookup(DataSourceComponent.ROLE + "Selector");
datasource = (DataSourceComponent) dbselector.select(DB_RESOURCE_NAME);
}
-</pre><div class="note"><div><strong>Note: </strong>The <tt xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">@Override</tt> annotation above is used by the Java
+</pre></div><div class="note"><div><b>Note: </b>The <tt>@Override</tt> annotation above is used by the Java
compiler to ensure that you are overriding a parent class's method. It only
works in Java 5. If you are developing against an earlier version of Java remove
that line so that you can compile the class. That goes for every time you see
@@ -808,27 +796,27 @@ component then we would run out and the
halt waiting for a connection to become available.</p><p>Since we are still dealing with managing the component itself, let's do the
cleanup code next. The Avalon framework uses the <tt>Disposable.dispose()</tt>
callback method to let the component know when it is safe to release all the
-components it is using and perform other cleanup.</p><pre> public void dispose()
+components it is using and perform other cleanup.</p><div><pre> public void dispose()
{
dbselector.release(datasource);
manager.release(dbselector);
datasource = null;
manager = null;
}
-</pre><p>While setting the fields to <tt>null</tt> might not be necessary with modern
+</pre></div><p>While setting the fields to <tt>null</tt> might not be necessary with modern
day garbage collectors, it still doesn't hurt. By releasing those components we
-ensure that Cocoon can shut down nicely and safely when it is time.</p><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Make sure PDFs Work</h3><p>Since we expect to have PDF documents in our database alongside pictures and
+ensure that Cocoon can shut down nicely and safely when it is time.</p></div><div class="section"><h3>Make sure PDFs Work<a name="Make_sure_PDFs_Work"></a></h3><p>Since we expect to have PDF documents in our database alongside pictures and
other types of documents, we need to make sure they display properly. Since the
bug in the IE Acrobat Reader plugin wasn't fixed until version 7 we need to make
sure the content length is returned. There is some overhead with this as Cocoon
has to cache the results to get the content length, but because we are going to
cache it anyway there is little difference on when it gets sent to the cache.
-This is how we do it:</p><pre> @Override
+This is how we do it:</p><div><pre> @Override
public boolean shouldSetContentLength()
{
return true;
}
-</pre><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Setting up for the Read (Cache directives, finding the resource, etc.)</h3><p>In the <tt>setup()</tt> method we need to ask the database for the
+</pre></div></div><div class="section"><h3>Setting up for the Read (Cache directives, finding the resource, etc.)<a name="Setting_up_for_the_Read_Cache_directives_finding_the_resource_etc."></a></h3><p>In the <tt>setup()</tt> method we need to ask the database for the
meta-information about our attachment. You may be curious why we need to do it
in the setup as opposed to the generate phase of the Reader. The answer is
simply this: the sitemap has already asked the Reader for all caching related
@@ -837,11 +825,11 @@ is really simple and it has an ID, a mim
content. We need to get our component and query it. You can never rely on your
connection pooling code to clean up your open statements and resultsets, so we
will have to do that ourselves. Let's add some more class fields to support the
-cache directives and cache the blob reference:</p><pre> private TimeStampValidity m_validity;
+cache directives and cache the blob reference:</p><div><pre> private TimeStampValidity m_validity;
private InputStream m_content;
private String m_mimeType;
-</pre><p>Since our AttachementReader is pooled and recyclable, let's make sure we
-clean these values up when the AttachmentReader is returned to the pool:</p><pre> @Override
+</pre></div><p>Since our AttachementReader is pooled and recyclable, let's make sure we
+clean these values up when the AttachmentReader is returned to the pool:</p><div><pre> @Override
public void recycle()
{
super.recycle();
@@ -850,15 +838,15 @@ clean these values up when the Attachmen
m_validity = null;
m_mimeType = null;
}
-</pre><p>The next code snippet is the content of the setup() method from the code
+</pre></div><p>The next code snippet is the content of the setup() method from the code
skeleton above. Let's break it down to understand what's going on. First we call
the superclass's version of the method so that all expectations of the class
-hold true:</p><pre> super.setup(sourceResolver, objectModel, src, params);
-</pre><p>Next we set up the holders for the connection, statement and resultset so
-that we can clean them up later.</p><pre> Connection con = null;
+hold true:</p><div><pre> super.setup(sourceResolver, objectModel, src, params);
+</pre></div><p>Next we set up the holders for the connection, statement and resultset so
+that we can clean them up later.</p><div><pre> Connection con = null;
ResultSet rs = null;
Statement stm = null;
-</pre><p>Now we have the meat of the method. We get a connection from the
+</pre></div><p>Now we have the meat of the method. We get a connection from the
DataSourceComponent, and for good measure we set the AutoCommit to false. You
can adjust this to your taste, but for a read we really don't need transactions.
There is some standard query code next, and the part I want to point out is how
@@ -867,7 +855,7 @@ depending on whether the record was foun
set the mimeType, validity, and content fields for the class. Otherwise, we
throw <tt>ResourceNotFoundException</tt>. That exception is how Cocoon knows to
differentiate between a 404 (HTTP Resource Not Found) and a 500 (HTTP Server
-Error) error.</p><pre> try
+Error) error.</p><div><pre> try
{
final String sql = "SELECT mimeType, sourceDate, attachmentData FROM attachments" +
" WHERE attachmentId = '" + source + "'";
@@ -888,58 +876,58 @@ Error) error.</p><pre> try
throw new ResourceNotFoundException("Could not find the record");
}
}
-</pre><p>If for some reason we catch a <tt>SQLException</tt> from the database, it is
+</pre></div><p>If for some reason we catch a <tt>SQLException</tt> from the database, it is
certainly not expected so we rethrow it wrapped with a general
-<tt>ProcessingException</tt>.</p><pre> catch (SQLException se)
+<tt>ProcessingException</tt>.</p><div><pre> catch (SQLException se)
{
throw new ProcessingException(se);
}
-</pre><p>Lastly we cleanup our database objects in the finally method. Without that we
+</pre></div><p>Lastly we cleanup our database objects in the finally method. Without that we
run into database server memory leaks as the database keeps resources open for
queries on the server side. Even the big name databases are sensitive to this.
The JDBCDataSourceComponent connection pooling code does cache the resultsets
and statements to make sure they are closed when you close the connection, but
you might want to use a generic J2EEDataSourceComponent which may or may not do
-that for you. Never make assumptions and always clean up after yourself.</p><pre> finally
+that for you. Never make assumptions and always clean up after yourself.</p><div><pre> finally
{
if (rs != null) try{ rs.close(); } catch(SQLException se) {/*ignore*/}
if (stm != null) try{ stm.close(); } catch(SQLException se) {/*ignore*/}
if (con != null) try{ con.close(); } catch(SQLException se) {/*ignore*/}
}
-</pre><p>The setup is done. Now we just need to let the sitemap know what we found.
+</pre></div><p>The setup is done. Now we just need to let the sitemap know what we found.
The first thing is to let the sitemap know what kind of attachment we are
sending. As you recall, we stored that in the class field "m_mimeType", and the
<tt>getMimeType()</tt> method from SitemapOutputComponent informs the sitemap.
-</p><pre> @Override
+</p><div><pre> @Override
public String getMimeType()
{
return m_mimeType;
}
-</pre><p>Now we want to let the sitemap know the last modified timestamp for the
+</pre></div><p>Now we want to let the sitemap know the last modified timestamp for the
attachment. Since we stored this information in the "m_validity" field we will
send the information from that field. There is a problem though: what if the
resource was not found? We might get a NullPointerException if the m_validity
field was never set. Even though the Sitemap shouldn't call this method in the
event that we couldn't find a resource we still don't want to take any chances.
-A properly guarded <tt>getLastModified()</tt> method would be:</p><pre> @Override
+A properly guarded <tt>getLastModified()</tt> method would be:</p><div><pre> @Override
public long getLastModified()
{
return (null == m_validity) ? -1L : m_validity.getTimeStamp();
}
-</pre><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">The Caching Clues</h3><p>Lastly we want to provide the caching information to the CachingPipeline when
+</pre></div></div><div class="section"><h3>The Caching Clues<a name="The_Caching_Clues"></a></h3><p>Lastly we want to provide the caching information to the CachingPipeline when
needed. Since our source is an ID (from <tt><map:read src="{1}"/></tt>) it
-is probably the best cache key for our component. Let's just use it:</p><pre> public Serializable getKey()
+is probably the best cache key for our component. Let's just use it:</p><div><pre> public Serializable getKey()
{
return source;
}
-</pre><p>We stored the TimeStampValidity object when we set up the attachment
+</pre></div><p>We stored the TimeStampValidity object when we set up the attachment
information, so let's just give that back. Alternatively you could use an
ExpiresValidity to completely avoid hits to the database altogether--but for now
-this is good enough.</p><pre> public SourceValidity getValidity()
+this is good enough.</p><div><pre> public SourceValidity getValidity()
{
return m_validity;
}
-</pre><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Sending the Payload</h3><p>All this work was done just so we could send the results back to the client,
+</pre></div></div><div class="section"><h3>Sending the Payload<a name="Sending_the_Payload"></a></h3><p>All this work was done just so we could send the results back to the client,
and now we get to see the code that does it.</p><p>Don't try to read the entire attachment into memory and then
send it on to the user. It isn't necessary and it kills your scalability.
Instead grab little chunks at a time and send it on to the output stream as you
@@ -951,7 +939,7 @@ that the connection isn't closed until t
practically need to worry about the system severing your connection to the
database mid-stream. Try it. Throw a load test at the system just to make sure
I'm not smoking some controlled substances. Nevertheless, without much further
-ado, the code:</p><pre> public void generate() throws IOException, SAXException, ProcessingException
+ado, the code:</p><div><pre> public void generate() throws IOException, SAXException, ProcessingException
{
try
{
@@ -972,7 +960,7 @@ ado, the code:</p><pre> public void g
m_content = null;
}
}
-</pre><p>We close the stream in the finally clause. If there are any exceptions
+</pre></div><p>We close the stream in the finally clause. If there are any exceptions
thrown, they are propogated up without rewrapping them. You may wonder why we
close the <tt>m_content</tt> stream here and in the <tt>recycle()</tt> method
above. The answer is assurance. The <tt>generate()</tt> method is only called
@@ -982,25 +970,29 @@ before the connection with the server is
limits as well, but we don't want to use them if we can avoid it. By including
the call to close the attachment data stream in the <tt>generate()</tt> method,
we shorten the amount of time that there might be resources tied up with the
-stream.</p><h2 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Summary</h2><p>We're done. It seems like we did a lot here, and that's because we did. If we
+stream.</p></div><div class="section" style="background:none;padding:0;"><h2 style="background:none;padding:0;">Summary<a name="Summary"></a></h2></div><p>We're done. It seems like we did a lot here, and that's because we did. If we
simply did direct generation of the data the class would have been simpler. By
incorporating a database into the mix we've covered most of the things you might
be curious about. Things like how to access other components from your
component, how to make sure our component is cacheable, and some real gotchas
that you do want to avoid. The example we have here will be very performant, and
is not too different from Cocoon's DatabaseReader. Of course, by doing it
-ourselves we get to learn a bit more about how things work inside of Cocoon.</p></div><div class="editUrl"><div><em>Errors and Improvements?</em> If you see any errors or potential improvements in this document please help
- us: <a href="http://cocoon.zones.apache.org/daisy/cdocs/681?branch=1&language=1">View, Edit or comment</a> on the latest development version (registration required).
- </div></div></div>
+ourselves we get to learn a bit more about how things work inside of Cocoon.</p></div></div>
+
</div>
</div>
<!-- end of content -->
<div id="footer">
- <p>©
- 1999-2008
+ <p>Copyright ©
+ 1999-2012
The Apache Software Foundation
+ All Rights Reserved.</p>
+
+ <p>
+ Apache Cocoon, Apache, the Apache feather logo, and the Apache Cocoon project logos are trademarks of The Apache Software Foundation.
+ All other marks mentioned may be trademarks or registered trademarks of their respective owners.
</p>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
Modified: cocoon/site/site/2.2/core-modules/core/2.2/688_1_1.html
URL: http://svn.apache.org/viewvc/cocoon/site/site/2.2/core-modules/core/2.2/688_1_1.html?rev=1329677&r1=1329676&r2=1329677&view=diff
==============================================================================
--- cocoon/site/site/2.2/core-modules/core/2.2/688_1_1.html (original)
+++ cocoon/site/site/2.2/core-modules/core/2.2/688_1_1.html Tue Apr 24 12:39:52 2012
@@ -29,17 +29,13 @@
<head>
<title> Cocoon Core - Creating a Generator
</title>
- <style type="text/css" media="all">
- @import url("./css/maven-base.css");
- @import url("./css/maven-theme.css");
- @import url("./css/site.css");
- </style>
+ <link rel="stylesheet" href="./css/apache-cocoon-thien-maven-skin.min.css" />
<link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
- <script src="./js/getBlank.js" language="javascript" type="text/javascript"></script>
- <meta name="author" content="The Cocoon Community" />
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+ <script src="./js/apache-cocoon-thien-maven-skin.min.js" language="javascript" type="text/javascript"></script>
+ <meta name="author" content="Apache Cocoon Documentation Team" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
- <body>
+ <body onload="javascript:prettyPrint();">
<div id="breadtrail">
<p><a href="http://www.apache.org">Apache</a> » <a href="../../../../">Cocoon</a> »</p>
</div>
@@ -77,7 +73,7 @@
<li><a href="../../../../2.2/core-modules/">Core <span class="pl-version-small">2.2</span></a></li>
<li><a href="../../../../2.2/blocks/">Blocks <span class="pl-version-small">2.2</span></a></li>
<li><a href="../../../../2.2/maven-plugins/">Maven Plugins <span class="pl-version-small">2.2</span></a></li>
- <li><strong><a href="../../../..//3.0/">Cocoon 3.0 <span class="pl-version-small">[alpha]</span></a></em></strong></li>
+ <li><strong><a href="../../../..//3.0/">Cocoon 3.0</a></em></strong></li>
<li><strong><a href="../../../../subprojects/">Subprojects</a></strong></li>
</ul>
</div>
@@ -92,7 +88,7 @@
<ul>
<li >
- <a href="1270_1_1.html">Introduction</a>
+ <a href="index.html">Introduction</a>
</li>
</ul>
</li>
@@ -319,8 +315,6 @@
-
-
<li class='menuCollapse'>
<a href="842_1_1.html">Reference</a>
@@ -608,7 +602,7 @@
</li>
<li >
- <a href="1380_1_1.html">Using Control Flow</a>
+ <a href="1380_1_1.html">Using Control Flow</a>
</li>
</ul>
</li>
@@ -642,11 +636,11 @@
</li>
<li >
- <a href="1399_1_1.html">Logging configuration</a>
+ <a href="1399_1_1.html">Logging Configuration</a>
</li>
<li >
- <a href="1259_1_1.html">Component Configurations</a>
+ <a href="1259_1_1.html">Component Configuration</a>
</li>
<li >
@@ -655,43 +649,37 @@
</ul>
</li>
<li>
- Project Documentation
+ Project Reports
<ul>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li class='menuCollapse'>
- <a href="project-info.html">Project Information</a>
- </li>
+ <li >
+ <a href="changes-report.html">Changes Report</a>
+ </li>
-
-
-
-
-
-
-
-
- <li class='menuCollapse'>
- <a href="project-reports.html">Project Reports</a>
- </li>
+ <li >
+ <a href="apidocs/">JavaDocs</a>
+ </li>
</ul>
</li>
</ul>
<div class="main">
- <div id="contentBody"><div id="bodyText"><h1 class="docTitle">Creating a Generator</h1><h1 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Creating a Generator</h1><p>One of the most common types of components to create in Cocoon is to create a
+ <!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License. -->
+ <div id="contentBody"><div id="bodyText"><h1 class="docTitle">Creating a Generator</h1><h1>Creating a Generator</h1><p>One of the most common types of components to create in Cocoon is to create a
Generator. Whether you realize it or not, every time you write an XSP page, you
are creating a Generator. XSP pages do a number of things for you, but there is
a considerable amount of overhead involved with compiling and debugging. After
@@ -707,7 +695,7 @@ environments to develop Java code. Gener
transformers and your serializers, so it makes creating them directly even more
enticing. Cocoon does have some wonderful generators like the
JXTemplateGenerator and others, but we are going to delve into the world of
-creating our own.</p><h2 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">How the Sitemap Treats a Generator</h2><p>In the eyes of the Sitemap, all XML pipelines start with the Generator. By
+creating our own.</p><div class="section" style="background:none;padding:0;"><h2 style="background:none;padding:0;">How the Sitemap Treats a Generator<a name="How_the_Sitemap_Treats_a_Generator"></a></h2></div><p>In the eyes of the Sitemap, all XML pipelines start with the Generator. By
definition, a Generator is the first <a href="689_1_1.html">XMLProducer</a> in the
pipeline. It is the source of all SAX events that the pipeline handles. It is
also a <a href="673_1_1.html">SitemapModelComponent</a>, so it must follow those
@@ -722,7 +710,7 @@ can recreate a SAX stream on demand as a
and then assemble the XML pipeline. After Cocoon assembles the pipeline,
chaining all XMLProducers to XMLConsumers (remember that an XMLPipe is both),
Cocoon will call the <tt>generate()</tt> method on the Generator. That is the
-signal to start producing results, so send out the SAX events and have fun.</p><h2 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Building our Own Generator</h2><p>We are going to keep things easy for our generator. As usual, we will make
+signal to start producing results, so send out the SAX events and have fun.</p><div class="section" style="background:none;padding:0;"><h2 style="background:none;padding:0;">Building our Own Generator<a name="Building_our_Own_Generator"></a></h2></div><p>We are going to keep things easy for our generator. As usual, we will make
the results cacheable because that is just good policy. In the spirit of trying
to be useful, as well as trying to keep things manageably simple, let's create a
BeanGenerator. The XML generated will be very simple, utilizing the JavaBean
@@ -740,16 +728,16 @@ each other you will have an infinite loo
of what we are trying to do, and that is generally bad design anyway so we won't
worry too much about it. Yes there is overhead with the beans Introspector but
we are writing for the general case.</p><p>To set up our generator, we need to use a serializer that shows us what the
-results are, so we will set up our sitemap to use our generator like this:</p><pre><map:match pattern="bean/*.xml">
+results are, so we will set up our sitemap to use our generator like this:</p><div><pre><map:match pattern="bean/*.xml">
<map:generate type="bean" src="{1}"/>
<map:serialize type="xml"/>
</map:match>
-</pre><p>Even though it is generally bad design to have a static anything in a Cocoon
+</pre></div><p>Even though it is generally bad design to have a static anything in a Cocoon
application we are going to use a helper class called "BeanPool" with the get()
and put() methods that are familiar from the HashMap. So that it is easier for
you to change the behavior of the BeanGenerator, we will provide a nice
protected method called <tt>findBean()</tt> which is meant to be overridden with
-something more robust.</p><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">The Skeleton</h3><p>Our skeleton code will look like this:</p><pre>import org.apache.avalon.framework.parameters.Parameters;
+something more robust.</p><div class="section"><h3>The Skeleton<a name="The_Skeleton"></a></h3><p>Our skeleton code will look like this:</p><div><pre>import org.apache.avalon.framework.parameters.Parameters;
import org.apache.cocoon.ProcessingException;
import org.apache.cocoon.ResourceNotFoundException;
import org.apache.cocoon.caching.CacheableProcessingComponent;
@@ -792,18 +780,18 @@ public class BeanGenerator extends Abstr
// ... skip other methods later.
}
-</pre><p>As you can see, we have our simplified <tt>findBean()</tt> method which can
+</pre></div><p>As you can see, we have our simplified <tt>findBean()</tt> method which can
be replaced with something more robust later. All you need to do to populate the
BeanPool is to call the <tt>BeanPool.put(String key, Object bean)</tt> method
-from somewhere else.</p><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Setting up to Generate</h3><p>Before we can generate anything let's start with the <tt>setup()</tt> code:
-</p><pre> super.setup( sourceResolver, model, src, params );
+from somewhere else.</p></div><div class="section"><h3>Setting up to Generate<a name="Setting_up_to_Generate"></a></h3><p>Before we can generate anything let's start with the <tt>setup()</tt> code:
+</p><div><pre> super.setup( sourceResolver, model, src, params );
m_bean = findBean(src);
if ( null == m_bean )
{
throw new ResourceNotFoundException(String.format("Could not find bean: %s", source));
}
-</pre><p>What we did is call the setup method from AbstractGenerator which populates
+</pre></div><p>What we did is call the setup method from AbstractGenerator which populates
some class fields for us (like the <tt>source</tt> field), then we tried to find
the bean using the key provided. If the bean is <tt>null</tt>, then we follow
the principle of least surprise and throw the <tt>ResourceNotFoundException
@@ -812,34 +800,34 @@ of generating some lame 500 server error
this particular Generator. Oh, and since we do have the <tt>m_bean</tt> field
populated we do want to clean up after ourselves properly. Let's add the
recycle() method from Recyclable so that we don't give an old result when a bean
-can't be found:</p><pre> @Override
+can't be found:</p><div><pre> @Override
public void recycle()
{
super.recycle();
m_bean = null;
}
-</pre><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">The Caching Clues</h3><p>We are going to make the caching for the BeanGenerator really simple. Ideally
+</pre></div></div><div class="section"><h3>The Caching Clues<a name="The_Caching_Clues"></a></h3><p>We are going to make the caching for the BeanGenerator really simple. Ideally
we would have something that listens for changes and invalidates the
SourceValidity if there is a change to the bean we are rendering. Unfortunately
that is outside our scope, and we will set up the key so that it never expires
unless it is done manually. Since we are using the source property from the
-Sitemap as our key, let's just use that as our cache key:</p><pre> public Serializable getKey()
+Sitemap as our key, let's just use that as our cache key:</p><div><pre> public Serializable getKey()
{
return source;
}
-</pre><p>And lastly, our brain-dead validity implementation:</p><pre> public SourceValidity getValidity()
+</pre></div><p>And lastly, our brain-dead validity implementation:</p><div><pre> public SourceValidity getValidity()
{
return NOPValidity.SHARED_INSTANCE;
}
-</pre><p>Using this approach is a bit naive in the sense that it is very possible that
+</pre></div><p>Using this approach is a bit naive in the sense that it is very possible that
the beans will have changed. We could use an ExpiresValidity instead to make
things a bit more resilient to change, but that is an excersize for you, dear
-reader.</p><h3 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Generating Output</h3><p>Now that we have our bean, we are ready to generate our output. The
+reader.</p></div><div class="section"><h3>Generating Output<a name="Generating_Output"></a></h3><p>Now that we have our bean, we are ready to generate our output. The
AbstractXMLProducer base class (AbstractGenerator inherits from that) stores the
target in a class field named <tt>contentHandler</tt>. Simple enough. We'll
start by implementing the generate() method, but we already know we need to
handle beans differently than the standard String and primitive types. So let's
-stub out the method we will use for recursive serialization. Here we go:</p><pre> public void generate()
+stub out the method we will use for recursive serialization. Here we go:</p><div><pre> public void generate()
{
contentHandler.startDocument();
@@ -847,9 +835,9 @@ stub out the method we will use for recu
contentHandler.endDocument();
}
-</pre><p>All we did was call the start and end document for the whole XML Document.
+</pre></div><p>All we did was call the start and end document for the whole XML Document.
That is enough for a basic XML document with no content. The
-<tt>renderBean()</tt> method is where the magic happens:</p><pre> public void renderBean(String root, Object bean)
+<tt>renderBean()</tt> method is where the magic happens:</p><div><pre> public void renderBean(String root, Object bean)
{
String namespace = String.format( "java:%s", bean.getClass().getName() );
qName = String.format( "%s:%s", root,root );
@@ -868,13 +856,13 @@ That is enough for a basic XML document
contentHandler.endElement( namespace, root, qName );
contentHandler.endNamespace( root );
}
-</pre><p>So far we created the root element and started iterating over the properties.
+</pre></div><p>So far we created the root element and started iterating over the properties.
Our root element consists of a namespace a name and a qName. Our implementation
is using the <tt>source</tt> for the initial root element so as long as we never
have any special characters like a colon (':') we should be OK. Without going
through the individual properties, a java.awt.Dimension object with a source of
-"dim" will be redered like this:</p><pre><dim:dim xmlns:dim="java:java.awt.Dimension"/>
-</pre><p>Now for the properties:</p><pre> private void renderProperty( String namespace, String root, PropertyDescriptor property )
+"dim" will be redered like this:</p><div><pre><dim:dim xmlns:dim="java:java.awt.Dimension"/>
+</pre></div><p>Now for the properties:</p><div><pre> private void renderProperty( String namespace, String root, PropertyDescriptor property )
{
Method reader = property.getReadMethod();
Class<?> type = property.getPropertyType();
@@ -901,7 +889,7 @@ through the individual properties, a jav
contentHandler.endElement( namespace, name, qName );
}
}
-</pre><p>This method is a little more complex in that we have to figure out if the
+</pre></div><p>This method is a little more complex in that we have to figure out if the
property is readable, and is a type we can handle. In this case, we don't read
indexed properties (if you want to support that, you'll have to extend this code
to do that), and we don't read any properties where there is no read method. We
@@ -910,11 +898,11 @@ the value, and then we call the start an
of the calls, we determine if the item is a bean, and if so we render the bean
using the renderBean method (the recursive aspect); otherwise we render the
content as text as long as it is not null. Once the <tt>isBean()</tt> method is
-implemented, our Dimension example above will produce the following result:</p><pre><dim:dim xmlns:dim="java:java.awt.Dimension">
+implemented, our Dimension example above will produce the following result:</p><div><pre><dim:dim xmlns:dim="java:java.awt.Dimension">
<dim:width>32</dim:width>
<dim:height>32</dim:height>
</dim:dim>
-</pre><p>Ok, now for the last method to determine if a value is a bean or not:</p><pre> private boolean isBean(Class<?> klass)
+</pre></div><p>Ok, now for the last method to determine if a value is a bean or not:</p><div><pre> private boolean isBean(Class<?> klass)
{
if ( Boolean.TYPE.equals( klass ) ) return false;
if ( Byte.TYPE.equals( klass ) ) return false;
@@ -929,9 +917,9 @@ implemented, our Dimension example above
return true;
}
-</pre><p>The isBean() method will treat all primitives, Strings, Dates, and anything
+</pre></div><p>The isBean() method will treat all primitives, Strings, Dates, and anything
in "java.lang" as value objects. This captures the boxed versions of primitives
-as well as the unboxed versions. Everything else is treated as a bean.</p><h2 xmlns:ns="http://outerx.org/daisy/1.0" xmlns:p="http://outerx.org/daisy/1.0#publisher">Summary</h2><p>Generators aren't too difficult to write, but the tricky parts are there due
+as well as the unboxed versions. Everything else is treated as a bean.</p></div><div class="section" style="background:none;padding:0;"><h2 style="background:none;padding:0;">Summary<a name="Summary"></a></h2></div><p>Generators aren't too difficult to write, but the tricky parts are there due
to namespaces. As long as you are familiar with the SAX API you should not have
any problems. The complexity in our generator is really from the reflection
logic used to discover how to render an object. You might ask why we didn't use
@@ -939,7 +927,7 @@ the XMLEncoder in the java.beans package
that the facility is based on IO streams, and can't be easily adapted to XML
streams. At any rate, we have something that can work with a wide range of
classes. Our XML is easy to understand. Here is a snippet from a more complex
-example:</p><pre><line:line xmlns:line="java:com.mycompany.shapes.Line">
+example:</p><div><pre><line:line xmlns:line="java:com.mycompany.shapes.Line">
<line:name>This line has a name</line:name>
<line:topLeft>
<topLeft:topLeft xmlns:topLeft="java:java.awt.Point">
@@ -954,22 +942,26 @@ example:</p><pre><line:line xmlns:lin
</bottomRight:topLeft>
</bottomRight:topLeft>
</line:line>
-</pre><p>Our theoretical line object contained a name and two java.awt.Point objects
+</pre></div><p>Our theoretical line object contained a name and two java.awt.Point objects
which in turn had an x and a y property. It is easier to understand when you
have domain specific beans that are backed to a database. Nevertheless, we have
a generator that satisfies a general purpose and can be extended later on to
-support our needs as they change.</p></div><div class="editUrl"><div><em>Errors and Improvements?</em> If you see any errors or potential improvements in this document please help
- us: <a href="http://cocoon.zones.apache.org/daisy/cdocs/688?branch=1&language=1">View, Edit or comment</a> on the latest development version (registration required).
- </div></div></div>
+support our needs as they change.</p></div></div>
+
</div>
</div>
<!-- end of content -->
<div id="footer">
- <p>©
- 1999-2008
+ <p>Copyright ©
+ 1999-2012
The Apache Software Foundation
+ All Rights Reserved.</p>
+
+ <p>
+ Apache Cocoon, Apache, the Apache feather logo, and the Apache Cocoon project logos are trademarks of The Apache Software Foundation.
+ All other marks mentioned may be trademarks or registered trademarks of their respective owners.
</p>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">