Services 1.0

This article documents the schema used by the Berlioz services configuration for reference.

The actual DTD used by Berlioz can be found on Github .

For additional documentation, examples and guidelines on how to configure services within Berlioz, have a look at the services configuration article.

Quick reference

<service-config version="1.0">
  <!-- Response code rule for all services (not recommended) -->
  <response-code use="[generator_selector]" rule="[highest|lowest|first]"> ?

  <!-- Group of services -->
  <services group="[category_for_grouping]"> *

    <!-- Response code rule for this group of services -->
    <response-code use="[generator_selector]" rule="[highest|lowest|first]"> ?

    <!-- Individual service -->
    <service id="[service_id]" method="[get|post|put|delete]" cache-control="[http_cache_control]"?> *
      <url pattern="[uri_pattern]" /> +
      <response-code use="[generator_selector]" rule="[highest|lowest|first]"> ?
      <generator class="[full_class_name]" name="[shorter_name]"? target="[region_for_grouping]"? > *
        <parameter name="[name]" value="[value_shorthand]" > *




URI Pattern

A URI Pattern as defined in the URI Template specifications

<!ENTITY  % URI_PATTERN      "CDATA"                                         >

HTTP method

The HTTP method for the associated service

<!ENTITY  % HTTP_METHOD      "(get | put | delete | post)"                   >

Code rule

A rule to use to compute the response code of a service.

<!ENTITY  % CODE_RULE        "(highest | lowest | first)"                    >

Element guide

Element: service-config

The service-config is the document element of the service configuration.


response-codeA general rule for generating the response code common to all services
servicesContainer for the different group of services


version"1.0"The version of the service configuration; this attribute is optional but if specified it must be "1.0"


<!ELEMENT service-config                       ( response-code?, services* ) >
<!ATTLIST service-config     version           CDATA            #FIXED "1.0" >


Element: services

This element defines a group of services.

The grouping of services is specific to a Web application, but services are generally grouped by any of the following criteria:

  • General layout structure for pages (e.g. header+nav+main+footer)
  • Area within a site that may be specific to different audiences or permission level
  • Usage type (e.g. ajax, Web service, etc...)

Since the group will determine the principal stylesheet module and affects which files will be loaded by the bundler. The general guideline, is that if a collection of services should have many common styles, scripts, or templates they should probably in the same group.


response-codeA general rule for generating the response code common to this group
serviceIndividual services within that group of services


groupNMTOKENA name to group the services together.


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


Element: service

The service element define a single service.

A service is composed of multiple generators and must define at least URL.

The generators are invoked in the order in which they are defined.


urlThe URL patterns that the service must match (at least one must be specified)
response-codeA rule for generating the response code specific to this service
generatorThe list of generators to invoke for this service


idIDA unique identifier for the service.
methodThe HTTP method that this service must match
cache-controlA cache control response header for when the response is successful


<!ELEMENT service                       ( url+, response-code?, generator* ) >
<!ATTLIST service           id                 ID                  #REQUIRED
                            method             %HTTP_METHOD;       #REQUIRED
                            cache-control      CDATA                #IMPLIED >


Element: url

The url element specifies a URI pattern that a service must match.


patternURI patternThe URI pattern for the URL.


<!ELEMENT url                                                          EMPTY >
<!ATTLIST url               pattern            %URI_PATTERN;       #REQUIRED >


Element: generator

The generator element defines a content generator to include in a service.

The parameter element is used to rewire some of the parameters received by the service and to pass on to the generator for example to rename the parameter or combine values.

The class attribute must implement the ContentGenerator interface defined in Berlioz.

The name and target are passed on in the Berlioz raw output so that they can used in the XSLT to determine what to do with the generated content.


parameterThe list of parameters to pass on to the generator.



The fully qualified Java class to load for this generator.


A name for this generator.


A target for the content generated in the output.


<!ELEMENT generator                                           ( parameter* ) >
<!ATTLIST generator        class               CDATA                #IMPLIED
                           name                NMTOKEN              #IMPLIED
                           target              NMTOKEN              #IMPLIED >


Element: parameter

This element defines a parameter to pass to the generator



The name of the parameter


Specifies the value for the generator which may be static or dynamic


<!ELEMENT parameter                                                    EMPTY >
<!ATTLIST parameter         name               CDATA               #REQUIRED
                            value              CDATA               #REQUIRED >


Element: response-code

The response code element is used to specify how to determine the response type of a service from the generator.

This is useful when services include several generators but failure of single generator (for example returning NOT_FOUND) should not imply failure of the service.

The response code can be specified at three levels:

  • global when it is a child of the service-config element
  • service group when it is a child of the services element
  • individual service when it is a child of the service element

The most specific rule takes precedence (i.e. service first, group second, global last)

The default behaviour is to use the highest response code of all the generators in a service.



What generator should be used.


Specifies the value for the generator which may be static or dynamic


<!ELEMENT response-code                                                EMPTY >
<!ATTLIST response-code     use                CDATA               #REQUIRED
                            rule               %CODE_RULE;          #IMPLIED >

Created on , last edited on