How Berlioz works

  1. Home
  2. get started
  3. how berlioz works
 

How Berlioz works

Every request to a Berlioz app, follows the steps below.

berlioz_process.png

1. Match service

The first step for Berlioz is to identify which service to execute. You can think of a service as a page in the context of HTML or a Web service when returning JSON or XML. All services have a unique identifier, that developers can define.

To make Berlioz more flexible, services are not simply attached to a specific single URL but to URL patterns (and an HTTP method). This allows all URLs matching that pattern to be handled by that service. By default, the extensions is not used for pattern matching.

All the services as well as which URL they match are defined in a configuration file called services.xml. 

berlioz_process_1_match.png

Example

Let's assume, that we've defined a service ID 'get-account' in our services.xml that matches /account/{username}.

Our app receives the following request:

GET /account/jsmith.html

Berlioz will look up the services and identify that it need to handle this URL using service 'get-account'. Additionally, it will record that the username is 'jsmith'

2. Invoke generators

What does Berlioz mean by handling a service?

First Berlioz will invoke all the generators associated with a service. A generator is a Java class which generates XML content from a request. The XML content can be sourced from a database, the file system, an external server, the result of an operation, etc...

Services can include multiple generators, typically between 1 and a half-dozen. The services.xml configuration file defines what generators to invoke for each service.

berlioz_process_2_process.png

Example

If the service 'get-account' includes the following generators:

  1. The Berlioz bundler
  2. A custom generator returning the general navigation for the site
  3. A custom generator returning the account detail for a user identified by a username
  4. The empty generator

Berlioz will invoke each of these generator in turn.

3. Generate content

Once all the generators have been successfully invoked, Berlioz will collate the content and some metadata about the service. This is the raw output.

The raw output includes:

  • the header with information about the URL, path, parameters and berlioz
  • the content for each of the generators that have been invoked 

Note

If one of the generators threw an error or instructed Berlioz to redirect the response, then the raw output may not necessarily be generated.

berlioz_process_3_output.png

Example

Following on the example above, the raw output will be:

<root service="topic" group="default">
  <header>
    <location scheme="http" host="example.org" port="80" path="/accounts/jsmith.html" query="" 
        base="http://example.org">http://example.org/accounts/jsmith.html</location>
    <path info="/accounts/jsmith" extension=".html"/>
    <http-parameters/>
    <uri-parameters>
      <parameter name="username">jsmith</parameter>
    </uri-parameters>
    <berlioz version="0.10.2" mode="local"/>
  </header>
  <content generator="org.pageseeder.berlioz.bundler.GetWebBundles" name="bundles" target="html" etag="1450227762000" status="ok">
    <script src="/script/_/global-2016-01-26-4736.min.js" bundled="true" minimized="true"/>
    <style src="/style/_/global-2016-01-26-111a.min.css" bundled="true" minimized="true"/>
  </content>
  <content generator="org.example.GetNavigation" name="nav" etag="dHjd8dhjat563" status="ok">
    <!-- Some app-specific content describing the Navigation -->
  </content>
  <content generator="org.pageseeder.GetAccount" name="account" etag="hdkjfGO9HJd03" status="ok">
    <!-- The account of details for 'jsmith' -->
  </content>
  <content generator="org.pageseeder.berlioz.generator.NoContent" name="footer" etag="nocontent" status="ok"/>
</root>

4. Transform content

If a transformation is required, Berlioz will apply XSLT onto the raw output in order to produce the final output. Berlioz will select the correct principal stylesheet module to apply based on the service and output type.

The XSLT selected by Berlioz to transform the output is determined by

  • the mediatype (usually derived from file extension)
  • the module (based on the service)

berlioz_process_4_transform.png

Example

Continuing on the previous example. If we are generating an HTML page from service 'get-account' in the default group of services.

Berlioz will process output from the XSLT in /WEB-INF/xslt/html/default.xsl

Created on , last edited on