Return-Path: Delivered-To: apmail-cocoon-docs-archive@www.apache.org Received: (qmail 12199 invoked from network); 25 Aug 2005 18:05:20 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 25 Aug 2005 18:05:20 -0000 Received: (qmail 55581 invoked by uid 500); 25 Aug 2005 18:05:14 -0000 Delivered-To: apmail-cocoon-docs-archive@cocoon.apache.org Received: (qmail 55533 invoked by uid 500); 25 Aug 2005 18:05:14 -0000 Mailing-List: contact docs-help@cocoon.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: docs@cocoon.apache.org List-Id: Delivered-To: mailing list docs@cocoon.apache.org Received: (qmail 55508 invoked by uid 99); 25 Aug 2005 18:05:14 -0000 X-ASF-Spam-Status: No, hits=0.2 required=10.0 tests=NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [207.7.158.203] (HELO cocoon.zones.apache.org) (207.7.158.203) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 25 Aug 2005 11:05:13 -0700 Message-ID: <24074573.1124992959792.JavaMail.daisy@cocoon.zones.apache.org> Date: Thu, 25 Aug 2005 18:02:39 +0000 (GMT+00:00) From: daisy@cocoon.zones.apache.org To: docs@cocoon.apache.org Subject: [DAISY] Updated: Creating a Reader Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N A document has been updated: http://cocoon.zones.apache.org/daisy/documentation/681.html Document ID: 681 Branch: main Language: default Name: Creating a Reader (unchanged) Document Type: Document (unchanged) Updated on: 8/25/05 6:02:21 PM Updated by: Berin Loritsch A new version has been created, state: publish Parts =3D=3D=3D=3D=3D Content ------- This part has been updated. Mime type: text/xml (unchanged) File name: (unchanged) Size: 5976 bytes (previous version: 5967 bytes) Content diff: (3 equal lines skipped)

Creating a Reader

=20

Readers are the components that send you a stream without the XML pr= ocessing --- that normally happens in a pipeline.=C2=A0 Cocoon already comes with so= me readers out +++ that normally happens in a pipeline. Cocoon already comes with some rea= ders out of the box such as your FileReader which serializes files from your web= app --- context.=C2=A0 What if you need something that doesn't come from the fi= le system?=C2=A0 --- What if you need to create content on the fly but the XML processing ge= ts in the --- way?=C2=A0 That's where the Reader comes to play.=C2=A0 Even though the= re is a --- DatabaseReader in the Cocoon's SQL block, we are going to go through th= e process --- of creating a cacheable database reader here.

+++ context. What if you need something that doesn't come from the file sys= tem? 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 DatabaseR= eader in +++ the Cocoon's SQL block, we are going to go through the process of creat= ing a +++ cacheable database reader here.

=20

In the sitemap we use the reader we are going to develop like this:<= /p> =20 (3 equal lines skipped) =20

The sitemap snippet above matches anything in the attachment path fo= llowed by --- the ID for the attachment.=C2=A0 It then passes the ID into the src= --- attribute for our reader.=C2=A0 Why not include the nice neat little ex= tension for --- the file after the ID?=C2=A0 We actually have a very good reason: Micro= soft.=C2=A0 If you --- recall from the SitemapOutputComponent Contracts<= /a> page, --- Internet Explorer likes to pretend its smarter than you are.=C2=A0 If y= ou have a file --- extension on the URL that IE knows, it will ignore your mime-type setti= ngs that --- you provide.=C2=A0 However, if you don't provide any clues then IE has = to fall back --- to respecting the standard.

+++ the ID for the attachment. It then passes the ID into the src +++ attribute for our reader. Why not include the nice neat little extensio= n for the +++ file after the ID? We actually have a very good reason: Microsoft. If y= ou recall +++ from the SitemapOutputComponent Contracts pag= e, Internet +++ 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 y= ou +++ provide. However, if you don't provide any clues then IE has to fall ba= ck to +++ respecting the standard.

=20

How Does the Sitemap Treat a Reader?

=20 ---

A Sitemap fills two of the core contracts with the Sitemap.=C2=A0 It= is both a --- SitemapModelComponent and a SitemapOutputComponent.=C2=A0 You can make it a +++

A Sitemap fills two of the core contracts with the Sitemap. It is bo= th a +++ SitemapModelComponent and a SitemapOutputComponent. You can ma= ke it a CacheableProcessingComponent as well, which will help reduce the load o= n your --- database by avoiding the need to retrieve your attachments all the time= .=C2=A0 In +++ 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 --- components cacheable just for the flexibility in deployment later.=C2= =A0 I recommend +++ components cacheable just for the flexibility in deployment later. I re= commend you read the articles on the core contracts to understand where to find= the resources you need.

=20 ---

A sitemap will fulfill all its core contracts first.=C2=A0 It will t= hen query the --- reader using the getLastModified() method.=C2=A0 The results o= f that method +++

A sitemap will fulfill all its core contracts first. It will then qu= ery the +++ reader using the getLastModified() method. The results of that= method will be added to the response header for browser caching purposes--alth= ough it --- is only done for the CachingPipeline.=C2=A0 Lastly, the sitemap will ca= ll the --- generate() method to create and send the results back to the c= lient.=C2=A0 +++ is only done for the CachingPipeline. Lastly, the sitemap will call the +++ generate() method to create and send the results back to the c= lient. It's a one stop shop, and because the Reader is both a SitemapModelComp= onent and a SitemapOutputComponent it is the beginning and the end of your pipeli= ne.

=20 (3 equal lines skipped)

ServiceableReader: A Good Start

=20

The ServiceableReader provides a good basis for building our databas= e bound --- AttachmentReader.=C2=A0 The ServiceableReader implements the Recyclable= , LogEnabled +++ AttachmentReader. The ServiceableReader implements the Recyclable, LogE= nabled and Serviceable interfaces and captures some of the information you wil= l need --- for you.=C2=A0 We will need these three interfaces to get a reference t= o the --- DataSourceComponent, our Logger, and to clean up our request based arti= facts.=C2=A0 +++ for you. We will need these three interfaces to get a reference to the +++ DataSourceComponent, our Logger, and to clean up our request based arti= facts. You might want to implement the Parameterizable or Configurable interfa= ces if you want to decide which particular database we will be hitting in your= own --- code.=C2=A0 For now, we are going to hard code the information.

+++ code. For now, we are going to hard code the information.

=20

The Skeleton

=20 (30 equal lines skipped) // ... skip many methods covered later =20 public void setup( SourceResolver sourceResolver, Map model, String= src, Parameters params ) --- =C2=A0throws IOException, ProcessingException, SAXException +++ throws IOException, ProcessingException, SAXException { // ... skip setup code for now } (5 equal lines skipped) } =20 ---

If you'll notice we added the Disposable interface to the contract a= s well.=C2=A0 +++

If you'll notice we added the Disposable interface to the contract a= s well. This is so that we can be good citizens and release our components when= we are --- done with them.=C2=A0 Anything pooled needs to be released.=C2=A0 While= it's probably safe --- to treat your DataSourceComponent and your ServiceManager as singletons= in the --- system, we still want to be responsible.=C2=A0 First things first, let'= s get our --- DataSourceComponent and hold on to it as long as this Reader is around.= =C2=A0 To do --- this we will need to add two more class fields:

+++ done with them. Anything pooled needs to be released.

=20 +++

Getting a Reference to Our DataSourceComponent

+++=20 +++

While it's probably safe to treat your DataSourceComponent and your +++ ServiceManager as singletons in the system, we still want to be respons= ible. +++ 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: +++

+++=20 
    private DataSourceComponent datasource;
        private ServiceSelector dbselector;
(6 equal lines skipped) Fields =3D=3D=3D=3D=3D=3D no changes Links =3D=3D=3D=3D=3D no changes Custom Fields =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D no changes Collections =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D no changes