Introduction
This example takes the very simple flow element described in the simple flow element example, and delegates all the logic to a cloud service.
Instead of the data being stored locally and processing being carried out by the flow element directly, as demonstrated in the simple flow element example, this example will call a cloud service to perform the required functionality.
Download Example
The source code used in this example is available here:
Dependencies
The aspect engine will need a dependency on the Pipeline engines package, and cloud request engine package
Select a tab to view language specific dependencies.
The dependencies needed for .NET are the
FiftyOne.Pipeline.Engines and FiftyOne.Pipeline.CloudRequestEngine NuGet packages. The only dependency needed for Java is the
pipeline.core 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.cloudrequestengine</artifactId>
<version>4.2.0</version>
</dependency>
<dependency>
<groupId>com.51degrees</groupId>
<artifactId>pipeline.engines</artifactId>
<version>4.2.0</version>
</dependency>
Data
The element data implemented in the previous example can now be upgraded to implement an aspect data.
Select a tab to view language specific aspect data implementation.
Instead of implementing
IElementData, the IStarSignData will now implement IAspectData which extends IElementData.
public interface IStarSignData : IAspectData
{
string StarSign { get; }
}
Now the internal implementation of it will implement a 'getter' and add a 'setter' for StarSign in the same way as the previous example.
internal class StarSignData : AspectDataBase, IStarSignData
{
public StarSignData(
ILogger<AspectDataBase> logger,
IPipeline pipeline,
IAspectEngine engine,
IMissingPropertyService missingPropertyService)
: base(logger, pipeline, engine, missingPropertyService)
{
}
public string StarSign
{
// Get the star sign from the internal IDictionary as a string.
get { return GetAs<string>("starsign"); }
// Add the star sign to the internal IDictionary.
set { base["starsign"] = value; }
}
}
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<? extends AspectData, ? extends AspectPropertyMetaData> 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.
Aspect Engine
Now the actual aspect engine needs to be implemented. For this, the class from the previous example will now implement the cloud aspect engine's base class.
Select a tab to view language specific aspect engine implementation.
First let's change the class to extend
CloudAspectEngineBase. 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 CloudAspectEngineBase class.
The constructor will also take a CloudRequestEngine instance to get the available properties from.
public class SimpleCloudEngine : CloudAspectEngineBase<IStarSignData>
{
public SimpleCloudEngine(
ILogger<SimpleCloudEngine> logger,
Func<IPipeline, FlowElementBase<IStarSignData, IAspectPropertyMetaData>, IStarSignData> deviceDataFactory,
CloudRequestEngine engine)
: base(logger, deviceDataFactory)
{
if (engine == null)
{
// There is no cloud request engine in the pipeline. This means
// there is no result available.
throw new PipelineConfigurationException(
$"The '{GetType().Name}' requires a 'CloudRequestEngine' " +
$"before it in the Pipeline. This engine will be unable " +
$"to produce results until this is corrected.");
}
}
Now the abstract methods can be implemented to create a functional aspect engine.
public class SimpleCloudEngine : CloudAspectEngineBase<IStarSignData>
{
public SimpleCloudEngine(
ILogger<SimpleCloudEngine> logger,
Func<IPipeline, FlowElementBase<IStarSignData, IAspectPropertyMetaData>, IStarSignData> deviceDataFactory,
CloudRequestEngine engine)
: base(logger, deviceDataFactory)
{
if (engine == null)
{
// There is no cloud request engine in the pipeline. This means
// there is no result available.
throw new PipelineConfigurationException(
$"The '{GetType().Name}' requires a 'CloudRequestEngine' " +
$"before it in the Pipeline. This engine will be unable " +
$"to produce results until this is corrected.");
}
}
public override string ElementDataKey => "starsign";
public override IEvidenceKeyFilter EvidenceKeyFilter =>
// This engine needs no evidence.
// It works from the cloud request data.
new EvidenceKeyFilterWhitelist(new List<string>());
protected override void ProcessEngine(IFlowData data, IStarSignData aspectData)
{
// Cast aspectData to StarSignData so the 'setter' is available.
StarSignData starSignData = (StarSignData)aspectData;
// Get the JSON response which the cloud request engine has
// fetched from the cloud service.
var requestData = data.Get<CloudRequestData>();
var json = requestData.JsonResponse;
// Extract data from json to the aspectData instance.
var dictionary = JsonConvert.DeserializeObject<Dictionary<string, object>>(json);
// Get the results for the star sign component.
var starSign = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
JsonConvert.PopulateObject(dictionary["starsign"].ToString(), starSign);
// Now get the values from the star sign results.
starSignData.StarSign = starSign["starsign"].ToString();
}
}
First let's change the class to extend
CloudAspectEngineBase. 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 CloudAspectEngineBase class.
The constructor will also take a CloudRequestEngine instance to get the available properties from.
public class SimpleCloudEngine extends CloudAspectEngineBase<StarSignData> {
private List<AspectPropertyMetaData> aspectProperties;
private String dataSourceTier;
public SimpleCloudEngine(
Logger logger,
ElementDataFactory<StarSignData> dataFactory) {
super(logger, dataFactory);
// Create an empty list
aspectProperties = new ArrayList<AspectPropertyMetaData>();
}
The loadAspectProperties method in this example will get the aspect properties from the CloudRequestEngine and store them. In this case we know the only property will be 'star sign', but more complex cloud engines can have many properties.
Now the abstract methods can be implemented to create a functional aspect engine.
public class SimpleCloudEngine extends CloudAspectEngineBase<StarSignData> {
private List<AspectPropertyMetaData> aspectProperties;
private String dataSourceTier;
public SimpleCloudEngine(
Logger logger,
ElementDataFactory<StarSignData> dataFactory) {
super(logger, dataFactory);
// Create an empty list
aspectProperties = new ArrayList<AspectPropertyMetaData>();
}
@Override
public List<AspectPropertyMetaData> getProperties() {
return aspectProperties;
}
@Override
public String getDataSourceTier() {
return dataSourceTier;
}
@Override
public String getElementDataKey() {
return "starsign";
}
@Override
public EvidenceKeyFilter getEvidenceKeyFilter() {
// This engine needs no evidence.
// It works from the cloud request data.
return new EvidenceKeyFilterWhitelist(new ArrayList<String>());
}
private boolean checkedForCloudEngine = false;
private CloudRequestEngine cloudRequestEngine = null;
@Override
protected void processEngine(FlowData data, StarSignData aspectData) {
// Cast aspectData to StarSignDataDefault, so the 'setter' is available.
StarSignDataInternal starSignData = (StarSignDataInternal)aspectData;
if (checkedForCloudEngine == false) {
cloudRequestEngine = getRequestEngine().getInstance();
checkedForCloudEngine = true;
}
CloudRequestData requestData = data.getFromElement(cloudRequestEngine);
String json = requestData.getJsonResponse();
// Extract data from json to the aspectData instance.
JSONObject jsonObj = new JSONObject(json);
JSONObject deviceObj = jsonObj.getJSONObject("starsign");
starSignData.setStarSign(deviceObj.getString("starsign"));
}
@Override
protected void unmanagedResourcesCleanup() {
// Nothing to clean up here.
}
}
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 cloud request aspect engine.
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
CloudAspectEngineBuilderBase.
public class SimpleCloudEngineBuilder : CloudAspectEngineBuilderBase<SimpleCloudEngineBuilder, SimpleCloudEngine>
{
private ILoggerFactory _loggerFactory;
private CloudRequestEngine _engine;
public SimpleCloudEngineBuilder(
ILoggerFactory loggerFactory,
CloudRequestEngine engine)
{
_loggerFactory = loggerFactory;
_engine = engine;
}
public SimpleCloudEngine Build()
{
return BuildEngine();
}
protected override SimpleCloudEngine NewEngine(List<string> properties)
{
return new SimpleCloudEngine(
_loggerFactory.CreateLogger<SimpleCloudEngine>(),
CreateData,
_engine);
}
private IStarSignData CreateData(IPipeline pipeline, FlowElementBase<IStarSignData, IAspectPropertyMetaData> engine)
{
return new StarSignData(
_loggerFactory.CreateLogger<StarSignData>(),
pipeline,
(IAspectEngine)engine,
MissingPropertyService.Instance);
}
}
As this aspect engine is using a data file, the builder can make use of the logic in the
CloudAspectEngineBuilderBase.
public class SimpleCloudEngineBuilder
extends CloudAspectEngineBuilderBase<
SimpleCloudEngineBuilder,
SimpleCloudEngine> {
public SimpleCloudEngineBuilder(
ILoggerFactory loggerFactory) {
super(loggerFactory);
}
@Override
protected SimpleCloudEngine newEngine(List<String> properties) {
return new SimpleCloudEngine(
loggerFactory.getLogger(SimpleCloudEngine.class.getName()),
new ElementDataFactory<StarSignData>() {
@Override
public StarSignData create(
FlowData flowData,
FlowElement<StarSignData, ?> flowElement) {
return new StarSignDataInternal(
loggerFactory.getLogger(StarSignDataInternal.class.getName()),
flowData,
(SimpleCloudEngine)flowElement,
MissingPropertyServiceDefault.getInstance());
}
});
}
public SimpleCloudEngine build() throws Exception {
return buildEngine();
}
}
Usage
Select a tab to view language specific usage.
This new aspect engine can now be added to a Pipeline along with a
CloudRequestEngine, and used like:
// Construct a cloud request engine using the example endpoint for
// the example engine to use.
var cloudRequestEngine =
new CloudRequestEngineBuilder(_loggerFactory, new HttpClient())
.SetEndPoint("http://51degrees.com/starsign/api/")
.SetResourceKey("cloudexample")
.Build();
// Construct the example engine.
var starSignEngine =
new SimpleCloudEngineBuilder(_loggerFactory, cloudRequestEngine)
.Build();
// Construct the pipeline with the example engine and the cloud
// request engine it requires.
var pipeline = new PipelineBuilder(_loggerFactory)
.AddFlowElement(cloudRequestEngine)
.AddFlowElement(starSignEngine)
.Build();
var dob = "18/12/1992";
// Create a new flow data.
var flowData = pipeline.CreateFlowData();
// Add the evidence and process the data.
flowData
.AddEvidence("date-of-birth", dob)
.Process();
// Now get the result of the processing.
Console.WriteLine($"With a date of birth of {dob}, " +
$"your star sign is {flowData.Get<IStarSignData>().StarSign}.");
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 along with a
CloudRequestEngine, and used like:
CloudRequestEngine cloudRequestEngine =
new CloudRequestEngineBuilder(loggerFactory, httpClient)
.setEndpoint("http://51degrees.com/starsign/api/")
.setResourceKey("cloudexample")
.build();
SimpleCloudEngine ageElement =
new SimpleCloudEngineBuilder(
loggerFactory)
.build();
Pipeline pipeline = new PipelineBuilder(loggerFactory)
.addFlowElement(cloudRequestEngine)
.addFlowElement(ageElement)
.build();
String dob = "18/12/1992";
try (FlowData flowData = pipeline.createFlowData()) {
flowData
.addEvidence("date-of-birth", dob)
.process();
System.out.println("With a date of birth of " +
dob +
", your star sign is " +
flowData.getFromElement(ageElement).getStarSign() + ".");
}
to give an output of:
With a date of birth of 18/12/1992, your star sign is Sagittarius.
Next Steps
The Custom On-premise Engine example shows you how to build an on premise engine to perform the functionality that was executed by the cloud engine here.