Cocoon Integration

Concepts

The xReporter server (which runs inside Phoenix) contains all logic related to the execution of reports. The output generated by xReporter however is always XML. That XML needs to be transformed one way or the other before displaying to the user. This is a job for the presentationlayer. For this purpose xReporter offers a number of Cocoon integration components, which allow to make a Web-interface on top of xReporter. These components are described in this document. This document assumes the reader has some knowledge about Cocoon.

Cocoon communicates with xReporter using xReporter's HTTP interface. That HTTP interface makes the functionality of xReporter available as a number of URL addressable resources. The behaviour of xReporter's URL's varies according to the used HTTP method (GET or POST). For example: to get the description of an interactionstep, a get is executed on a certain URL. To submit the values for that interactionstep, a POST is done to the same URL.

Authentication

xReporter expects for all requests a username as parameter. xReporter itself however does not do any authentication, that task is left to the presentation layer. The simplest way to implement the authentication is to pass this responsibility to the servlet container. An example of how this can be configured for Tomcat is given in the installation document.

URL's and parameters

To keep the Cocoon layer as simple as possible, the HTTP interface that Cocoon offers to the Web browser is kept as similar as possible to the HTTP interface of xReporter. That way xReporter can simply pass on the requests to xReporter, and the only job left for Cocoon is to react on the XML output comming from xReporter. This will then cause the generation of a HTML page or a redirect to another page.

Language selection

The language is selected once by the user and then remembered in the URL. This means that all URL's are prefixed with the language, as in this example:

http://example.com/{mount-point}/{language-code}/datasources
http://example.com/cocoon/mount/xreporter/nl-BE/datasources

The {mount-point} part can be whatever, or even simply empty. In the {language-code} part the language is inserted, in the same format as xReporter expects.

Remembering the language selection in the URL offers, in contrast with storing it in the session, the advantage that the language remains known, even if the session is expired.

Various output formats

By default the user gets the output of a report in HTML. The user can however also choose to get the report in other formats, such as Excel, PDF, CSV or XML.

Stylesheet selection and parameterisation

For some reports you may want to have a layout that is completely different from the default layout. For example if the results shouldn't be displayed in a table but in some other manner. For those cases it is possible to create a report-specific stylesheet (XSLT).

In many cases however the default table layout will suffice, but some parameterisation may be desired: specific column widths, some columns in another color, ... To support this a stylesheet parameterisation mechanism is provided.

Customer specific customisation

xReporter has the possibility to associate each user with a customer. That customer is available in the XML output of xReporter, and can thus be used to e.g. place the logo of the customer on the report. To achieve this, you will need to edit XSLT's.

Pipeline structure

As of xReporter 1.3, this section is somewhat outdated, as some refactoring of the sitemap has happened. Some basic principles still apply though.

Below is an example of the typical sitemap structure for handling an xReporter related request.

<map:match pattern="*/datasources">
  <map:act type="xreporter-request">
    <map:parameter name="lang" value="{1}"/>
    <map:parameter name="path" value="/datasources"/>
    <map:parameter name="method" value="GET"/>
    <map:select type="parameter">
      <map:parameter name="parameter-selector-test" value="{result-type}"/>
      <map:when test="LINK">
        <map:act type="xreporter-getlink">
          <map:act type="context-path">
            <map:redirect-to
              uri="{context-path}/{../../1}{../link}"/>
          </map:act>
        </map:act>
      </map:when>
      <map:when test="OK">
        <map:generate type="xreporter"/>
        <map:transform src="resources/custom/stylesheets/html/datasources.xsl"/>
        <map:transform type="i18n">
          <parameter name="locale" value="{../1}"/>
        </map:transform>
        <map:serialize type="html"/>
      </map:when>
      <map:otherwise>
        <map:generate type="xreporter"/>
        <map:transform src="resources/custom/stylesheets/html/error.xsl"/>
        <map:transform type="i18n">
          <parameter name="locale" value="{../1}"/>
        </map:transform>
        <map:serialize type="xml"/>
      </map:otherwise>
    </map:select>
  </map:act>
</map:match>

The pipeline fragment starts with a matcher that matches on "*/datasources". The star is a wildcard representing the language.

xreporter-request action

After the matcher there's an action, the "xreporter-request" action. This action does the communication with xReporter (over HTTP). It requires the following parameters:

lang language (and country) in the format as xReporter requires, e.g. nl-BE, fr-BE, en-US, ...
path the path to which the request should be send (as specified in xReporter's HTTP-interface).
method the HTTP method for the request to be send to xReporter. This can be GET or POST.

The xreporter-request action will then send a HTTP request to xReporter. The user (authenticated by the servlet container) and all incoming request parameters will be automatically added to the request.

xReporter's response to the request is then retrieved in a buffer. The type of response from xReporter can be subdivided into three categories:

normal response, the requested data is returned
a link to somewhere else is returned
an error is returned

The xreporter-request action will use pull-parsing to check the type of response given by xReporter (this can be derived from the document element). This answer-type is then, together with the buffer containing the actual data, stored in the request object, so that other components will be able to access it.

Next to the above mentioned types of answers there's one more possibility: an error can occur before xReporter is able to generate an answer.

The xreporter-request action returns a variable to the sitemap called " result-type". This contains one of the following: OK, LINK, APP_ERROR, ERROR. These values correspond to the types of answers discussed above.

parameter selector

After the xreporter-request action, the parameter selector is used. This is a standard Cocoon selector. This selector tests the value of the parameter " parameter-selector-test" that is passed to it. In our situation here, we test on the value of the result-type variable that was returned by the xrep orter-request action.

xreporter-getlink action

The first map:when checks whether the answer from xReporter is a link. In that case the value of the link can be retrieved with the xreporter-getlink action. This action returns a sitemap variable named "link". This link always starts with a slash, and is an absolute path to an xReporter HTTP resource (thus a path as described in xReporter's HTTP-interface).

Next to that the context-path action is used to retrieve the context path of the application, to avoid hard-coding this. The context path is the path on which the application is mounted in the servlet container plus the eventual mount-point of the subsitemap (in the default installation this is " /cocoon/mount/xreporter").

Finally map:redirect-to is used to redirect the browser to the linked location.

xreporter generator

The second map:when handles the case where the answer of xReporter is OK, thus that the requested XML data is returned. In this case the xreporter generator can be used. This will stream the data from the buffer that was created earlier by the xreporter-request action.

An XSL is then applied to style the XML data.

The i18n transformer will translate language-dependent texts produced by the XSL. This is only for texts created by the XSL (such as titles, navigation links, ...). The actual content retrieved from xReporter is already translated.

Finally all this is serialized to a HTML response.

error handling

The map:otherwise handles the cases APP_ERROR and ERROR. The xreporter generator is again used here, which will now generate information about the error that occured. The generated XML has the following structure:

<xr:error xmlns:xr="http://outerx.org/xreporter/result/1.0">
  <xr:description>
    [error description]
  </xr:description>
</xr:error>

In case the error is an APP_ERROR, the error message will usually be a localised message (thus translated into the language of the user).

Remarks

The sitemap pattern described above will be reused for each xReporter resource. In the actual sitemap, certain patterns are always the same, and have therefore been moved into resources.

Note also that in the above example we check if the response of xReporter is a link, while that could never be the case for the /datasources resource. It's only added here to demonstrate the general pattern.

Output pipelines

As of xReporter 1.3, this section is somewhat outdated, as some refactoring of the sitemap has happened. Some basic principles still apply though.

Some extra notes about the pipelines generating the report output.

HTML output

Here we take a look at the normal HTML output of the report, thus the thing the users gets to see before it can select other output formats.

The HTML output makes use of chunking: no more than 50 records are shown at once (by default). To do this, xReporter expects two extra parameters: chunkOffset and chunkLength. Usually these are passed on from the browser. Initially (on the first request) these parameters will not yet exist, therefore a special action "determine-chunk" is used. This action returns the values of chunkOffset and chunkLength: either they come from the request, or if not present there it returns by default 1 for chunkOffset, and 50 for chunkLength.

<map:match pattern="*/reports/*/output">
  <map:act type="determine-chunk">
    <map:act type="xreporter-request">
      <map:parameter name="lang" value="{../1}"/>
      <map:parameter name="path" value="/reports/{../2}/output"/>
      <map:parameter name="method" value="GET"/>
      <map:parameter name="parameter_chunkOffset" value="{chunkOffset}"/>
      <map:parameter name="parameter_chunkLength" value="{chunkLength}"/>
      ...

Here a functionality of the xreporter-request action is demonstrated that was not mentioned before: all parameters whose name start with "parameter_" are passed as request parameters to xReporter, but without the "parameter_" part.

Below the pipeline fragment is shown that generates the HTML output:

<map:when test="OK">
  <map:generate type="xreporter"/>
  <map:transform type="include-style-info">
    <map:parameter name="path" value="resources/custom/stylesheets/html/report/"/>
  </map:transform>
  <map:act type="determine-stylesheet">
    <map:parameter name="path" value="resources/custom/stylesheets/html/report/"/>
    <map:parameter name="default" value="resources/custom/stylesheets/html/output.xsl"/>
    <map:act type="context-path">
      <map:transform src="{../stylesheet}">
        <map:parameter name="context-path" value="{context-path}"/>
        <map:parameter name="lang" value="{../../../../1}"/>
      </map:transform>
    </map:act>
  </map:act>
  <map:transform type="i18n">
    <parameter name="locale" value="{../../1}"/>
  </map:transform>
  <map:serialize type="html"/>
</map:when>

There's various new stuff here. For starters we have the include-style-info transformer. This transformer will include an external XML file in the xreporter data (after the document element). This external XML file contains parameterisation data for the XSLT. The include-style-info transformer looks for a file called {reportdefinition-id}.xml in the directory specified in the path parameter. If such a file exists it will be included, and otherwise the transformer will do nothing.

The determine-stylesheet action's purpose is to find out which XSLT to use. In case a file called {reportdefinition-id}.xsl is found in the directory specified in the path parameter, then that will be used. Otherwise the stylesheet specified in the "default" parameter is used. The action returns a sitemap variable with the name "stylesheet" that contains the path to the stylesheet to use.

Other output formats

For the other output formats the same pattern is used as for the HTML output, except that there is no chunking involved. The URL's for these alternative output formats are like in these matcher patterns:

*/report-*.pdf
*/report-*.txt
...

Wherein the first star is a wildcard for the language and the second star is a wildcard for the report instance id.

To follow the design of the xReporter HTTP interface, it would have been better to make these output formats subresources of the output resource, such as:

*/reports/*/output/pdf
*/reports/*/output/txt
...

But because of pratical reasons the first solution is used: the file extension reflects the file type (some browsers require this), and files for different reports have different names.

Administrative resources

The default xReporter sitemap includes a number of administrative resources. More specifically it concerns the matchers with the following patterns:

*/admin/tests
*/admin/reportinstances
*/admin/connectionproviderstatus

It is highly recommended to disable these in production environments (or at least to secure them).

xReporter XML formats

When writing stylesheets for xReporter it is useful to know the xReporter XML formats. These are described in the document about the HTTP interface.

Comments (0)