Advanced

Advanced topics

 

Berlioz output

Berlioz produces two types of output:

Raw XML outputXML directly produced by Berlioz as a result of invoking the generators
Transformed outputRaw XML output that has been transformed for a particular output type.

Raw XML output

Whenever a request is made, Berlioz always produces a response by:

  1. Assembling the XML data produced by the generators
  2. Including a header with various metadata about the request

The XML response follows the structure below:

<root>
  <!-- Only one header, always first -->
  <header> ... </header>
  <!-- for each generator for the service -->
  <content generator=[class] name="[name]" target="[]" status="[]">
    ...
  </content>
</root>

XML Header

The XML header returns information about the request and how Berlioz processed it. It is consistent and follows the structure below:

<header>
  <group>[service-group]</group>
  <service>[service-id]</service>
  <path-info>[path-info]</path-info>
  <context-path>[context-path]</context-path>
  <host>[host]</host>
  <port>[port]</port>
  <url>[request-url]</url>
  <query-string>[query-string]</query-string>
  <http-parameters>
    <!-- for each HTTP parameter -->
    <parameter name="[parameter-name]">[parameter-value]</parameter>
  </http-parameters>
  <uri-parameters>
    <!-- for each URI parameter -->
    <parameter name="[parameter-name]">[parameter-value]</parameter>
  </uri-parameters>
  <berlioz version="[berlioz-version]"/>
</header>

 

service-groupThe name of the group the service is part of
service-idThe ID of the service corresponding to the request
path-infoThe Berlioz path information (normally corresponds to the * in the <url-pattern> in the Web descriptor
context-pathThe context path of the application (may be empty)
hostThe host of the application server
portThe port of the application server
request-urlThe request URL (without query string)
query-stringThe query string (part after the ? as defined in HTTP spec)
parameter-nameThe name of the HTTP or URI parameter
parameter-valueThe value of the HTTP or URI parameter
berlioz-versionThe version of Berlioz library in use

XML content

Each generator used by the service that processed the request will be wrapped in the XML below

<content generator=[generator-class] 
              name="[name]"
            target="[target]"
            status="[status]">
    <!-- The actual content depends on the generator -->
</content>

 

generator-classThe full class name of the generator invoked by the service
nameThe name given to this generator content as defined in the services.xml configuration file.
targetThe target for this generator content  as defined in theservices.xml configuration file.
statusIndicates the status of the generator request; 'ok' if the generator could process the request without error; 'error' otherwise.

The actual XML content inside the <content> element is specific to each generator. Check the generators API for details.

Transformed output

Generally, Berlioz will serve HTML or another output such as RSS, ICAL, etc.

The Berlioz servlet will use the stylesheet as defined in the Web descriptor ( /WEB-INF/web.xml ) to transform the raw XML into the desired output.

By convention, the stylesheet used by Berlioz is called global.xsl.

Specifying the output type

The output type is specified in the XSLT stylesheet using the <xsl:output> element.

The Berlioz servlet will use the attributes in this element to produce the correct HTTP headers.

For example, to produce an HTML 4 output:

<xsl:output method="html" encoding="utf-8" indent="yes"
            doctype-public="-//W3C//DTD HTML 4.01//EN"
            doctype-system="http://www.w3.org/TR/html4/strict.dtd"
            undeclare-prefixes="no"/>

Or to produce a different XML:

<xsl:output method="xml" encoding="utf-8" indent="yes" 
            media-type="application/xml" />

Created on , last edited on