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

  </services>

</service-config>

Datatypes

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.

Elements

Attributes

DTD

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

Elements

Attributes

DTD

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

Elements

Attributes

DTD

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

Attributes

DTD

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

Elements

Attributes

DTD

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

Attributes

DTD

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

Attributes

DTD

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

Created on 12 December 2015 , last edited on 15 December 2015 at 16:23