Serializers in Cocoon

Serializers transform a SAX event stream into binary or character streams for output. If a pipeline contains a generator, it should also contain a serializer. You can get full details on any serializer in the components appendix of the Cocoon user manual:

• XML serializer—This Serializer serves as the basis for a number of the other serializers. It generates an XML document from the input SAX event stream. This serializer is in the class org.apache.cocoon.serialization.XMLSerializer under the name xml. You can provide a number of configuration parameters when you use the serializer from a <serialize> tag:
  
  
  
  • cdata-section-elements—A whitespace-separated list of elements whose text content should be enclosed in CDATA sections for output.
  
  
  • doctype-public—The public ID to be placed in the DTD of the output document.
  
  
  • doctype-system—The system ID to be placed in the DTD of the output document.
  
  
  • encoding—The character encoding to be supplied for the encoding declaration in the output document.
  
  
  • indent—"yes" if some elements should trigger a line break, or "no" otherwise (the default value is "yes").
  
  
  • media-type—The MIME content type of the document.
  
  
  • method—The output method that should be used. The method names are the XSLT output method names.
  
  
  • omit-xml-declaration—"yes" to omit the XML declaration.
  
  
  • standalone—"yes" to output a standalone document declaration.
  
  
  • version—The version of the output method. The defaults are 1.0 for the XML output method and 4.0 for the HTML output method.
  
  
  
  


• HTML serializer—The HTML serializer is the default for Cocoon pipelines. It’s in the class org.apache.cocoon.serialization.HtmlSerializer and available under the name html. This serializer accepts the same configuration parameters as the XML serializer.


• XHTML serializer—This is a use of the XML serializer for serializing the event stream as XHTML. There are some differences. When defining the XHTML serializer, you must supply some configuration parameters. These appear as child elements of the <serializer> element. The elements are doctype-public and doctype-system. The meaning of these elements corresponds to the XML serializer configuration parameters of the same name. You should supply the public and system ID of one of the three XHTML DTDs as the values of doctype-public and doctype-system, respectively. You also need to provide a mime-type attribute on the <serializer> element. The value of the mime-type should be "text/html". The XHTML serializer uses the same class as the XML serializer, org.apache.cocoon.serialization.XMLSerializer, but is named xhtml.


• Text serializer—The Text serializer is built on the XML serializer but in a different way than the XHTML serializer. When you define the text serializer, you need to supply a mime-type attribute on the <serializer> element. The value of this attribute should be "text/plain". After that, you’re all set. The class for the text serializer is org.apache.cocoon.serialization.TextSerializer (not XMLSerializer). The name is text.


• WAP/WML serializer—The WML serializer is also built on the XML serializer. You need to supply the mime-type attribute on the <serializer> when you define it, and you need to provide <doctype-public> and <doctype-system> children. The mime-type attribute should be set to "text/vnd.wap.wml". The value for <doctype-public> is -//WAPFORUM//DTD WML 1.1//EN, and the value for <doctype-system> is http://www.wapforum.org/DTD/wml_1.1.xml . You should name the serializer wml and use the class org.apache.cocoon.serialization.XMLSerializer.


• SVG/XML serializer—This is the last of the serializers based on the XML serializer. You need to set the mime-type attribute of the <serializer> element to "text/xml" when you define the serializer. You also need to set the value of the <doctype-public> child element to -//W3C//DTD SVG 1.0//EN and the value of the <doctype-system> child element to http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd. This serializer is named svgxml and is in org.apache.cocoon.serialization.XMLSerializer.


• SVG/JPEG serializer—This serializer expects the event stream to contain an SVG document. It serializes that document by using Batik to convert it into a JPEG image. This serializer uses the class org.apache.cocoon.serialization.SVGSerializer and is available under the name svg2jpeg. When you define it, it needs a mime-type attribute on the <serializer> element. The value for the attribute should be "image/jpeg". This causes SVGSerializer to select the correct Batik transcoder.
  You can supply some configuration parameters using <parameter> children of the <serializer> element. The SVG/JPEG serializer has its own specific parameter named quality; it’s a float that specifies the JPEG quality as a value between 0.0 and 1.0, with 1.0 being the best quality. There are also some parameters used by any serializer that uses SVGSerializer:
  
  
  
  • width—The width of the rasterized image. If no height is specified, the aspect ratio is preserved.
  
  
  
  
  
  
  • height—The height of the rasterized image. If no width is specified, the aspect ratio is preserved.
  
  
  • background_color—The background color. The value is of the form RRGGBB or #RRGGBB. The default background color is white.
  
  
  • language—The language to use. The default is English (en).
  
  
  • user_stylesheet_uri—The URI of a user stylesheet.
  
  
  • pixel_to_mm—The pixel to millimeter conversion factor. By default it’s 0.264583, which yields 96dpi.
  
  
  
  


• SVG/PNG serializer—This serializer works just like the SVG/JPEG serializer. When you define it, you supply "image/png" as the mime-type attribute value instead of "image/jpeg". You also use the name svg2png instead of svg2jpeg. In addition to the shared parameters for SVGSerializer (see the SVG/JPEG serializer), this serializer defines two parameters useful for PNG files. The parameter force_transparent_white controls the color of fully transparent pixels. If the parameter is "true", they’re white. If it’s "false", they’re black (the default). The other parameter is named gamma and controls the gamma correction of the PNG. The default value of gamma is about 2.22.


• SVG/TIFF serializer—This serializer is also based on SVGSerializer. Set the value of the mime-type attribute to "image/tiff". The name for this serializer is svg2tiff. It uses all the shared SVGSerializer parameters (see SVG/JPEG serializer), and it also uses the force_transparent _white parameter defined by the SVG/PNG serializer.


• Link serializer—The link serializer is the companion to the LinkStatus generator. It’s in the class org.apache.cocoon.serialization.LinkSerializer and can be accessed via the name links. The MIME type of the output is application/x-cocoon-links. You also need a views section in your site map (we’ll talk about views later):
  

  <map:views> <map:view from-position="last" name="links">  <map:serialize type="links" /> </map:view><map:views>

  
  


• PDF serializer (optional)—Cocoon’s PDF serializer uses FOP to serialize XML to PDF. The code for the serializer is part of the Cocoon distribution, but you need to install the FOP fop.jar in Cocoon’s lib directory. Once you’ve done that, you can specify fo2pdf as the name of the serializer, which is in org.apache.cocoon.serialization.FOPSerializer. The PDF serializer expects the input event stream to contain an XSL FO document. You can use the FOP tools to generate a PDF with embedded fonts.


• PS serializer (optional)—The PostScript serializer also uses FOP to do its job, so you need to do the same setup as for the PDF serializer. The serializer is in org.apache.cocoon.serialization .PSSerializer, and you can use the name fo2ps to access it. Like the PDF serializer, it expects an XSL FO document in the input event stream.


• PCL serializer (optional)—This serializer is like the PostScript and PDF serializers. It’s in org.apache.cocoon.serialization.PCLSerializer, and the name is fo2pcl.