Advanced topics


Berlioz Services


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"
<service-config version="1.0">
   <!-- services configuration go here -->
   <services group="[group #1]"> ... </services>
   <services group="[group #2]"> ... </services>
   <!-- ... -->

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 -->

Examples of grouping include:

  • default  to all services used by default
  • dialog  for services that will 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 Berlioz administration services. 


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

Defining a Service

A Berlioz services 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]"/>

But a service can match different patterns, include several generators which may 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]"/>

URL Pattern

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

The URL pattern will attempt 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/'
*.htmlAnything before '.html'

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

Some examples of patterns:

PatternMatching URL (excluding prefix/suffix)

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


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

The following attributes can be specified:

classthe fully qualified java class to load for this generatorYes
nameA short hand name for the generator in the serviceNo
targetA target for the generated for content (see below)No



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 declared a parameter if it can be directly inherited from the HTTP query parameters or the URL. Berlioz will automatically forward them. But the element can be used to override inherited parameters.


  • <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 ensure that the status code for the HTTP response is meaningful.

This is only useful if a service invokes multiple generators. Some generators may be used to generator 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 does not have to be declared individually for each service.


  • <response-code use="target:main" rule="highest"/>
  • <response-code use="search,facets" rule="first"/>

Created on , last edited on