Services

/WEB-INF/config/services.xml

This configuration file is responsible for mapping services to URL patterns and defining what content to generate when a service is invoked using generators. Generators implement the ContentGenerator interface.

Note

This file is the only mandatory configuration file in Berlioz.

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.pageseeder.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 will produce HTML for dialog boxes
ajax - for services to be used exclusively in ajax
admin - for admin related services

Note

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

DTD

<!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]"/>
</service>

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]"/>
  </generator>
</service>

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/`'
`*.html`	Anything before '`.html`'

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

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 will be 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 will throw 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.

Note

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.

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

Examples:

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

Created on 10 December 2015 , last edited on 17 December 2015 at 18:30