\r\n

51Degrees API Documentation  4.4

Introduction

Rather than setting all build options and flow elements explicitly in code form, it is often preferable to make the Pipeline configurable without recompiling. A pipeline builder allows this via its 'BuildFromConfiguration' method.

See the Specification for more technical details.

Usage

A configuration can be parsed manually from XML, JSON, or any other source and given to a pipeline builder. Alternatively, in web integrations, a configuration file is loaded automatically.

Note, the possible format of the configuration file varies greatly between languages, with some languages having many options and others only having one. Where possible, we recommend using JSON as the simplest and most transferable configuration format; JSON is also supported by the PHP and Node.js bindings, where XML is not. In contrast, it should be noted that Java only supports XML configuration files.

Parsing XML

Select a language for an example of parsing XML.

Parsing JSON

Select a language for an example of parsing JSON.

Example configuration

Select a file format to view an example configuration.

Rules for building from a configuration file

The core build from configuration logic ultimately calls the same configuration methods, on the same builders as the developer does if they configure the Pipeline in code.

There are several rules that govern how a value in a configuration file is mapped to a builder or configuration method:

Element builder names

The element builder name is used to determine the element builder that we want to use. Each of the following is tried in turn to find a builder that matches the supplied name:

  1. Case insensitive match on type name (e.g. 'MyElementBuilder' matches a type with that name).
  2. Case insensitive match on type name suffixed with 'builder' (e.g. 'MyElement' matches a type called 'MyElementBuilder').
  3. Where the language allows it, match on some alternative name for the builder.

Element build parameters

The key value of each entry in the 'build parameters' list associated with each element is used to determine the method to call on the element builder. Each of the following is tried in turn to find a method that matches the supplied name:

  1. Case insensitive match on method name (e.g. 'SetCacheSize' matches a method with that name).
  2. Case insensitive match on method name prefixed with 'set' (e.g. 'CacheSize' matches a method called 'SetCacheSize').
  3. Where the language allows it, match on some alternative name for the method.

The value part of each entry in the 'build parameters' list is then passed to the matching method as a parameter. For strongly-types languages, this may also involve parsing a string value from the configuration into the required type.

If there are any build parameters for which a method cannot be found, they will be used to set parameters on the 'Build' method once configuration is complete. In this case, a simple case-insensitive match is performed to determine the parameter value to set.

Pipeline build parameters

Pipeline build parameters work in the same way as element build parameters but they are used to call configuration methods on the pipeline builder instead of the element builder.

See above for all the rules governing this.

Alternative naming details

Some languages have a mechanism for specifying alternative names for builders and methods. These can be used to match against supplied configuration options.

Select a language for information of specifying an alternative name for element builders and configuration methods.

Internals

The exact internal mechanics of the builder will depend on the language being used. Wherever possible, the rules for mapping are consistent between languages but this cannot always be achieved.

Select a language for more details of the internals of build from configuration.