This Example shows how to configure the usage sharing feature of the Pipeline API. Usage sharing is a feature that allows you to share details of the requests you are processing with 51Degrees.

Usage sharing works by adding a 'ShareUsageElement' to the pipeline. This element will collect evidence values as they pass through, periodically sending them to 51Degrees for processing.

If you want to know more about usage sharing, and why you should consider using it, see the usage sharing feature page.

Usage sharing is enabled by default if using a pipeline builder that is derived from FiftyOnePipelineBuilder. For instance, the DeviceDetectionPipelineBuilder. In this example, we show how to add a ShareUsageElement to a Pipeline using configuration.

As with all ElementBuilders, this can also be handled in code, using the ShareUsageBuilder. The commented section in the example demonstrates this.

The 51d.xml file contains all the configuration options. These are all optional, so each can be omitted if the default for that option is sufficient:

1 <?xml version="1.0" encoding="utf-8" ?>

2 <!--

3 ~ This Original Work is copyright of 51 Degrees Mobile Experts Limited.

5 ~ Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.

6 ~

7 ~ This Original Work is licensed under the European Union Public Licence

8 ~ (EUPL) v.1.2 and is subject to its terms as set out below.

9 ~

10 ~ If a copy of the EUPL was not distributed with this file, You can obtain

11 ~ one at https://opensource.org/licenses/EUPL-1.2.

12 ~

13 ~ The 'Compatible Licences' set out in the Appendix to the EUPL (as may be

14 ~ amended by the European Commission) shall be deemed incompatible for

15 ~ the purposes of the Work and the provisions of the compatibility

16 ~ clause in Article 5 of the EUPL shall not apply.

17 ~

18 ~ If using the Work as, or as part of, a network application, by

19 ~ including the attribution notice(s) required under Article 5 of the EUPL

20 ~ in the end user terms of the application under an appropriate heading,

21 ~ such notice(s) shall fulfill the requirements of that article.

22 -->

23

24 <PipelineOptions>

25 <Elements>

26 <Element>

27 <BuildParameters>

28 <SharePercentage>0.1</SharePercentage>

29 <ShareUsageUrl>https://devices-v4.51degrees.com/new.ashx</ShareUsageUrl>

30 <MinimumEntriesPerMessage>50</MinimumEntriesPerMessage>

31 <RepeatEvidenceIntervalMinutes>10</RepeatEvidenceIntervalMinutes>

32 <TrackSession>false</TrackSession>

33 <SessionCookieName></SessionCookieName>

34 <IncludedQueryStringParameters>parameter1,parameter2</IncludedQueryStringParameters>

35 <BlockedHttpHeader>mySecretHeader</BlockedHttpHeader>

36 <IgnoreFlowDataEvidenceFilter>evidenceKey:evidenceValue</IgnoreFlowDataEvidenceFilter>

37 <AddTimeout>5</AddTimeout>

38 <TakeTimeout>100</TakeTimeout>

39 </BuildParameters>

40 <BuilderName>ShareUsage</BuilderName>

41 </Element>

42 </Elements>

43 </PipelineOptions>

For details of what each setting does, see the reference documentation for the share usage builder

This example is available in full on GitHub.

Expected output:

Constructing pipeline from configuration file.

Pipeline created with share usage element. Evidence processed

with this pipeline will now be shared with 51Degrees using the

specified configuration.

/*

* This Original Work is copyright of 51 Degrees Mobile Experts Limited.

* Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.

*

* This Original Work is licensed under the European Union Public Licence

* (EUPL) v.1.2 and is subject to its terms as set out below.

*

* If a copy of the EUPL was not distributed with this file, You can obtain

* one at https://opensource.org/licenses/EUPL-1.2.

*

* The 'Compatible Licences' set out in the Appendix to the EUPL (as may be

* amended by the European Commission) shall be deemed incompatible for

* the purposes of the Work and the provisions of the compatibility

* clause in Article 5 of the EUPL shall not apply.

*

* If using the Work as, or as part of, a network application, by

* including the attribution notice(s) required under Article 5 of the EUPL

* in the end user terms of the application under an appropriate heading,

* such notice(s) shall fulfill the requirements of that article.

*/

package pipeline.developerexamples.usagesharing;

import fiftyone.pipeline.core.configuration.PipelineOptions;

import fiftyone.pipeline.core.data.FlowData;

import fiftyone.pipeline.core.flowelements.Pipeline;

import fiftyone.pipeline.core.flowelements.PipelineBuilder;

import fiftyone.pipeline.engines.fiftyone.flowelements.ShareUsageElement;

import fiftyone.pipeline.engines.fiftyone.flowelements.ShareUsageBuilder;

import fiftyone.pipeline.engines.services.HttpClient;

import fiftyone.pipeline.engines.services.HttpClientDefault;

import org.slf4j.ILoggerFactory;

import org.slf4j.LoggerFactory;

import jakarta.xml.bind.JAXBContext;

import jakarta.xml.bind.Unmarshaller;

import java.io.File;

public class Main {

private static final ILoggerFactory loggerFactory =

LoggerFactory.getILoggerFactory();

// The HTTP service that will be used to send usage

// data back to 51Degrees.

private static final HttpClient http = new HttpClientDefault();

public static class Example {

public void run() throws Exception {

System.out.println("Constructing pipeline from configuration file.");

System.out.println();

// Create the configuration object from an XML file

File file = new File(getClass().getClassLoader().getResource("51d.xml").getFile());

JAXBContext jaxbContext = JAXBContext.newInstance(PipelineOptions.class);

Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();

// Bind the configuration to a pipeline options instance

PipelineOptions options = (PipelineOptions)unmarshaller.unmarshal(file);

// Build a new Pipeline from the configuration.

Pipeline pipeline = new PipelineBuilder()

.addService(http)

.buildFromConfiguration(options);

// Alternatively, the commented code below shows how to

// configure the ShareUsageElement in code, rather than

// using a configuration file.

//ShareUsageElement usageElement = new ShareUsageBuilder(loggerFactory, http)

// .setSharePercentage(0.01)

// .setMinimumEntriesPerMessage(2500)

// .build();

//Pipeline pipeline = new PipelineBuilder()

// .addFlowElement(usageElement)

// .build();

System.out.println(

"Pipeline created with share usage element. Evidence processed " +

"with this pipeline will now be periodically shared with " +

"51Degrees using the specified configuration.");

}

public static void main(String[] args) throws Exception {

new Example().run();

}

51Degrees Pipeline Java 4.4

usagesharing/Main.java