\r\n

51Degrees Pipeline Documentation  4.1Newer Version 4.4

Search

Documentation

• Examples
• Examples with a custom flow element
• Custom On-Premise Engine

Custom On-Premise Engine

Introduction

This example takes the very simple flow element described in the simple flow element example, and adds a data file, upgrading the flow element to an aspect engine.

Instead of storing data statically, as the simple flow element example did, this example will store it in a data file which will be loaded and can also be updated.

Download Example

The source code used in this example is available here:

• C# Visual Studio project
• Java project
• Node.js project

Dependencies

The aspect engine will need a dependency on the Pipeline engines package now as it is implementing an aspect engine rather than a flow element.

C# Java Node.js

Select a tab to view language specific dependencies.

The only dependency needed for .NET is the FiftyOne.Pipeline.Engines NuGet package.

The only dependency needed for Java is the pipeline.engines Maven package from com.51degrees. To include this, add the following to the <dependencies> section of the project's pom.xml:

<dependency>

<groupId>com.51degrees</groupId>

<artifactId>pipeline.engines</artifactId>

<version>4.1.0</version>

</dependency>

Add a dependency to the fiftyone.pipeline.engines NPM package to the package.json, and required it in the source with require("fiftyone.pipeline.engines").

Data

The element data implemented in the previous example can now be upgraded to implement an aspect data.

C# Java Node.js

Select a tab to view language specific aspect data implementation.

Instead of implementing IElementData, the IStarSignData will now implement IAspectData which extends IElementData.

Now the internal implementation of it will implement a 'getter' and add a 'setter' for StarSign in the same way as the previous example.

Instead of implementing ElementData, the StarSignData will now implement AspectData which extends ElementData.

public interface StarSignData extends AspectData {

String getStarSign();

}

Now the internal implementation of it will implement a 'getter' and add a 'setter' for StarSign in the same way as the previous example.

class StarSignDataInternal extends AspectDataBase implements StarSignData {

public StarSignDataInternal(

Logger logger,

FlowData flowData,

AspectEngine engine,

MissingPropertyService missingPropertyService) {

super(logger, flowData, engine, missingPropertyService);

}

@Override

public String getStarSign() {

return getAs("starsign", String.class);

}

void setStarSign(String starSign) {

put("starsign", starSign);

}

}

Note that this concrete implementation of StarSignData sits in the same package as the aspect engine, not the StarSignData interface, as it only needs to be accessible by the aspect engine.

Node's implementation of element data does not require concrete getters for IDE autocompletion, so aspectDataDictionary can be used.

Aspect Engine

Now the actual aspect engine needs to be implemented. For this, the class from the previous example will now implement the on-premise engine's base class.

C# Java Node.js

Select a tab to view language specific aspect engine implementation.

First let's change the class to extend OnPremiseAspectEngineBase (which partially implements IOnPremiseAspectEngine). This has the type arguments of IStarSignData - the interface extending aspect data which will be added to the flow data, and IAspectPropertyMetaData - instead of IElementPropertyMetaData.

The existing constructor needs to change to match the OnPremiseAspectEngineBase class. So it takes the additional arguments of a data file path, and a temporary data file path. This is the location of the data file that the aspect engine will use, and where to make a temporary copy if required.

The constructor will also read the data file containing the star signs into memory. This is done in another method so that it can also be used by the RefreshData method when a new data file is downloaded (this is not applicable for this example as star sign data will not change).

The Init method in this example will simply read a CSV file with the start and end dates of each star sign, which looks like:

Aries,21/03,19/04

Taurus,20/04,20/05

Gemini,21/05,20/06

Cancer,21/06,22/07

...

and add each to a list of a new class named StarSign which has the following simple implementation:

Note that the year of the start and end date are both set to 1, as the year should be ignored, but the year 0 cannot be used in a DateTime.

The new Init method looks like this:

Now the abstract methods can be implemented to create a functional aspect engine.

First let's change the class to extend OnPremiseAspectEngineBase (which partially implements OnPremiseAspectEngine). This has the type arguments of StarSignData - the interface extending aspect data which will be added to the flow data, and AspectPropertyMetaData - instead of ElementPropertyMetaData.

The existing constructor needs to change to match the OnPremiseAspectEngineBase class. So it takes the additional arguments of a data file path, and a temporary data file path. This is the location of the data file that the aspect engine will use, and where to make a temporary copy if required.

The constructor will also read the data file containing the star signs into memory. This is done in another method so that it can also be used by the refreshData method when a new data file is downloaded (this is not applicable for this example as star sign data is static).

public class SimpleOnPremiseEngine extends OnPremiseAspectEngineBase<StarSignData, AspectPropertyMetaData> {

public SimpleOnPremiseEngine(

String dataFile,

Logger logger,

ElementDataFactory<StarSignData> elementDataFactory,

String tempDir) throws IOException {

super(logger, elementDataFactory, tempDir);

this.dataFile = dataFile;

init();

}

The init method in this example will simply read a CSV file with the start and end dates of each star sign, which looks like:

Aries,21/03,19/04

Taurus,20/04,20/05

Gemini,21/05,20/06

Cancer,21/06,22/07

...

and add each to a list of a new class named StarSign which has the following simple implementation:

public class StarSign {

private final Calendar end;

private final Calendar start;

private final String name;

public StarSign(String name, String start, String end) {

this.name = name;

this.start = Calendar.getInstance();

String[] startDate = start.split("/");

this.start.set(

0,

Integer.parseInt(startDate[1]) - 1,

Integer.parseInt(startDate[0]));

this.end = Calendar.getInstance();

String[] endDate = end.split("/");

this.end.set(

0,

Integer.parseInt(endDate[1]) - 1,

Integer.parseInt(endDate[0]));

}

public String getName() {

return name;

}

public Calendar getStart() {

return start;

}

public Calendar getEnd() {

return end;

}

}

Note that the year of the start and end date are both set to 0, as the year should be ignored.

The new init method looks like this:

private void init() throws IOException {

List<StarSign> starSigns = new ArrayList<>();

try (FileReader fileReader = new FileReader(dataFile)) {

try (BufferedReader reader = new BufferedReader(fileReader)) {

String line;

while ((line = reader.readLine()) != null) {

String[] columns = line.split(",");

starSigns.add(new StarSign(

columns[0],

columns[1],

columns[2]));

}

}

}

this.starSigns = starSigns;

}

Now the abstract methods can be implemented to create a functional aspect engine.

public class SimpleOnPremiseEngine extends OnPremiseAspectEngineBase<StarSignData, AspectPropertyMetaData> {

public SimpleOnPremiseEngine(

String dataFile,

Logger logger,

ElementDataFactory<StarSignData> elementDataFactory,

String tempDir) throws IOException {

super(logger, elementDataFactory, tempDir);

this.dataFile = dataFile;

init();

}

private final String dataFile;

private List<StarSign> starSigns;

private void init() throws IOException {

List<StarSign> starSigns = new ArrayList<>();

try (FileReader fileReader = new FileReader(dataFile)) {

try (BufferedReader reader = new BufferedReader(fileReader)) {

String line;

while ((line = reader.readLine()) != null) {

String[] columns = line.split(",");

starSigns.add(new StarSign(

columns[0],

columns[1],

columns[2]));

}

}

}

this.starSigns = starSigns;

}

@Override

public String getTempDataDirPath() {

return dataFile;

}

@Override

public Date getDataFilePublishedDate(String dataFileIdentifier) {

return null;

}

@Override

public Date getDataFileUpdateAvailableTime(String dataFileIdentifier) {

return null;

}

@Override

public void refreshData(String dataFileIdentifier) {

try {

init();

} catch (IOException e) {

logger.warn("There was an exception refreshing the data file" +

"'" + dataFileIdentifier + "'",

e);

}

}

@Override

public void refreshData(String dataFileIdentifier, byte[] data) {

// Lets not implement this logic in this example.

}

@Override

protected void processEngine(FlowData data, StarSignData aspectData) throws Exception {

// Cast the StarSignData to StarSignDataInternal so the 'setter' is available.

StarSignDataInternal starSignData = (StarSignDataInternal)aspectData;

TryGetResult<Date> date = data.tryGetEvidence("date-of-birth", Date.class);

if (date.hasValue()) {

// "date-of-birth" is there, so set the star sign.

Calendar dob = Calendar.getInstance();

dob.setTime(date.getValue());

Calendar monthAndDay = Calendar.getInstance();

monthAndDay.set(

0,

dob.get(Calendar.MONTH),

dob.get(Calendar.DATE));

for (StarSign starSign : starSigns) {

if (monthAndDay.compareTo(starSign.getStart()) >= 0 &&

monthAndDay.compareTo(starSign.getEnd()) <= 0) {

starSignData.setStarSign(starSign.getName());

break;

}

}

}

else

{

// "date-of-birth" is not there, so set the star sign to unknown.

starSignData.setStarSign("Unknown");

}

}

@Override

public String getElementDataKey() {

// The StarSignData will be stored with the key "starsign" in the FlowData.

return "starsign";

}

@Override

public EvidenceKeyFilter getEvidenceKeyFilter() {

// The only item of evidence needed is "date-of-birth".

return new EvidenceKeyFilterWhitelist(

Collections.singletonList("date-of-birth"),

String.CASE_INSENSITIVE_ORDER);

}

@Override

public List<AspectPropertyMetaData> getProperties() {

// The only property which will be returned is "starsign" which will be

// an String.

return Collections.singletonList(

(AspectPropertyMetaData) new AspectPropertyMetaDataDefault(

"starsign",

this,

"starsign",

String.class,

Collections.singletonList("free"),

true));

}

@Override

public String getDataSourceTier() {

return "free";

}

@Override

protected void unmanagedResourcesCleanup() {

// Nothing to clean up here.

}

}

First let's change the class to extend engine.

The existing constructor needs to change to match the engine class. So it takes the additional argument of a data file path. This is the location of the data file that the aspect engine will use.

The constructor will also read the data file containing the star signs into memory. This is done in another method so that it can also be used when a new data file is downloaded (this is not applicable for this example as star sign data is static).

The refresh method in this example will simply read a JSON file with the start and end dates of each star sign, which looks like:

[

[

"Aries",

"21/03",

"19/04"

],

[

"Taurus",

"20/04",

"20/05"

],

...

and parse into objects.

The new refresh method looks like this:

Now the abstract methods can be implemented to create a functional aspect engine.

Builder

Now the aspect engine needs one final thing, an element builder to construct it. This needs to provide the aspect engine with a logger and an aspect data factory as in the previous example. However, it also now needs a data file.

C# Java Node.js

Select a tab to view language specific element builder implementation.

As this aspect engine is using a data file, the builder can make use of the logic in the SingleFileAspectEngineBuilderBase.

As this aspect engine is using a data file, the builder can make use of the logic in the SingleFileAspectEngineBuilderBase.

public class SimpleOnPremiseEngineBuilder

extends SingleFileAspectEngineBuilderBase<

SimpleOnPremiseEngineBuilder,

SimpleOnPremiseEngine> {

public SimpleOnPremiseEngineBuilder(ILoggerFactory loggerFactory) {

super(loggerFactory);

}

@Override

protected SimpleOnPremiseEngine newEngine(List<String> properties) {

if (dataFileConfigs.size() != 1)

{

throw new RuntimeException(

"This builder requires one and only one configured file " +

"but it has " + dataFileConfigs.size());

}

DataFileConfiguration config = dataFileConfigs.get(0);

try {

return new SimpleOnPremiseEngine(

config.getDataFilePath(),

loggerFactory.getLogger(SimpleOnPremiseEngine.class.getName()),

new ElementDataFactory<StarSignData>() {

@Override

public StarSignData create(

FlowData flowData,

FlowElement<StarSignData, ?> flowElement) {

return new StarSignDataInternal(

loggerFactory.getLogger(StarSignDataInternal.class.getName()),

flowData,

(SimpleOnPremiseEngine)flowElement,

MissingPropertyServiceDefault.getInstance());

}

},

tempDir);

} catch (IOException e) {

throw new RuntimeException(e);

}

}

@Override

public SimpleOnPremiseEngineBuilder setPerformanceProfile(Constants.PerformanceProfiles profile) {

// Lets not implement multiple performance profiles in this example.

return this;

}

}

The Node implementation does not use separate builder classes. Instead the options are provided by optional constructor parameters.

Usage

C# Java Node.js

Select a tab to view language specific usage.

This new aspect engine can now be added to a Pipeline and used like:

to give an output of:

With a date of birth of 18/12/1992, your star sign is Sagittarius.

This new aspect engine can now be added to a Pipeline and used like:

SimpleOnPremiseEngine starSignEngine =

new SimpleOnPremiseEngineBuilder(loggerFactory)

.setAutoUpdate(false)

.build(

Main.class.getClassLoader().getResource("starsigns.csv").getPath(),

false);

Pipeline pipeline = new PipelineBuilder(loggerFactory)

.addFlowElement(starSignEngine)

.build();

Calendar dob = Calendar.getInstance();

dob.set(1992, Calendar.DECEMBER, 18);

FlowData flowData = pipeline.createFlowData();

flowData

.addEvidence("date-of-birth", dob.getTime())

.process();

System.out.println("With a date of birth of " +

new SimpleDateFormat("yyyy/MM/dd").format(dob.getTime()) +

", your star sign is " +

flowData.getFromElement(starSignEngine).getStarSign() + ".");

to give an output of:

With a date of birth of 18/12/1992, your star sign is Sagittarius.

This new aspect engine can now be added to a Pipeline and used like:

To print the star sign of the user.

Next Steps

The Custom Client-Side Evidence example shows how you can build a custom engine that can take evidence supplied by the client.

Generated by doxygen 1.8.15