Berlioz

There are a number of predefined properties that can be defined to configure how Berlioz works.

Although they are also part of Berlioz core properties, the bundler properties are documented elsewhere.

Summary

The following properties are defined by Berlioz.

Property reference

All the properties below are prefixed by berlioz.

Property control-key

The property specifies a value, a control key, that is used to restrict the usage of global parameters.

Property http.compression

This property instructs Berlioz to use HTTP compression to the content response of services using the gzip content encoding. The HTTP headers will be updated accordingly.

HTTP compression is not systematic, even if this property is set to true, Berlioz use compression if:

• the HTTP client supports the gzip (based on Accept-Encoding header)
• the mediatype of the response is likely to compress well (text/*, */xml, */*+xml, */javascript and */json)

The recommended setting is to enable this property as the performance cost of compression is negligible, but it can save on bandwidth for client.

Property http.get-via-post

When enabled, this property will automatically forward HTTP POST requests to GET requests if there is no specific service for POST.

This is useful in cases when the same service could be used for both GET and POST requests.  When this property is set to false, a POST on the service that is defined only for GET request will result in a "405 Method not allowed" error.

For example, if a search service accepts both HTTP methods so that criteria can be specified in the content request rather than as query parameters. The service only needs to be defined once in the services.

The recommended setting is to enable this feature.

Property http.max-age

This property only applies to cacheable responses. In the absence of a specific cache-control value in the global configuration or in the services.xml. This value will be used to generate the Cache-Control HTTP header:

Cache-Control: max-age=60, must-revalidate

The default value is set to 60 seconds, in the absence of any other cache control configuration, successive requests from the same client to the same service within a minute will return a "302 Not Modified" HTTP response.

Property http.cache-control

This property defines the global cache control directive to be used as the Cache-Control HTTP header for cacheable responses.

When it is defined, it overrides the berlioz.http.max-age property, but it is overridden by any cache control defined in the services.xml.

This property is intended as fallback control control for all services in the application. Developers should specify a value that reflect the default HTTP caching requirements for their application i.e. applicable to most services and override this value when necessary in the services.xml.

Property http.errors.handle

This property defines how Berlioz is supposed to handle errors.

When set to true, Berlioz will directly use the Berlioz error handler to return a response to the client. If set to false, Berlioz will simply let the Web container handle the error; in other words, it will rely on the errors pages defined using the <error> element in the Web descriptor. 

Errors occurs in the following situations:

• A service is unavailable because the service definition in services.xml references a generator which could not be found (HTTP 503 Service not available)
• The request URL matched existing services in services.xml but it did not match any service for that HTTP method (HTTP 405 Method not allowed)
• No service matching the request URL could be found (HTTP 404 Not found)
• An exception was thrown in a generator and Berlioz was instructed not to catch it because berlioz.error.generator-catch was set to false.

During the early stages of development it is often simpler to let Berlioz handle errors as it will provide as much information as possible to help diagnose and fix issues. In production it is recommended that developers define a proper error strategy at the Web container level.

Property error.generator-catch

This property define whether Berlioz catch errors occurring within generators or not.

When set to true, Berlioz will catch any error thrown within generators and rewrite the XML response of the generator to include the error details so that they can be handled by the front-end.

<berlioz-exception class="[class]">
  <message>[message]</message>
  <stack-trace>[exception]</stack-trace>
  <cause>[cause exception as XML (if any)]</cause>
  <location line="[line]" column="[column]" />
</berlioz-exception>

When set to false, the error will percolate to Berlioz and will cause Berlioz to handle the error or send the error to the Web container.

This property is useful in cases, when we never want to expose end-users to error messages. However, they may leave errors undetected, since they will only available in the logs and will rely on the XSLT to handle the error.

Property xml.header.version

This property defines the format of the <header> element in the Berlioz raw output.

Property xml.parse-strict

This property defines whether warnings when parsing XML should be reported as errors, hence making parsing stricter.

The default and recommended value is true. This option may no longer be available in future versions of Berlioz.

Property xslt.cache

This property defines whether Berlioz should cache the XSLT templates. When this property is set to true, the XSLT templates are cached and reused for every request.

They can always be reloaded using the clear-xslt-cache or berlioz-reload global parameters.

During the early stages of development, it is more convenient to set this property to false so that changes in XSLT are reflected for every request.

In production, this property should be set to true, to avoid of the performance cost of reloading XSLT templates that are unlikely not change.

Created on 17 December 2015 , last edited on 17 December 2015 at 18:40