Berlioz Services
/WEB-INF/config/services.xml
This configuration file is responsible for mapping services to some URL patterns and one or more generators. Generators are implement the ContentGenerator interface.
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 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 , last edited on