Berlioz Services

/WEB-INF/config/services.xml

This configuration file is responsible for mapping services to some URL patterns and one or more Generators.

Service configuration

All Berlioz services are defined in the service configuration file:

<?xml version="1.0" encoding="utf-8"?>
  <!DOCTYPE service-config PUBLIC "-//Berlioz//DTD::Services 1.0//EN"
          "http://www.weborganic.org/schema/berlioz/services-1.0.dtd">
    <service-config version="1.0">
      <!-- services configuration go here -->
      <services group="[group #1]"> ... </services>
      <services group="[group #2]"> ... </services>
      <!-- ... -->
    </service-config>

Grouping Services

Services can be grouped together based on the type, format or structure they produce. This can be used to use a different set of templates or simply to group them logically:

<services group="[group name]">
  <!-- Individual services go here -->
<services>

Examples of grouping include:

default – to all services used by default.
dialog – for services that produce HTML for dialog boxes.
ajax – for services to be used exclusively in ajax.
admin – for admin related services.

The bzadmin group is a commonly used for providing a set of Berlioz administration services.

DTD

<!ELEMENT services                 ( response-code?, service* ) >
<!ATTLIST services  group           NMTOKEN           #REQUIRED >

Defining a Service

A Berlioz service associates one or more URL patterns to a set of generators. When a URL matches the one of the patterns, the generators are invoked in sequence.

At its simplest, a service can be defined as:

<service id="[service id]" method="[get|put|post|delete]">
  <url pattern="[URL pattern]"/>
  <generator class="[class name]"/>
</service>

But a service can: match different patterns, include several generators that might accept parameters, provide some cache control information or some specific conditions to return an error code. So a more complete definition is:

<service id="[id]" method="[method]" cache-control="[cache control]">
  <!-- for each pattern -->
  <url pattern="[URL pattern" />
  <!-- for a custom response code -->
  <response-code use="[names]" rule="[highest|lowest|first]" />
  <!-- for each generator -->
  <generator class="[class]" name="[name]" target="[target]">
    <!-- for each parameter -->
    <parameter name="[name]" value="[value]"/>
  </generator>
</service>

URL Pattern

A Berlioz service is invoked if the URL matches any one of the URL patterns defined for that service.

The URL pattern attempts to match the wildcard part of the Berlioz Servlet mapping in the Web descriptor (/WEB-INF/web.xml). In other words, it ignores the suffix or prefix in use for the mapping.

If the Servlet Mapping is ...	The URL Pattern should match ...
/html/*	Anything after `/html/`
`*.html`	Anything before `.html`

For details on the syntax for the patterns, see URI pattern.

Some examples of patterns:

Pattern	Matching URL (excluding prefix/suffix)
/home	/home
/{+path}	/acme/test /123 /hello
/{item}/{id}	/book/978-0-9802479-8-5

Any matching URI variable is made available to the generators and can be used as a parameter.

Generator

The generators must implement the Java ContentGenerator interface to be accepted; otherwise, Berlioz throws an error.

The following attributes can be specified:

name	description	Required
class	The fully qualified java class to load for this generator	Yes
name	A short hand name for the generator in the service	No
target	A target for the generated for content (see below)	No

Parameters

If a generator takes parameters, they can be specified using the <parameter> element.

Dynamic values can be specified using curly brackets. This can be useful to construct parameter values from HTTP query parameters or resolved URL variables.

There is no need to declare a parameter if it can be directly inherited from the HTTP query parameters or the URL. Berlioz automatically forwards them. But the element can be used to override inherited parameters.

Examples:

<parameter name="path" value="navigation"/>
<parameter name="path" value="nav/{section}"/>
<parameter name="isbn" value="{id}"/>

Response code

The purpose of the <response-code> element is to ensure that the status code for the HTTP response is meaningful.

This is only useful if a service invokes multiple generators. Some generators might be used to generate related content such as the navigation, headers etc. and should not cause the service to return an error if they fail.

This element can be specified at the different levels, so that if the same mechanism is used, it doesn’t have to be declared individually for each service.