Taming Cocoon

1
Taming Cocoon

• ApacheCon Europe 2005
• Gianugo Rabellino

2
Agenda

• Introduction
• Installing Cocoon
• Dissecting Cocoon
• Management and configuration
• A sitemap tour
• Cocoon components and blocks
• Understanding continuations and flow
• Dealing with forms
• Patterns, best practices, pitfalls

3
Introduction web developer nightmares

• out.println(lttable border\0\gt\n\tlttrgt\n\t\t
  
• lttd align\left\gtltfont size\1\gt
• request.getParameter(lousyjob)
• Does your boss know you\'re typing HTML?
  
• lt/tdgt\n\tlt/trgt\nlt/tablegt\n)

4
Nightmare managing HTML

• Your IDE can't deal with HTML
• Dreamweaver can't deal with business logic
• Period.
• Oh, and JSPs suck. Big time.
• Separate concerns - Edsger Dijkstra - 1974

5
Nightmare handling state

• HTTP is stateless (did you notice already?)
• Where am I now?
• Restart required
• Sessions overpopulated mess of dictionaries

6
Nightmare managing user input

• Validation hell
• Conversion ordeal
• Binding torture
• The infamous Back button, oh my!

7
There has to be a better way
Never let a man do what a machine can do for
him Blaise Pascal
8
Apache Cocoon

• A fast-paced overview

9
Apache Cocoon facts and figures

• Origins
• Started by the Italian student Stefano Mazzocchi
• Redesign of Apache.org
• Frustrated by the limitations of HTML
• Wanted to use emerging technologies (XML/XSL)
• Today
• Now one of the most important Apache projects
• Incorporates technologies from various project
• Just under 2000 registered on all mailing lists
• Includes major companies such as HP, IBM

10
Tucking web devs in, kissing them goodnight
11
10.000ft overview
12
Key Cocoon concepts

• URI space decoupling
• Componentized resource assembling
• Datasource connections and decoupling
• Stateful applications

13
And their implementation...

• URI space decoupling
• Sitemap
• Componentized resource assembling
• Pipelines
• Datasource connections and decoupling
• Source interface and implementations (file, URL,
  database, WebDAV, XMLDB...)
• Stateful applications
• Web continuations

14
URI space decoupling the sitemap

• Think ltservlet-mappinggt on steroids
• Pattern freaks think FrontController
• Uses pluggable algorithms
• Wildcard
• Regexp
• Your own
• Matching the whole HTTP environment
• Request URI/parameters/attributes
• Session attributes
• Cookies, context, etc...
• Welcome to the sitemap

15
A sitemap example

• ltmapmatch pattern"news/" type"wildcard"gt
• ltmapgenerate src"newsfeeds/1.xml"
  type"file"/gt
• ltmaptransform src"news2html.xsl"
  type"xslt"/gt
• ltmapserialize type"html"/gt
• lt/mapmatchgt
• ltmapmatch pattern"products/"
  type"wildcard"gt
• ltmapgenerate src"products/infos/product_
  1.xml" type"file"/gt
• ltmaptransform src"products2html.xsl"
  type"xslt"/gt
• ltmapserialize type"html"/gt
• lt/mapmatchgt

16
Resource assembling the pipeline

• Task find the total number of unique hosts
  visiting the home page of your site
• Windows solution
• include ltstdlib.hgt
• ...
• Unix solution
• grep index.html access.log awk 'print 2 '
  sort uniq wc -l
• Welcome to the pipeline specialized components
  glued together

17
The Cocoon pipeline

• Two simple rules
• Data stream is based on SAX events
• Pipelines start with one Generator (and only
  one), have 0-n Transformers, end with one (and
  only one) Serializer
• Generators adapters from the outside world to
  SAX events
• Transformers SAX event manglers
• Serializers adapters from SAX events to the
  outside world

18
A pipeline example
ltmapmatch pattern".html"gt ltmapgenerate
srcxdocs/1.xml"/gt ltmaptransform
srcstyle/xdocs2html.xsl/gt ltmapserialize/gt lt/
mapmatchgt
19
Datasource virtualization

• Virtualization layer over stream-based data
  sources
• Provides a java.io.File like interface for a
  number of data sources
• Think URLs on steroids

20
The Source interface
21
A datasource example

• ltmapmatch pattern"news/" type"wildcard"gt
• ltmapgenerate src"webdav//repo/newsfeeds/1.
  xml" type"file"/gt
• ltmaptransform src"xmldb//localhost/db/news2h
  tml.xsl" type"xslt"/gt
• ltmapserialize type"html"/gt
• lt/mapmatchgt
• ltmapmatch pattern"products/" type"wildcard"gt
• ltmapgenerate src"cocoon//products/infos/prod
  uct_1.xml"/gt
• ltmaptransform src"resource//products2html.xs
  l" type"xslt"/gt
• ltmapserialize type"html"/gt
• lt/mapmatchgt

22
Summing it up

• The sitemap decouples URI space from physical
  resources
• The pipeline decouples results from the way
  they're built
• XML decouples content from presentation
• The source abstraction decouples data sources
  from physical locations
• Result full Separation of Concerns
• (and you aint seen nothing yet...)

23
Web Continuations

• The next revolution

24
Web applications are easy!
25
But wait, this is stateless HTTP

• Webapps are finite state machines
• Upon every click, processing starts from the
  beginning
• Again, and again, and again

26
A typical web application clutter
27
What are continuations?

• A continuation is an entire set of closures that
  make up a point of execution
• A continuation is an object that, for a given
  point in your program, contains a snapshot of the
  stack trace, including all the local variables,
  and the program counter
• Hmmm... so what?

28
A flowscript example where the magic happens
29
What are continuations, again?

• Contents of a continuation
• Stack of function calls
• Value of local variables
• ? Most often a lightweight object
• ? Creating a continuation does not halt a thread
  !!
• A continuation object is associated with a unique
  identifier available to the view
• ? Later used to "resurrect" it

30
Flowscript example, revisited
31
Continuations tree
Don't fear the Back button anymore!
32
Summing it up

• Continuations give control back to the server
• ? We always know "where" the browser is
• Allow sophisticated flow screens
• ? No need for state automata
• Increase security and robustness
• ? Forbids direct access to form submission URLs
• ? Handling of "back" and "new window"

33
A word about forms

• Managing user input

34
Cocoon Forms nightmares solved!

• MVC based form framework
• Provides
• Strongly-typed data a date field is a
  java.util.Date. Automatically.
• Validation declarative. Handled for you.
  Automatically.
• Binding to objects (EJB, POJOs...) or to XML,
  your choice. Automatically.

35
Cocoon Forms, a functional view

• Separation of Concerns in forms
• Model data typing, validation rules
• View widget presentation
• selections could be drop down lists or checkboxes
  
• Controller
• flowscript (continuations based)
• custom actions (à la Struts) not recommended
• Data binding
• declarative
• JXPath based

36
Cocoon Forms a rich framework

• Powerful widget library
• Fields, aggregated fields, dates, selectors,
  trees and repeaters
• AJAX compliant infrastructure
• Boosts perceived performance
• Integrated add-ons
• HTML editor
• calendar pop-ups
• dynamic double selection lists

37
Summing it up RAD development

• Configure, don't code
• Continuations make webapp development a breeze
• Powerful form frameworks ease managing user input
• Separation of Concerns brings maintainability
• ... and they lived happily ever after.

38
Installing Cocoon

• Finding your way through compilation and blocks

39
Downloading Cocoon

• http//cocoon.apache.org
• Subversion for the latest version
• http//svn.apache.org/repos/asf/cocoon/branches/
  BRANCH_2.1.X
• http//svn.apache.org/repos/asf/cocoon/trunk
• or even WebDAV

40
Preparing Cocoon

• Task list
• Edit local.build.properties
• Exclude unneeded and heavy tasks (e.g. javadocs /
  documentation)
• Edit local.blocks.properties
• Beware of dependencies
• All done, now run
• ./build.sh (Unix)
• C\gt build.bat (Windows)

41
Testing the install

• Embedded Jetty
• Run
• ./cocoon.sh servlet (Unix)
• C\gt cocoon.bat servlet (Windows)
• Point your browser to http//localhost8888/
• Other servlet engines
• Run
• ./build.sh war (Unix)
• C\gt build.bat war (Windows)
• Deploy dist/cocoon.war

42
Beware the classloader

• Cocoon uses its own version of Rhino (Javascript
  engine)
• Might clash with vendor-provided ones (e.g.
  Websphere/BEA)
• Make sure that your appserver is configured to
  run Cocoon in an isolated classloader (as per
  servlet spec)
• ask your vendor to fix his bug if it doesnt work
• If it doesnt work, use the paranoid block and
  the ParanoidCocoonServlet (but you shouldnt)
• Mind redirects on WebSphere!

43
Eclipse integration

• Run
• ./build.sh eclipse-project (Unix)
• C\gt build.bat eclipse-project (Windows)
• Inside Eclipse
• New Java Project
• Navigate to COCOON_HOME
• Your project will appear automagically!

44
Files you want to know

• Main sitemap
• COCOON_HOME/build/webapp/sitemap.xmap
• Log configuration
• COCOON_HOME/build/webapp/WEB-INF/logkit.xconf
• Component configuration
• COCOON_HOME/build/webapp/WEB-INF/cocoon.xconf
• Mount table
• COCOON_HOME/mount-table.xml

45
Management and configuration

• Handling Cocoon in production

46
Configuring Cocoon

• Web Application Configuration
• Cocoon runs as a servlet
• Configuration controlled by web.xml
• Find it in the WEB-INF directory
• Most important entry
• Name and location of the actual configuration
  file
• Default WEB-INF/cocoon.xconf
• lt!--
• This parameter points to the main configuration
  file for Cocoon. Note that the path is specified
  in absolute notation but it will be resolved
  relative to the servlets webapp context path
• --gt
• ltinit-paramgt
• ltparam-namegtconfigurationslt/param-namegt
• ltparam-valuegt/WEB-INF/cocoon.xconflt/param-valuegt
  
• lt/init-paramgt

47
Configuring Cocoon

• cocoon.xconf
• XML format
• Contains Avalon component configuration
• But not (!!) the sitemap components
• They are in the sitemap
• cocoon.xconf rarely needs changing
• Moving from test to production
• Replacing the XML parser

48
Configuring Cocoon

• cocoon.xconf
• lt?xml version"1.0"?gt
• ltcocoon version"2.0"gt
• ltparser class"org.apache.cocoon.components.parser
  .XercesParser"/gt
• lthsqldb-server class"org.apache.cocoon.components
  .hsqldb.ServerImpl"
• pool-max"1" pool-min"1"gt
• ltparameter name"port" value"9002"/gt
• ltparameter name"silent" value"true"/gt
• ltparameter name"trace" value"false"/gt
• lt/hsqldb-servergt...
• lt/cocoongt

49
Configuring Cocoon

• cocoon.xconf
• No namespace
• Each component defined inside ltcocoongt
• Logical names matched to implementations
• e.g. parser hsqldb-server
• Configuration using ltparametergt
• Contains name-value pairs
• pool-min and pool-max
• We will look at those later (pooling)

50
Configuring Cocoon

• cocoon.xconf
• Another important piece of information
• Location and name of the sitemap
• ltsitemap file"context//sitemap.xmap"
• check-reload"yes"/gt
• Reloading
• Triggers on incoming request
• Synchronous
• New sitemap will be generated and then handles
  the request
• What do you do if an error occurs ............

51
Configuring Cocoon

• LogKit Configuration
• Each component in Cocoon logs using LogKit
• There are five log levels
• DEBUG
• INFO
• WARNING
• ERROR
• FATAL_ERROR
• In testing DEBUG
• In production ERROR or FATAL_ERROR
• Location of the LogKit configuration file
• Is in the web.xml
• ltinit-paramgt
• ltparam-namegtlogkit-configlt/param-namegt
• ltparam-valuegt/WEB-INF/logkit.xconflt/param-valuegt
  
• lt/init-paramgt

52
Configuring Cocoon

• LogKit Configuration
• Consists of several parts
• Factories for logging targets
• Implementations are not "hard-wired"
• Defines components that are to receive the log
  messages
• Targets
• Configured with Factory
• And file name, output format, size/rotation
  information
• Categories
• Actual "receiver" of the log messages
• Configured with (multiple) targets
• And log level

53
Configuring Cocoon

• LogKit Configuration

ltlogkitgt ltfactoriesgt ltfactory
type"cocoon" class"org.apache.cocoon.util.log.Co
coonTargetFactory"/gt lt/factoriesgt   lttargetsgt
ltcocoon id"cocoon"gt ltfilenamegtcontext-r
oot/WEB-INF/logs/cocoon.loglt/filenamegt
ltformat type"cocoon"gt 7.7priority
time 8.8category (uri)
thread/classshort
message\nthrowable lt/formatgt
ltappendgttruelt/appendgt ltrotation
type"revolving" init"1" max"4"gt ltorgt
ltsizegt100mlt/sizegt
lttimegt010000lt/timegt lt/orgt
lt/rotationgt lt/cocoongt ltfilter/gt
lt/targetsgt   ltcategoriesgt ltcategory
name"cocoon" log-level"DEBUG"gt
ltlog-target id-ref"cocoon"/gt ltlog-target
id-ref"filter"/gt lt/categorygt
lt/categoriesgt lt/logkitgt
54
Configuring Cocoon

• LogKit Configuration
• (Normally) No need to change the setting
• Apart from log-levels
• Not reflected automatically
• Touch cocoon.xconf
• DEBUG logfiles can become very large
• Hard drives have a limited capacity ?
• And slow performance down
• Default level ERROR for all categories

55
Dissecting Cocoon

• A sitemap tour

56
Cocoon anatomy
57
Cocoon physiology
58
The sitemap disemboweled

• The sitemap contains
• Component definitions and configurations
• Views
• Resources
• Action sets
• Flow
• Pipelines
• all neatly packaged as a namespaced XML file
• ltmapsitemap xmlnsmap"http//xml.apache.org/coco
  on/sitemap/1.0"gt
• ltmapcomponents/gt
• ltmapviews/gt
• ltmapresources/gt
• ltmapaction-sets/gt
• ltmapflow/gt
• ltmappipelines/gt
• lt/mapsitemapgt

59
Sitemap components

• Configured as children of the ltmapcomponentsgt
  section
• Contains
• Generators
• Transformers
• Serializers
• Readers
• Matchers
• Selectors
• Actions
• Pipes
• and their configuration
• Each section declaration can have a default
  component

60
Sitemap components Tour

• Generator, Transformers and Serializers are
  typical Cocoon components for pipelines
• Readers are used for binary resources
• Think of a collapsed Generator and Serializer
• Matchers are used to route requests
• Selectors implement branching (if then else)
  logic
• Actions implement business logic based switching
  (old fashioned, flow is now the preferred way)
• Pipes define different pipeline implementation
  (which differ mainly for caching policies)
• Examples will follow

61
A word about Actions

• Actions are reusable snippets of business logic
• Actions wrap pipeline snippets
• Actions can return either
• null the pipeline snippet is skipped
• A Map containing business values, which can be
  reused in the pipeline snippet
• ltmapact type"clear-cache"gtltmapgenerate
  src"status" type"status"/gtltmaptransform
  src"context//stylesheets/system/status2html.xslt
  "gt  ltmapparameter name"contextPath"
  value"requestcontextPath"/gtlt/maptransformgtlt
  mapserialize/gt
• lt/mapactgt

62
Sitemap components example

• ltmapcomponentsgt  ltmapgenerators/gt  ltmaptran
  sformers default"xslt"gt     ltmaptransformer
  logger"sitemap.transformer.xslt"           name
  "xslt" pool-max"32"              src"org.apache
  .cocoon.transformation.TraxTransformer"gt       
  ltuse-request-parametersgtfalselt/use-request-para
  metersgt                     ltuse-session-paramete
  rsgtfalselt/use-session-parametersgt               lt
  use-cookie-parametersgtfalselt/use-cookie-parameters
  gt               ltxslt-processor-rolegtxalanlt/xslt-
  processor-rolegt               ltcheck-includesgttru
  elt/check-includesgt     lt/maptransformergt  lt/ma
  ptransformersgt   ltmapserializers/gt  ltmapreade
  rs/gt  ltmapactions/gt  ltmappipes/gtlt/mapcompone
  ntsgt

63
Tip reusing components

• Components can be re-defined with different
  configurations,
• Names have to be unique
• ltmaptransformer logger"sitemap.transforme
  r.xalan" name"xalan" pool-max"32"
  src"org.apache.cocoon.transformation.TraxTransfor
  mer"gt      ltuse-request-parametersgtfalselt/use-req
  uest-parametersgt      ltuse-session-parametersgtfal
  selt/use-session-parametersgt      ltuse-cookie-para
  metersgtfalselt/use-cookie-parametersgt      ltxslt-p
  rocessor-rolegtxalanlt/xslt-processor-rolegt      ltc
  heck-includesgttruelt/check-includesgt    lt/maptran
  sformergt    ltmaptransformer logger"sitemap.tra
  nsformer.xsltc" name"xsltc" pool-max"32"
  src"org.apache.cocoon.transformation.TraxTransfor
  mer"gt      ltuse-request-parametersgtfalselt/use-req
  uest-parametersgt      ltuse-session-parametersgtfal
  selt/use-session-parametersgt      ltuse-cookie-para
  metersgtfalselt/use-cookie-parametersgt      ltxslt-p
  rocessor-rolegtxsltclt/xslt-processor-rolegt      ltc
  heck-includesgttruelt/check-includesgt    lt/maptran
  sformergt

64
Understanding views

• Views are exit points in pipeline processing
• Original motivation semantic search
• Current use mainly debug
• Configuration
• name unique identifier
• from-label explicit exit point
• from-position implicit (automatic) exit point
• first right after the generator
• last right before the serializer
• Activated by cocoon-viewview-name
• Warning! Views are not inherited by subsitemaps
• Warning! Views can be a security concern

65
More on views placing labels

• Labels are set using the label attribute on
  either
• A Generator or Transformer declaration in the
  components section (will work anywhere)
• A Generate or Transform directive in a pipeline
  (specific to the pipeline)
• An Aggregate or Part directive (more on this
  later)

66
View examples

• Defining views
• ltmapviewsgt    ltmapview from-label"content"
  name"content"gt      ltmapserialize
  type"xml"/gt    lt/mapviewgt    ltmapview
  from-label"content" name"pretty-content"gt      
  ltmaptransform src"stylesheets/system/xml2html.xs
  lt"/gt      ltmapserialize type"html"/gt    lt/map
  viewgt  lt/mapviewsgt
• Defining labels
• ltmapgenerator label"content"
  logger"sitemap.generator.file"
• name"file" pool-max"32
• src"org.apache.cocoon.generation.FileGen
  erator"/gt

67
Resources

• Reusable pipeline fragments
• Useful for repetitive tasks
• Will be (mostly) replaced by Virtual Sitemap
  Components
• Warning! Resources are not inherited by
  subsitemaps

68
A resource example

• Defining a resource
• ltmapresourcesgt   ltmapresource
  name"simple-page2html"gt     ltmaptransform
  src"context//samples/common/style/xsl/html/simpl
  e-page2html.xsl"gt       ltmapparameter
  name"contextPath" value"requestcontextPath"/gt
         ltmapparameter name"servletPath"
  value"requestservletPath"/gt       ltmapparame
  ter name"sitemapURI" value"requestsitemapURI"
  /gt       ltmapparameter name"file"
  value"file"/gt       ltmapparameter
  name"remove" value"../0"/gt     lt/maptransfor
  mgt    lt/mapresourcegt lt/mapresourcesgt
• Calling a resource
• ltmapcall resource"simple-page2html"gtltmapparame
  ter name"file" value"forms/form1_success.xsp"/gt
• lt/mapcallgt

69
Action-sets

• Define a set of actions to be executed as a unit
  of work either
• Unconditionally (upon every invocation)
• When explicitely called, using a cocoon-action
  parameter
• ltmapaction-setsgt  ltmapaction-set
  name"shop-actions"gt    ltmapact
  type"session-invalidator" action"logoff"/gt    lt
  mapact type"session-validator"/gt lt!-- Always
  executed --gt    ltmapact type"cart-add"
  action"addItem"/gt    ltmapact
  type"cart-remove" action"removeItem"/gt    ltmap
  act type"cart-remove-all" action"removeAll"/gt  
    ltmapact type"cart-update" action"updateQty"/gt
      ltmapact type"order-add" action"addOrder"/gt
      ltmapact type"order-verify"
  action"verifyOrder"/gt    ltmapact
  type"navigator" src"1"/gt lt!-- Always executed
  --gt
•   lt/mapaction-setgtlt/mapaction-setsgt

70
Declaring flow scripts

• Flow is a new way to insert page flow control in
  your application (much more on that later)
• Scripts and/or classes are declared in the flow
  section of the sitemap
• ltmapflow language"javascript"gt
• ltmapscript src"calc.js"/gt
• lt/mapflowgt  
• ltmapflow language"java"gtltmapscript
• src"org.apache.cocoon.samples.flow.java.Cal
  culatorFlow"/gtltmapscript src"org.apache.cocoon.
  samples.flow.java.FormFlow"/gtltmapscript
• src"org.apache.cocoon.samples.flow.java.Per
  sistenceFlow"/gt
• lt/mapflowgt

71
The pipelines section

• The heart of Cocoon, where things get done
• Contains 1 ltmappipelinegt declarations
• Any pipeline section represents a logical
  division
• Different pipelines serve different purposes
• Visibility internal-only pipelines can only be
  just using the cocoon protocol
• Caching, as pipelines can be
• non-cached (always executed)
• cached delegating validity to the pipeline
  components (executed if nothing has changed in
  the pipeline)
• cached beforehand using the expires directive
  (executed only once during the validity period)

72
Cocoon pipelines dissected

• Pipelines are recipes building resources
• SAX events travel through the pipeline
• The TLA is GTS Generator, Transformer,
  Serializer
• Generators are adapters from the outside world to
  SAX events
• Transformers are SAX filters
• Serializers are the opposite of Generators,
  adapting SAX events to the outside world
• The obligatory diagram

73
Whats in a pipeline?

• Well, components in action from nouns to verbs
• Content production
• generate - transform - serialize
• aggregate - part - part
• read
• Branching
• match
• select
• act
• call

74
So whats the sitemap, again?

• Central switchboard (or FrontController, if you
  like patterns)
• Contains component declarations (yes, even
  business components)
• Locates (match) and builds (pipelines) the final
  result
• In most cases, its the only file youll need to
  touch

75
A typical request cycle in Cocoon

• The environment is checked for the proper
  pipeline to use (normally via matching/selecting)
• The pipeline is evaluated
• Sitemap components are looked up via type
  references or default assignment
• The pipeline is setup.
• The pipeline is executed
• Warning no dynamic sitemap routing!

76
Zen and the art of matching
77
A perfectly valid pipeline example

• ltmappipelinegt
• ltmapgenerate srchello.xml"
  type"file"/gt
• ltmaptransform srchello2html.xsl"
  type"xslt"/gt
• ltmapserialize type"html"/gt
• lt/mappipelinegt
• Would match any request and greet the user
• which is probably not what you want

78
Matchers kick in

• Matchers associate the actual environment to a
  pipeline
• ltmappipelinegt
• ltmapmatch patternhello type"wildcard"gt
• ltmapgenerate srchello.xml"
  type"file"/gt
• ltmaptransform srchello2html.xsl"
  type"xslt"/gt
• ltmapserialize type"html"/gt
• lt/mapmatchgt
• ltmappipelinegt
• Hit http//localhost8888/hello

79
Semantic problem

• Warning, pitfall ahead!
• Formally a pipeline is everything included in
  ltmappipelinegt
• Colloquially, though, a pipeline is normally the
  G-T-S part
• ltmappipelinegt
• ltmapmatch patternhello type"wildcard"gt
• ltmapgenerate srchello.xml"
  type"file"/gt
• ltmaptransform srchello2html.xsl"
  type"xslt"/gt
• ltmapserialize type"html"/gt
• lt/mapmatchgt
• ltmapmatch patterngoodbye type"wildcard"gt
• ltmapgenerate srcgoodbye.xml"
  type"file"/gt
• ltmaptransform srcbye2html.xsl"
  type"xslt"/gt
• ltmapserialize type"html"/gt
• lt/mapmatchgt
• ltmappipelinegt

80
Why the fuss?

• A pipeline, formally, is everything that starts
  with a Generator and ends with a Serializer
• This sample, then, is perfectly valid
• 1ltmappipelinegt
• 2 ltmapmatch patternhello type"wildcard"gt
• 3 ltmapgenerate srchello.xml"
  type"file"/gt
• 4 lt/mapmatchgt
• 5 ltmapmatch patterngoodbye
  type"wildcard"gt
• 5 ltmapgenerate srcgoodbye.xml"
  type"file"/gt
• 7 lt/mapmatchgt
• 8 ltmaptransform srcgreeting2html.xsl"
  type"xslt"/gt
• 9 ltmapserialize type"html"/gt
• 10ltmappipelinegt

81
To make things further complicated

• This one is valid as well
• 1ltmappipelinegt
• 2 ltmapmatch patternhello type"wildcard"gt
• 3 ltmapgenerate srchello.xml"
  type"file"/gt
• 4 ltmaptransform srcgreeting2html.xsl"
  type"xslt"/gt
• 5 ltmapserialize type"html"/gt
• 6 lt/mapmatchgt
• 7 ltmapmatch patterngoodbye
  type"wildcard"gt
• 8 ltmapgenerate srcgoodbye.xml"
  type"file"/gt
• 9 lt/mapmatchgt
• 10 ltmaptransform srcgreeting2html.xsl"
  type"xslt"/gt
• 11 ltmapserialize type"html"/gt
• 12ltmappipelinegt

82
Argh! Where is my aspirin?

• but this one could not be
• 1ltmappipelinegt
• 2 ltmapgenerate srchello.xml" type"file"/gt
• 3 ltmapmatch patternhello type"wildcard"gt
• 4 ltmapgenerate srchello.xml"
  type"file"/gt
• 5 ltmaptransform srcgreeting2html.xsl"
  type"xslt"/gt
• 6 ltmapserialize type"html"/gt
• 7 lt/mapmatchgt
• 8 ltmapmatch patterngoodbye
  type"wildcard"gt
• 9 ltmapgenerate srcgoodbye.xml"
  type"file"/gt
• 10 lt/mapmatchgt
• 11 ltmaptransform srcgreeting2html.xsl"
  type"xslt"/gt
• 12 ltmapserialize type"html"/gt
• 13ltmappipelinegt

83
Bottom line

• Cocoon will process the sitemap and try to build
  a G-T-S pipeline
• Cocoon will stop processing when a Serializer is
  met
• Beware the Generator already set errors!
• You cant have a Serializer already set error

84
Understanding matchers

• Matchers will route a user request through
  Cocoon pipelines
• Matchers are evaluated in order first match wins
• Matchers are available for the whole environment,
  matching on
• Request URI
• Request parameters
• Request Attributes
• Session Attributes
• Cookies
• and more
• Matchers are pluggable write your own!

85
Using matchers

• A basic example
•      ltmapmatch pattern""gt      ltmapgenerate
  src"welcome.xml"/gt      ltmaptransform
  src"welcome.xslt"/gt      ltmapserialize
  type"xhtml"/gt    lt/mapmatchgt
• Captures an empty URI

86
Wildcard-based matching

• Wildcard match part of the URI using special
  chars (/)
• A single asterisk matches everything up to the
  first forward slash
•   ltmapmatch patternwelcome-"gt      ltmap
  generate src"welcome.xml"/gt      ltmaptransform
  src"welcome.xslt"/gt      ltmapserialize
  type"xhtml"/gt    lt/mapmatchgt
• Matches http//localhost8888/welcome-friend
• A double asterisk matches everything
•      ltmapmatch patternwelcome"gt      ltmapge
  nerate src"welcome.xml"/gt      ltmaptransform
  src"welcome.xslt"/gt      ltmapserialize
  type"xhtml"/gt    lt/mapmatchgt
• Matches http//localhost8888/welcome/friend

87
Capturing matcher results

• Captured parts of a URI are available for later
  use
• Ordered list, denoted by position number in curly
  braces
• Starts at 1
•   ltmapmatch patternwelcome-"gt      ltmap
  generate src"welcome-files/1.xml"/gt      ltmap
  transform src"welcome.xslt"/gt      ltmapserializ
  e type"xhtml"/gt    lt/mapmatchgt
• Matches http//localhost8888/welcome-friend
• Uses welcome-files/friend.xml as the generator
  input
• Can be arbitrarily complex
• ltmapmatch pattern"linkstatus///"gt    
   ltmapgenerate src"http//12/3"
  type"linkstatus"/gt     ltmaptransform
  src"stylesheets/system/linkstatus2html.xslt"/gt  
     ltmapserialize/gt   lt/mapmatchgt

88
Nesting matchers

• Matchers can be nested
•   ltmapmatch patternwelcome-"gt
• ltmapmatch patternfriend-"gt
•        ltmapgenerate src"welcome-files/
  1.xml"/gt
• lt/mapmatchgt
• ltmapmatch patternfoe-"gt
•        ltmapgenerate srcgoaway/1.xml"/gt
• lt/mapmatchgt       ltmaptransform
  src"welcome.xslt"/gt      ltmapserialize
  type"xhtml"/gt    lt/mapmatchgt

89
Nesting matchers capturing parent results

• The matched expression on the child matcher
  doesnt take into account the part already
  matched
• Parent captured expressions are available with
  a tree navigation syntax
•   ltmapmatch patternwelcome-"gt
• ltmapmatch typehost-matcher
  patternlocalhost"gt
•        ltmapgenerate srclocal-files/../1.
  xml"/gt
• lt/mapmatchgt
• ltmapmatch typehost-matcher
  pattern.mydomain.com"gt
•        ltmapgenerate srcremote-files/1/.
  ./1.xml"/gt
• lt/mapmatchgt       ltmaptransform
  src"welcome.xslt"/gt      ltmapserialize
  type"xhtml"/gt    lt/mapmatchgt

90
Dealing with Sources
91
The Source abstraction

• Abstracts a stream based data source
• Sub interfaces define write mode and tree-like
  navigation (à la java.io.File)
• URL-like syntax (with some bastardization)

92
The Source interface
93
Available sources

• Remote sources
• URLSource deals with every protocol available
  for java.net.URL
• FileSource manages local files
• WebDAVSource interoperates with WebDAV
  repositories
• XMLDBSource connects to NXDs
• BlobSource uses databases blobs
• Meta sources
• SitemapSource uses Cocoon pipelines as data
  stream sources
• ResourceSource grabs data from classpath
• ContextSource accessed streams from the webapp
  context
• ModuleSource converts modules into sources
• CachedSource decorates sources adding passive
  caching

94
The Sitemap Source

• Calls cocoon pipelines
• Weirdo
• When used in a generator or transformer, the
  called pipeline serializer will be ignored
• When used in a reader, the serializer will be
  honored
• More weirdos URL bastardization
• cocoon/ will call a pipeline starting from the
  current sitemap
• cocoon// will call a pipeline starting from the
  root sitemap

95
Cocoon Components Tour

• A journey through Generators, Transformers,
  Serializers, Readers, Matchers, Sub-sitemaps,
  Modules, Error handling and more

96
Components Tour

• Cocoon has roughly 400 components
• 66 Generators
• 65 Transformers
• 23 Serializers
• 10 Readers
• 37 Matchers
• 31 Selectors
• 88 Actions
• 59 Input/Output Modules
• And you might want to write your own
• No way to cover them all well see the most
  useful

97
Useful stuff FileGenerator

• Actually its a SourceGenerator can deal with
  every Source data stream
• which includes cocoon// URIs
• Probably the most used generator in Cocoon

98
Useful stuff Directory Traversal

• Operate on TraversableSources (directories)
• Provide an XML listing of the requested resources
• Available components
• DirectoryGenerator
• ImageDirectoryGenerator
• MP3DirectoryGenerator
• TraversableGenerator
• TraversableSourceDescriptionGenerator
• XPathTraversableGenerator

99
Useful stuff more generators

• JXTemplateGenerator inspired by JSTL, more on
  this later
• RequestGenerator XMLized Request object
• SessionAttributeGenerator streams an object
  stored in session as XML
• StreamGenerator reads and streams XML from a
  request InputStream (e.g. POST requests)
• HttpProxyGenerator accesses an XML stream over
  HTTP
• HTMLGenerator grabs HTML from a source, converts
  to XHTML using jTidy and streams it away

100
Useful stuff TraxTransformer

• Can use either (and concurrently)
• TRAX
• Xalan
• Saxon
• Relevant configuration parameters
• ltuse-request-parametersgttruefalselt/use-request-pa
  rametersgt
• ltuse-session-parametersgttruefalselt/use-session-pa
  rametersgt
• ltuse-cookie-parametersgttruefalselt/use-cookie-para
  metersgt
• ltxslt-processor-rolegttraxxalanxsltclt/xslt-proces
  sor-rolegt
• ltcheck-includesgttruelt/check-includesgt
• Beware caching impact!

101
Useful stuff I18NTransformer

• Incredibly useful for dictionaries and
  localization
• Golden rule use it
• Relevant configuration
•  ltmaptransformer name"i18n" logger"sitemap.tran
  sformer.i18n" src"org.apache.cocoon.transformatio
  n.I18nTransformer"gtltcatalogues
  default"messages"gt  ltcatalogue id"messages"
  name"messages" location"translations"/gt  ltcatal
  ogue id"menu" name"menu" location"translations"
  /gt  ltcatalogue id"tiered" name"messages"gt     
  ltlocationgttranslations/tieredlt/locationgt     ltloc
  ationgttranslationslt/locationgt  lt/cataloguegtlt/cat
  aloguesgtltcache-at-startupgttruelt/cache-at-startupgt
  
• lt/maptransformergt

102
Dissecting I18NTransformer

• Resolving catalogue files
• name, id unique identifiers and base names for
  files
• location a source to be prepended to the base
  names
• Locale will be appended, in full or short form
  (en_US or en as a fallback).
• Finally, .xml will complete the file name
• So
• ltcatalogue id"messages" name"messages
  location"translations"/gt
• Assuming en_US as locale, the transformer will
  look for
• translations/messages_en_US.xml
• translations/messages_en.xml
• translations/messages.xml

103
I18N catalog files

• ltcatalogue xmllang"en"gt
• ltmessage key"Apache Cocoon i18n
  Samples"gtApache Cocoon i18n Sampleslt/messagegtltmes
  sage key"Samples"gtSampleslt/messagegtltmessage
  key"Introduction"gtIntroductionlt/messagegtltmessage
  key"Static (XML)"gtStatic (XML)lt/messagegtltmessag
  e key"Dynamic (XSP)"gtDynamic (XSP)lt/messagegtltmes
  sage key"Sitemap source"gtSitemap
  sourcelt/messagegtltmessage key"Locales"gtLocaleslt/m
  essagegtltmessage key"Documentation"gtDocumentation
  lt/messagegtltmessage key"i18n transformer
  docs"gtlt!CDATAltI18ntransformergt
  docsgtlt/messagegtltmessage key"i18n transformer
  Javadoc"gtlt!CDATAltI18ntransformergt
  Javadocgtlt/messagegtltmessage key"LocaleAction
  Javadoc"gtlt!CDATAltLocaleActiongt
  Javadocgtlt/messagegtltmessage key"Credits"gtCredit
  slt/messagegtltmessage key"Konstantin
  Piroumian"gtKonstantin Piroumianlt/messagegtltmessage
  key"Many others..."gtMany others...lt/messagegt
• lt/cataloguegt

104
Using the I18NTransformer

• From then you can happily translate
• Elements
• lttitlegt  lti18ntextgttitletextlt/i18ntextgt
• lt/titlegt
• Attributes
• ltpara title"first" name"article"
  i18nattr"title name"gt
• Dates
• lti18ndate-time pattern"MEDIUM"/gt
• Numbers
• lti18nnumber type"percent" src-locale"en"
  value"1.2"/gt

105
Useful stuff CIncludeTransformer

• Dynamically inserts content in XML streams
• Reacts to elements in the http//apache.org/cocoon
  /include/1.0 namespace
• ltpage   xmlnscinclude"http//apache.org/cocoo
  n/include/1.0"gt  lttitlegtHellolt/titlegt  ltcontentgt
      ltparagtThis is my first Cocoon
  page!lt/paragt    ltcincludeinclude
  src"include.xml" element"included"/gt  lt/content
  gtlt/pagegt    
• Can be cached as well
• ltmaptransform type"cinclude"gt      ltmappara
  meter name"expires" value"600"/gt
• lt/maptransformgt
•   ltcincludecached-include src"include.xml"/gt

106
Useful stuff SourceWritingTransformer

• Useful to write XML data to (Writeable) Sources
  during pipeline execution
• e.g., save a file
• Reacts to elements in the http//apache.org/cocoon
  /source/1.0 namespace
• Typically used with XSLT building the source
  stuff
• Read the Javadocs for details
• ltpagegt  ltsourcewrite create"true
• xmlnssource"http//apache.org/cocoon/sour
  ce/1.0"gt    ltsourcesourcegtfile//tmp/test.writelt
  /sourcesourcegt    ltsourcefragmentgt      lttitle
  gta titlelt/titlegt      ltcontentgt       ...      
  lt/contentgt    lt/sourcefragmentgt  lt/sourcewrite
  gtlt/pagegt

107
Useful stuff XMLSerializer

• Outputs, well, XML.
• Configurable encodings and doctypes
• ltmapserializer logger"sitemap.serializer.xhtml"
  
• mime-type"application/xhtmlxml" name"xhtml11
  
• src"org.apache.cocoon.serialization.XMLSerialize
  r"gtltdoctype-publicgt-//W3C//DTD XHTML
  1.1//ENlt/doctype-publicgtltdoctype-systemgt
• http//www.w3.org/TR/xhtml11/DTD/xhtml11.dtd
  
• lt/doctype-systemgt
• ltencodinggtUTF-8lt/encodinggt
• lt/mapserializergt

108
Useful stuff FOPSerializer

• Uses Apache FOP to produce
• PDF
• PS
• PCL
• RTF
• ltmapserializer logger"sitemap.serializer.fo2pdf"
  
• mime-type"application/pdf" name"fo2pdf"
  src"org.apache.cocoon.serialization.FOPSerializer
  "gt      ltuser-configgtWEB-INF/fop-config.xmllt/user
  -configgt      ltset-content-lengthgttruelt/set-conte
  nt-lengthgt
• lt/mapserializergt
• ltmapserializer logger"sitemap.serializer.fo2ps"
  
• mime-type"application/postscript"
  name"fo2ps" src"org.apache.cocoon.serialization.
  FOPSerializer"/gt
• ltmapserializer logger"sitemap.serializer.fo2pcl"
  
• mime-type"vnd.hp-PCL" name"fo2pcl"
  src"org.apache.cocoon.serialization.FOPSerializer
  "/gt    

109
Useful stufff SVGSerializer

• Takes SVG as input, produces JPEG/PNG as output
• Uses Apache Batik
• ltmapserializer logger"sitemap.serializer.svg2jpe
  g"
• mime-type"image/jpeg" name"svg2jpeg"
  src"org.apache.cocoon.serialization.SVGSerializer
  "gt   ltparameter name"quality" type"float"
  value"0.9"/gt
• lt/mapserializergt
• ltmapserializer logger"sitemap.serializer.svg2png
  "
• mime-type"image/png" name"svg2png
• src"org.apache.cocoon.serialization.SVGSeriali
  zer"/gt    

110
Useful stuff ImageReader

• Will serve images (surprise!)
• The kick performing width, height, ratio
  adjustments (great for thumbnails)
•       
• ltmapmatch pattern"image-size-"gt ltmapread
  type"image" src"logo.jpg"gt ltmapparameter
  name"width" value"1"/gt ltmapparameter
  name"height" value"1"/gt lt/mapreadgt
• lt/mapmatchgt

111
Sub sitemaps

• Sitemaps could become overpopulated and messy
  (the Perl effect)
• Solution modularize using sub-sitemaps
• From the main sitemap match the parent path and
  mount a sitemap underneath
•     ltmapmatch pattern"xsp/"gt     ltmapmount
  uri-prefix"xsp" src"xsp.xmap"
  /gt   lt/mapmatchgt
• Wildcard substitution, of course, works
• ltmapmatch pattern"/"gt
• ltmapmount src"/home/1/public_html/"
  uri-prefix"1"/gt lt/mapmatchgt  

112
Input/Output Modules

• Modules create generic components and plug actual
  input/output at runtime
• Example grab a request parameter and use it in
  the sitemap
• ltmapmatch patternwelcome"gt
•        ltmapgenerate srclocal-files/request-p
  aramfile.xml"/gt
•       ltmaptransform src"welcome.xslt"/gt     
   ltmapserialize type"xhtml"/gt    lt/mapmatchgt
• Again no dynamic routing possible
• Modules are evaluated during the pipeline setup
  phase

113
Useful modules GlobalInputModule

• Allows to configure global variables in the
  sitemap, with runtime substitution
• Helps writing maintainable code
• ltmapcomponent-configurationsgt    ltglobal-var
  iablesgt      ltstaginggtwebdav//localhost/webdav/s
  tep1/lt/staginggt    lt/global-variablesgt  lt/mapco
  mponent-configurationsgt  ltmappipelinegt    ltma
  pmatch pattern"repo/"gt      ltmapgenerate
  type"traverse" src"globalstagingrepo/"gt     
     ltmapparameter name"depth" value"1"/gt      lt
  /mapgenerategt      ltmapserialize
  type"xml"/gt    lt/mapmatchgt
•    lt/mappipelinegt

114
Useful modules XMLFileInputModule

• Allows XPath queries on external resources
• Helps maintainability configuration will be
  outside the sitemap
• Configured in cocoon.xconf
• ltcomponent-instance    class"org.apache.cocoo
  n.components.modules.input.XMLFileModule"  logger
  "core.modules.xml" namesettings"gt     ltfile
  src"cocoon//project.mount/configuration/test.
  xhtml"         reloadable"false"
  cacheable"true"/gtlt/component-instancegt
• ltmapgenerate type"traverse"
  src"settings/html/head/title"gt

115
When things go wrong error handling

• Error conditions (exception) can be catched in
  the pipeline
• Each pipeline can have a handle-errors section
• Error handling is inherited
• NotifyingGenerator provides errors in XML format
• ExceptionSelector allows branching according to
  the exception

116
Error handling explained

• ltmapselector logger"sitemap.selector.exception"
  name"exception"
• src"org.apache.cocoon.selection.ExceptionSele
  ctor"gt
• ltexception class"o.a.c.ResourceNotFoundExcept
  ion" name"not-found"/gt      
• ltexception class"o.a.c.c.flow.InvalidContinuat
  ionException"
• name"invalid-continuation"/gt
• lt/mapselectorgt  
• ltmaphandle-errorsgt
• ltmapselect type"exception"gt  ltmapwhen
  test"not-found"gt     ltmapgenerate
  type"notifying"/gt     ltmaptransform
  src"stylesheets/system/error2html.xslt/gt     ltm
  apserialize status-code"404"/gt  lt/mapwhengt  
  ltmapwhen test"invalid-continuation"gt      ltmap
  generate type"notifying"/gt      ltmaptransform
  src"stylesheets/system/error2html.xslt"gt      ltm
  apserialize status-code"404"/gt  lt/mapwhengt  
  ltmapotherwisegt      ltmapgenerate
  type"notifying"/gt      ltmaptransform
  src"stylesheets/system/error2html.xslt"gt      ltm
  apserialize status-code"500"/gt  lt/mapotherwise
  gtlt/mapselectgt
• lt/maphandle-errorsgt

117
Flowscript

• The magic of web continuations

118
Overview

• Introduction
• JavaScript features
• View layer
• Putting it all together
• Session variables
• Managing continuations

119
Introduction

• Need for flow control
• What is "flow control" ?
• Control of transition between pages
• Driven by application logic
• Aren't actions enough ?
• Yes, but they require state management
• Quickly becomes complex, hard to understand and
  to maintain

120
Introduction

• Flow script what is it ?
• Simple and effective way to glue together
  business logic, presentation and page flow
• Uses scripts written in JavaScript (server-side)
• a simple scripting language
• can implement the most complex use cases
• Why JavaScript ?
• Simpler than Java, although powerful
• Integrates well with Java
• Well-known in the web world
• Allows faster roundtrips (save and reload)
• Supports continuations

121
Introduction

• Flow script example

var cart var user function checkout()
while(user null) cocoon.sendPageAndWait("
login.html") user UserRegistry.getUser(coc
oon.request.get("name"))
cocoon.sendPageAndWait("shippingAddress.html",
who user) var address cocoon.request.get(
"address") cocoon.sendPageAndWait("creditCard.h
tml") var creditCard cocoon.request.get("cre
ditCard") cocoon.sendPageAndWait("confirmOrder.
html") EnterpriseSystem.placeOrder(user,
cart, address, creditCard) cocoon.sendPage("ord
erPlaced.html")
122
Introduction

• JavaScript vs. Java detour
• If you know Java, you already know JavaScript
  !Well, mostly.
• JavaScript is dynamically typed (variables dont
  have types, values do)
• Prototype-based inheritance as opposed to
  class-based inheritance
• Objects are extensible at runtime add or remove
  properties and methods

123
Calling the view

• cocoon.sendPage()
• cocoon.sendPage invokes the output page (view)
  with two arguments
• The view URL, relative to current sitemap
• A context Map made available to the view
• ? Can contain Java or JavaScript objects
• cocoon.sendPage("view.html") is like redirecting
  to "cocoon/view.html"
• Control then comes back to the script
• ? Should normally terminate

cocoon.sendPage("checkout.html", user
loggedUser, email address)
124
Calling the view

• cocoon.sendPageAndWait()
• Similar to cocoon.sendPage
• Invoke the view with a context object
• The script is suspended after the view is
  generated
• ? the whole execution stack saved in a
  continuation object
• Flow between pages becomes sequential code
• ? No more complicated state automata

125
Continuations

• What is it ?
• Contents of a continuation
• Stack of function calls
• Value of local variables
• ? Most often a lightweight object
• ? Creating a continuation does not halt a thread
  !!
• A continuation object is associated with a unique
  identifier available to the view
• ? Later used to "resurrect" it

126
Continuations

• Sample flow script revisited

var cart var user function checkout()
while(user null) cocoon.sendPageAndWait("
login.html") user UserRegistry.getUser(coc
oon.request.get("name"))
cocoon.sendPageAndWait("shippingAddress.html",
who user) var address cocoon.request.get(
"address") cocoon.sendPageAndWait("creditCard.h
tml") var creditCard cocoon.request.get("cre
ditCard") cocoon.sendPageAndWait("confirmOrder.
html") EnterpriseSystem.placeOrder(user,
cart, address, creditCard) cocoon.sendPage("ord
erPlaced.html")
127
View layer JXTemplate

• What is JXTemplate ?
• An XML template language inspired by JSTL
• Doesn't allow code, but only access to context
  variables
• ? More simple, more secure
• Flow values are provided as variables
• 2 expression languages Jexl and JXPath

ltjxforEach var"item" items"cart.items"gt
ltpgtName ltjxout value"item.name"/gtlt/pgt lt/jxf
orEachgt
lta href"kont/continuation.id"gtContinuelt/agt
128
View layer JXTemplate

• Jexl
• JSTL Velocity's expression language
• JavaBean property navigation language
• ? Property navigation using "."
• Expressions enclosed in
• ? More suited to Java objects

You are calling from request.remoteHost
http//jakarta.apache.org/commons/jexl/
129
View layer JXTemplate

• JXPath
• XPath on abitrary object graphs
• XML documents, but also JavaBeans
• Expressions enclosed in