\r\n

51Degrees API Documentation  4.4

Search

Documentation

• Concepts
• Configuration
• Builders
• Building from Configuration

Building from Configuration

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

C# Java

Select a language for an example of parsing XML.

var config = new ConfigurationBuilder()

.AddXmlFile("configuration.xml")

.Build();

PipelineOptions options = new PipelineOptions();

var section = config.GetRequiredSection("PipelineOptions");

// Use the 'ErrorOnUnknownConfiguration' option to warn us if we've got any

// misnamed configuration keys.

section.Bind(options, (o) => { o.ErrorOnUnknownConfiguration = true; });

IPipeline pipeline = new PipelineBuilder(loggerFactory)

.BuildFromConfiguration(options);

PipelineOptions options = PipelineOptionsFactory.getOptionsFromFile("configuration.xml");

Pipeline pipeline = new PipelineBuilder(loggerFactory)

.buildFromConfiguration(options);

Parsing JSON

C# PHP Node.js

Select a language for an example of parsing JSON.

var config = new ConfigurationBuilder()

.AddJsonFile("configuration.json")

.Build();

PipelineOptions options = new PipelineOptions();

var section = config.GetRequiredSection("PipelineOptions");

// Use the 'ErrorOnUnknownConfiguration' option to warn us if we've got any

// misnamed configuration keys.

section.Bind(options, (o) => { o.ErrorOnUnknownConfiguration = true; });

IPipeline pipeline = new PipelineBuilder(loggerFactory)

.BuildFromConfiguration(options);

use fiftyone\pipeline\core\PipelineBuilder;
$builder = new PipelineBuilder();
$pipeline = $builder->buildFromConfig($configFile)->build();

const pipeline = new FiftyOneDegreesGeoLocation.GeoLocationPipelineBuilder({resourceKey:localResourceKey});

pipeline.buildFromConfigurationFile(configFilePath);

Example configuration

XML JSON

Select a file format to view an example configuration.

There is a sample file demonstrating all configuration options for Java on GitHub.

Configure a Pipeline with a flow element named 'MyElement' with a build parameter, and set the Pipeline to suppress process exceptions.

<PipelineOptions>

<Elements>

<Element>

<BuilderName>MyElementBuilder</BuilderName>

<BuildParameters>

<MyBuildParameter>a value for the element</MyBuildParameter>

</BuildParameters>

</Element>

</Elements>

<BuildParameters>

<SuppressProcessExceptions>true</SuppressProcessExceptions>

</BuildParameters>

</PipelineOptions>

Configure a Pipeline with a flow element named 'MyElement' with a build parameter, and set the Pipeline to suppress process exceptions.

Note that for use in node.js, BuilderName and BuilderParameters should be replaced by elementName and elementParameters.

There is a sample file demonstrating all configuration options for .NET on GitHub.

{

"PipelineOptions": {

"Elements": [

{

"BuilderName": "MyElementBuilder",

"BuildParameters": {

"MyBuildParameter": "a value for the element"

}

}

],

"BuildParameters": {

"SuppressProcessExceptions": true

}

}

}

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.

C# Java

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

The AlternateNameAttribute can be used to decorate element builder classes as well as configuration methods on an element builder. This can be used to specify one or more other names to match on when building from configuration.

The ElementBuilder(alternateName) attribute can be used to decorate element builder classes. This can be used to specify one or more other names to match when buiding from configuration.

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.

C# PHP Node.js

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

In .NET, pipeline builder relies on reflection to find the correct builder to build the flow elements required by the configuration. For this reason, it is necessary for the libraries that contain the element builders for each flow element to be loaded. This can be done in a number of ways:

• loading the library by calling a method in code;
• adding a library to a config file to be loaded;

For example:

Assembly.Load("FiftyOne.DeviceDetection.Hash.Engine.OnPremise");

Additionally, the pipeline builder will need to know how to supply any dependencies required by the element builders it creates.

By default, the pipeline builder will call a constructor on element builder that takes an ILoggerFactory if one is available. If not, it will call the default constructor - if one is available.

If neither are available then the pipeline builder will be unable to create the element builder.

This can be resolved by passing an IServiceProvider to the pipeline builder on construction that is populated with instances of the services that element builders will require.

PHP will load elements named in BuilderName as if they were specified in a use statement, so for example:

"BuilderName": "fiftyone\\pipeline\\cloudrequestengine\\CloudRequestEngine"

Node will load elements named in ElementName as if they were specified in a require statement, so for example:

"ElementName": "fiftyone.pipeline.cloudrequestengine"

Generated by doxygen 1.8.15