Plug-in Java API

The Concurrent Processing Framework Plug-in API for Java (1.6+) allows developers to create business application plug-ins that can be deployed to the CPF web services.

package ca.bc.gov.open.cpf.plugin.api

The Concurrent Processing Framework Java Plug-in API.

annotation AllowedValues

The AllowedValues method annotation defines the list of valid values for a JobParameter or RequestParameter . The annotation can only be defined on a setXXX method which has either the JobParameter or RequestParameter annotations.

The list of allowed values are encoded as strings. The string values will be converted to the data type of the parameter on the setXXX method.

The list of allowed values is returned with the parameter descriptions in the business application specifications web services.

The list of allowed values is used to Construct a new select list field on the job submission form. If the parameter is not required the select field will include "-" to indicate the null (not selected) value.

The following code fragment shows an example of using the API.

@AllowedValues(value = {
  "MD5",
  "SHA"
})
@JobParameter
@RequestParameter
public void setAlgorithmName(final String algorithmName) {
  this.algorithmName = algorithmName;
}
NameTypeDefaultDescription
value String[] - The list of allowed values encoded as strings. The string values will be converted to the data type of the parameter.

annotation BusinessApplicationPlugin

The BusinessApplicationPlugin annotation marks a Java class as a CPF business application plug-in. The plug-in class must have the public keyword, be defined in a separate Java file, must not be in the default package (must have a package declaration) and must not have the final keyword.

The instance of the plug-in is executed within a single thread so does not need to be synchronized. Any services that it uses must however be thread safe as they will be used by multiple instances of the plug-in in different threads.

NOTE: An instance of the plug-in class is created for each request processed by the plug-in. Therefore state will not be maintained between requests it must not include the initialization of any resources that have significant overhead to create. These should be defined as spring beans and made available to the plug-in using spring dependency injection. If there are data structures that vary based on the parameters to a request then these can be created within the plug-in.

The following code fragment shows the implementation of a plug-in class using all of the annotation elements.

package ca.bc.gov.demo;

import ca.bc.gov.open.cpf.plugin.api.BusinessApplicationPlugin;

@BusinessApplicationPlugin(
  name                    = "Demo",
  packageName             = "ca.bc.gov.demo",
  title                   = "Demonstration Plug-in"
  version                 = "1.1.2",
  compatibleVersions      = { "1.1.0", "1.1.1" },
  description             = "Demonstrates how to use the CPF plug-in API"
  descriptionUrl          = "http://demo.gov.bc.ca",
  inputDataContentTypes   = { "image/png", "image/jpeg" },
  resultDataContentTypes  = { "image/png", "image/jpeg" },
  perRequestInputData     = true,
  perRequestResultData    = true,
  maxRequestsPerJob       = 100,
  numRequestsPerWorker    = 2,
  maxConcurrentRequests   = 10,
  batchModePermission     = "hasRoleRegex('DEMO_.*')")
  instantModePermission   = "hasRole('DEMO_USER')",
  logLevel                = "INFO")
public class Demo {
  :
}
NameTypeDefaultDescription
batchModePermission String "permitAll"

A Spring security expression indicating if a user has permission to submit single or multiple requests for batch execution.

compatibleVersions String[] {}
description String ""

A description of the plug-in that is displayed on the business application list page. Keep to a few sentences, use the descriptionUrl to link to a page containing more information.

descriptionUrl String ""

A URL to a web page providing additional documentation for the business application. This is displayed as a link on the application description page.

inputDataContentTypes String[] {}

The array of MIME media types of input data accepted by the plug-in. For perRequestInputData=false omit this value to use all the supported structured data MIME media types. For perRequestInputData=true set this to the MIME media types of the input data supported (e.g. image/jpeg).

instantModePermission String "denyAll"

A Spring security expression indicating if a user has permission to submit single request for instant execution.

NOTE: DO NOT enable this for plug-ins that consume lots of resources or take more than a second to run as it will tie up available web server threads.

logLevel String "ERROR"

The level of logging to include for requests processed by the plug-in.

Log Levels
Level Description
ERROR Only include un-handled application errors.
INFO Includes more details on the execution of groups or plug-in info level messages.
DEBUG The most detailed log level, should only be used during development.

Enabling INFO or DEBUG will increase the time it takes to process a request so should not be enabled in production unless an issue is being investigated.

maxConcurrentRequests int 100

The maximum number of concurrent execution groups that will be scheduled for this business application. If an application has a limit to the number of database connections it can use this value can be used to limit the number of requests that will be executed by the workers at one time.

maxRequestsPerJob int 2147483647

The maximum number of requests that a user can submit in a batch job.

name String ""

The name of the plug-in in (lower|Upper)CaseCamelNotation (e.g. fibonacciSequence or FibonacciSequence) . Must be a valid Java identifier (no spaces or special characters). This is used in the web service URL for the business application and in the batch jobs in the database. The name should not be changed between releases. If the name changes manual changes will be required to the data in the database and any exteral applications that use the plug-in.

numRequestsPerWorker int 1

The maximum number of requests that will be added to an execution group to send to a worker for sequential execution. If a plug-in takes milliseconds to execute set this to 100 to reduce the communication overhead in processing the requests.

packageName String ""

The name of the Java package that the business application is in (e.g. ca.bc.gov.gba). Currently this is used to set the logging level for any loggers created with that package prefix.

perRequestInputData boolean false

Boolean flag indicating that the plug-in accepts a binary blob of data for each request. The binary data will be passed to the plug-in as URL used to access the binary blob of data. Use the value true if the plug-in accepts an image, GML, or some other kind of file. Use the value false if the plug-in is a structured data plug-in and the request attributes will be set using the setter methods on the plug-in.

perRequestResultData boolean false

Boolean flag indicating that the plug-in will return a binary blob of data via an OutputStream as the result of execution. Use the value true if the plug-in generates an image, GML, or some other kind of file. Use the value false if the plug-in is a structured data plug-in and the result attributes will be read from the plug-in and these values will be stored against the request.

resultDataContentTypes String[] {}

The array of MIME media types of output data returned by the plug-in. For perRequestOutputData=false omit this value to use all the supported structured data MIME media types. For perRequestOutputData=true set this to the MIME media types of the output data supported (e.g. image/jpeg).

title String ""

The display title displayed on the web site for the plug-in (e.g. Fibonacci Sequence).

version String ""

annotation DefaultValue

The DefaultValue method annotation defines the default value to display on the form or use if a value was not provided for a JobParameter or RequestParameter . The annotation can only be defined on a setXXX method which has the JobParameter or RequestParameter .

The default value is encoded as a string. The string values will be converted to the data type of the parameter on the setXXX method.

The default value is displayed with the parameter descriptions in the business application specifications web services.

On the submit jobs form the default value is displayed in the text field or as selected value for a select list created using AllowedValues on the form.

The following code fragment shows an example of using the API.

@DefaultValue(value = "10"})
@JobParameter
@RequestParameter
public void setMaxResults(final int maxResults) {
  this.maxResults = maxResults;
}
NameTypeDefaultDescription
value String - The default value encoded as a string. The string value will be converted to the data type of the parameter.

annotation GeometryConfiguration

The GeometryConfiguration annotation can be used on a BusinessApplicationPlugin class, a RequestParameter setXXX method with a com.vividsolutions.jts.geom.Geometry subclass parameter, or a ResultAttribute getXXX method with a com.vividsolutions.jts.geom.Geometry subclass parameter to indicate the configuration of the required coordinate system, precision model, number of coordinate axis and if the geometry should be validated.

If the input or result geometry is different from the GeometryConfiguration, then the CPF will convert the geometry to a new geometry using the GeometryConfiguration.

The following example shows a geometry result attribute in BC Albers (3005), with x,y,z (3D) coordinates 1mm x,y precision model, 1m z precision model. The geometry will also be validated and the is the primary geometry.

@ResultAttribute
@GeometryConfiguration(
  srid = 3005,
  axisCount = 3,
  scaleFactorXy = 1000,
  scaleFactorZ = 1,
  validate = true,
  primaryGeometry = true)
public Geometry getGeometry() {
  return geometry;
}
NameTypeDefaultDescription
numAxis int 2

The number or axis used in the geometry. For example a 2D geometry has x, y coordinates, so the number of axis is 2. A 3D geometry has x, y, z so the number of axis is 3. Currently only axisCount of 2 and 3 are supported.

primaryGeometry boolean true

The flag indicating that this bean property is the primary geometry. This is required as some spatial file formats only support a single real geometry field. Non-primary geometries will be written as an E-WKTR string field. Only one geometry set method and one geometry get method can be marked as primary (the input primary geometry parameter can be different from the result primary geometry attribute.

scaleFactorXy double 0.0

The scale factor to apply the x, y coordinates. The scale factor is 1 / minimum unit. For example if the minimum unit was 1mm (0.001) the scale factor is 1000 (1 / 0.001). The default value 0 indicates a floating precision model where the coordinates are not rounded.

scaleFactorZ double 0.0

The scale factor to apply the z coordinates. The scale factor is 1 / minimum unit. For example if the minimum unit was 1mm (0.001) the scale factor is 1000 (1 / 0.001). The default value 0 indicates a floating precision model where the coordinates are not rounded.

srid int 0

The srid of the coordinate system the geometry should be converted to. If this attribute is omitted or has the value 0 then the coordinate system of the source geometry will not be changed. Otherwise it will be projected to the requested coordinate system.

validate boolean false

Boolean flag indicating if the geometry should be validated using the OGC isValid predicate.

annotation JobParameter

The JobParameter method annotation indicates that a setXXX method is a parameter that will be applied to all requests in a job on a BusinessApplicationPlugin class.

Job parameters are implemented as Java bean properties on the plug-in class. The plug-in must implement a setXXX property method for each job parameter. The job parameter name is the name of the Java bean property. The parameter type can only use the supported data types. The job parameters will be converted by the CPF from the input data to the correct Java type.

Before execution of the plug-in the job methods will be invoked to set the job parameter values.

A JobParameter method can also be marked as a RequestParameter if the parameter can be specified either at the job or request level.

The following example shows the use of the annotation.

private String algorithmName;

@JobParameter
public void setAlgorithmName(final String algorithmName) {
  this.algorithmName = algorithmName;
}
NameTypeDefaultDescription
description String "" The description of the job parameter to display on the plug-in overview page and as instructions on the create job forms.
descriptionUrl String "" The url to a page that describes the parameter in greater detail than is possible on the form. If specified the name of the parameter will be a hyper-link to this URL.
index int -1 The index (position) of the job parameter in the input file form.
length int -1 The maximum length of the job parameter including the scale. This is ignored for fixed size data types such as boolean, byte, short, int, long, float and double. The value -1 indicates no defined limit to the scale.
maxValue String "" The maximum allowed value for numeric parameters. The string value will be converted to the correct data type.
minValue String "" The minimum allowed value for numeric parameters. The string value will be converted to the correct data type.
scale int -1 The number of decimal places for fixed precision numeric types.
units String "" The units of measurement for numeric fields (e.g. metres, feet, degrees). This will be displayed after the field on the form.

annotation RequestParameter

The RequestParameter method annotation indicates that a setXXX method is a structured input data parameter on a BusinessApplicationPlugin class that has perRequestInputData=false.

Request parameters are implemented as Java bean properties on the plug-in class. The plug-in must implement a setXXX property method for each request parameter. The request parameter name is the name of the Java bean property. The parameter type can only use the supported data types. The request parameters will be converted by the CPF from the input data to the correct Java type.

Before execution of the plug-in the request methods will be invoked to set the request parameter values.

A RequestParameter method can also be marked as a JobParameter if the parameter can be specified either at the job or request level.

The following example shows the use of the annotation.

private String algorithmName;

@RequestParameter
public void setAlgorithmName(final String algorithmName) {
  this.algorithmName = algorithmName;
}
NameTypeDefaultDescription
description String "" The description of the request parameter to display on the plug-in overview page and as instructions on the create job forms.
descriptionUrl String "" The url to a page that describes the parameter in greater detail than is possible on the form. If specified the name of the parameter will be a hyper-link to this URL.
index int -1 The index (position) of the parameter in the input file form.
length int -1 The maximum length of the parameter including the scale. This is ignored for fixed size data types such as boolean, byte, short, int, long, float and double. The value -1 indicates no defined limit to the scale.
maxValue String "" The maximum allowed value for numeric parameters. The string value will be converted to the correct data type.
minValue String "" The minimum allowed value for numeric parameters. The string value will be converted to the correct data type.
scale int -1 The number of decimal places for fixed precision numeric types.
units String "" The units of measurement for numeric fields (e.g. metres, feet, degrees). This will be displayed after the field on the form.

annotation Required

The Required method annotation defines a JobParameter or RequestParameter as being required. If a value is not specified for a required parameter the scheduler will exclude that request from being processed and an error returned. The annotation can only be defined on a setXXX method which has the JobParameter or RequestParameter annotations.

The following example shows the use of the annotation on a JobParameter method.

@Required
@JobParameter
public void setAlgorithmName(final String algorithmName) {
  this.algorithmName = algorithmName;
}

annotation ResultAttribute

The ResultAttribute method annotation indicates that a getXXX or isXXX method is a structured result data attribute on a BusinessApplicationPlugin or ResultList class that has perRequestResultData=false.

Result attributes are implemented as Java bean properties on the plug-in class or ResultList class. The plug-in must implement a getXXX or isXXX property method for each result attribute. The result attribute name is the name of the Java bean property. The return type can only use the supported data types. The result attributes will be converted by the CPF to the correct representation in the output format or a string representation of the value before being returned to the user.

After execution of the plug-in the result attribute methods will be invoked to get the result attribute values.

The following example shows the use of the annotation on a BusinessApplicationPlugin class.

@BusinessApplicationPlugin
public class Square {
  private int square;

  @ResultAttribute(index = 2, description = "The square of a value")
  public int getSquare() {
    return square;
  }
}
NameTypeDefaultDescription
description String "" The description of the result attribute to display on the plug-in overview page and as instructions on the create job forms. If the description is not specified and there is a RequestParameter with the same name that has a description then that will be used. This simplifies coding as it removes the need to duplicate the description.
index int -1 The index (position) of the attribute in the output file.
length int -1

The maximum length of the attribute including the scale, sign '-' and decimal point '.'. This is ignored for fixed size data types such as boolean, byte, short, int, long. The value -1 indicates the use of the default value for that data type.

NOTE: decimal types such as float, double and BigDecimal should have a length specified if fixed size file formats such as shapefile are to be used.

scale int -1

The number of decimal places for fixed precision numeric types. This is ignored for data types such as boolean, byte, short, int, long, string. The value -1 indicates the use of the default value for that data type.

NOTE: decimal types such as float, double and BigDecimal should have a scaled specified if fixed size file formats such as shapefile are to be used.

annotation ResultList

The ResultList annotation can be used in structured result data plug-ins that return a list of structured results instead of a single result. For example a geocoder that returns a list of potential matches.

To return a list of results the plug-in must implement a get method that returns a List of a specified value object (e.g. ResultObject). The method must also have the ResultList annotation. The plug-in class must not have any methods marked with the ResultAttribute annotation.

The value object class contains the result attributes to return for each result in the list. Pick an appropriate name for the value object (e.g. Address). The value object class must have one or more get methods with the ResultAttribute annotation. These are the attributes that are returned to the client. The same rules apply as per structured result attributes.

The following example shows the use of the annotation on a BusinessApplicationPlugin method.

private List<ResultObject>

@ResultList
public List<ResultObject> getResults() {
  return results;
}

The following example shows the value object implementation for the above example.

public class ResultObject
private String attribute1;

@ResultAttribute
public int getField1 () {
  return attribute1;
}

class GeometryFactory

The CPF provides an extended version of the Java Topology Suite (JTS) GeometryFactory to create JTS geometries. The extended version includes support for coordinate system projection, precision model, and controls on the number of axis.

The GeometryFactory does not provide a public constructor. GeometryFactory instances can be obtained using the getFactory static methods described below.

Get a GeometryFactory with no coordinate system, 3D axis (x, y & z) and a floating precision model.

Return
GeometryFactory The geometry factory.

Get a GeometryFactory with no coordinate system, 3D axis (x, y & z) and a fixed x, y &anp; floating z precision models.

ParameterTypeDescription
scaleXy double The scale factor used to round the x, y coordinates. The precision is 1 / scaleXy. A scale factor of 1000 will give a precision of 1 / 1000 = 1mm for projected coordinate systems using metres.
Return
GeometryFactory The geometry factory.
Get the geometry factory used for an existing geometry.
ParameterTypeDescription
geometry com.vividsolutions.jts.geom.Geometry The geometry to get the factory from.
Return
GeometryFactory The geometry factory;

Get a GeometryFactory with the coordinate system, 3D axis (x, y & z) and a floating precision models.

ParameterTypeDescription
srid int The EPSG coordinate system id.
Return
GeometryFactory The geometry factory.

Get a GeometryFactory with the coordinate system, 2D axis (x & y) and a fixed x, y precision model.

ParameterTypeDescription
srid int The EPSG coordinate system id.
scaleXy double The scale factor used to round the x, y coordinates. The precision is 1 / scaleXy. A scale factor of 1000 will give a precision of 1 / 1000 = 1mm for projected coordinate systems using metres.
Return
GeometryFactory The geometry factory.

Get a GeometryFactory with no coordinate system, 3D axis (x, y & z) and a fixed x, y & floating z precision models.

ParameterTypeDescription
srid int The EPSG coordinate system id.
scaleXy double The scale factor used to round the x, y coordinates. The precision is 1 / scaleXy. A scale factor of 1000 will give a precision of 1 / 1000 = 1mm for projected coordinate systems using metres.
scaleZ double The scale factor used to round the z coordinates. The precision is 1 / scaleZ. A scale factor of 1000 will give a precision of 1 / 1000 = 1mm for projected coordinate systems using metres.
Return
GeometryFactory The geometry factory.

Get a GeometryFactory with the coordinate system, number of axis and a floating precision model.

ParameterTypeDescription
srid int The EPSG coordinate system id.
axisCount int The number of coordinate axis. 2 for 2D x & y coordinates. 3 for 3D x, y & z coordinates.
Return
GeometryFactory The geometry factory.

Get a GeometryFactory with the coordinate system, number of axis and a fixed x, y & fixed z precision models.

ParameterTypeDescription
srid int The EPSG coordinate system id.
axisCount int The number of coordinate axis. 2 for 2D x & y coordinates. 3 for 3D x, y & z coordinates.
scaleXy double The scale factor used to round the x, y coordinates. The precision is 1 / scaleXy. A scale factor of 1000 will give a precision of 1 / 1000 = 1mm for projected coordinate systems using metres.
scaleZ double The scale factor used to round the z coordinates. The precision is 1 / scaleZ. A scale factor of 1000 will give a precision of 1 / 1000 = 1mm for projected coordinate systems using metres.
Return
GeometryFactory The geometry factory.
ParameterTypeDescription
geometry com.vividsolutions.jts.geom.Geometry
Return
String
ParameterTypeDescription
geometry com.vividsolutions.jts.geom.Geometry
writeSrid boolean
Return
String

Construct a new copy of an existing com.vividsolutions.jts.geom.Geometry . If the geometry is in a different coordinate system or precision model project the geometry to the coordinate system from this geometry factory and apply the precision model.

The return type of this method will be auto-casted to the type of the variable the result is assigned to. Use Geometry as the type if it is not possible to guarantee that the geometry is of a specific geometry type.

ParameterTypeDescription
geometry G The geometry.
Return
G The copied geometry.

Construct a new com.vividsolutions.jts.geom.Geometry from a WKT or EWKT encoded geometry. If the EWKT string includes a SRID the geometry will use read using that SRID and then projected to the SRID of the geometry factory. If the SRID was not specified the geometry will be assumed to be in the coordinate system of the geometry factory's SRID. The return type of the WKT to geometry conversion will be auto-casted to the type of the variable the result is assigned to. Use Geometry as the type if it is not possible to guarantee that the WKT is of a specific geometry type.

The following example shows a WGS84 EWKT polygon converted to a BC Albers polygon.

GeometryFactory geometryFactory = GeometryFactory.getFactory(3005, 1.0);
  String wkt = "SRID=4326;POLYGON((-122 50,-124 50,-124 51,-122 51,-122 50))";
  Polygon polygon = createGeometry(wkt);
  System.out.println(polygon);
  // POLYGON((1286630 561884,1143372 555809,1140228 667065,1280345 673006,1286630 561884))
ParameterTypeDescription
wkt String The WKT or http://postgis.net/docs/manual-2.0/using_postgis_dbmanagement.html#EWKB_EWKT encoded geometry.
Return
T The created geometry.

Construct a new com.vividsolutions.jts.geom.LinearRing using the array of coordinates. The ring must form a closed loop. The size of the array should be a multiple of the number of axis. For example a 2D geometry will have x1,y1...,xN,yN values and a 3D x1,y1,z1...,xN,yN,zN. Geographic coordinates are always longitude, latitude and projected easting, northing.

ParameterTypeDescription
coordinates double[] The coordinates.
Return
com.vividsolutions.jts.geom.LinearRing The created linear ring.

Construct a new com.vividsolutions.jts.geom.LineString using the array of coordinates. The size of the array should be a multiple of the number of axis. For example a 2D geometry will have x1,y1...,xN,yN values and a 3D x1,y1,z1...,xN,yN,zN. Geographic coordinates are always longitude, latitude and projected easting, northing.

ParameterTypeDescription
coordinates double[] The coordinates.
Return
com.vividsolutions.jts.geom.LineString The created linestring.

Construct a new com.vividsolutions.jts.geom.MultiLineString using the list of lines. The first ring in the list is the exterior ring and the other rings are the interior rings. The rings in the list can be any of the following types.

  • double[]
  • com.vividsolutions.jts.geom.LineString
  • com.vividsolutions.jts.geom.CoordinateSequence

For a double[] the size of the array should be a multiple of the number of axis. For example a 2D geometry will have x1,y1...,xN,yN values and a 3D x1,y1,z1...,xN,yN,zN. Geographic coordinates are always longitude, latitude and projected easting, northing.

ParameterTypeDescription
lines Collection<?> The list of lines.
Return
com.vividsolutions.jts.geom.MultiLineString The created multi-linestring.

Construct a new com.vividsolutions.jts.geom.MultiPoint using the list of points. The points in the list can be any of the following types.

  • double[]
  • com.vividsolutions.jts.geom.Point
  • com.vividsolutions.jts.geom.Coordinate
  • com.vividsolutions.jts.geom.CoordinateSequence

For a double[] the size of the array should be a multiple of the number of axis. For example a 2D geometry will have x1,y1...,xN,yN values and a 3D x1,y1,z1...,xN,yN,zN. Geographic coordinates are always longitude, latitude and projected easting, northing.

ParameterTypeDescription
points List<?> The list of points.
Return
com.vividsolutions.jts.geom.MultiPoint The created multi-point.

Construct a new point using the array of coordinates. The size of the array should be the same as the number of axis used on this geometry factory. If the size is less then additional axis will be set to 0. If greater then those values will be ignored. For example a 2D geometry will have x,y values and a 3D x,y,z. Geographic coordinates are always longitude, latitude and projected easting, northing.

ParameterTypeDescription
coordinates double[] The coordinates.
Return
com.vividsolutions.jts.geom.Point The created point.
ParameterTypeDescription
object Object
Return
com.vividsolutions.jts.geom.Point

Construct a new polygon using the list of rings. The first ring in the list is the exterior ring and the other rings are the interior rings. The rings in the list can be any of the following types.

  • double[]
  • com.vividsolutions.jts.geom.LineString
  • com.vividsolutions.jts.geom.LinearRing
  • com.vividsolutions.jts.geom.CoordinateSequence

For a double[] the size of the array should be a multiple of the number of axis. For example a 2D geometry will have x1,y1...,xN,yN values and a 3D x1,y1,z1...,xN,yN,zN. Geographic coordinates are always longitude, latitude and projected easting, northing.

ParameterTypeDescription
rings List<?> The list of rings.
Return
com.vividsolutions.jts.geom.Polygon The created polygon.
ParameterTypeDescription
polygonList Collection<?>
Return
com.vividsolutions.jts.geom.Polygon[]
Return
double
Return
double
Return
boolean
Return
boolean

Construct a new com.vividsolutions.jts.geom.MultiPolygon using the list of points. The points in the list can be any of the following types.

For a double[] the size of the array should be a multiple of the number of axis. For example a 2D geometry will have x1,y1...,xN,yN values and a 3D x1,y1,z1...,xN,yN,zN. Geographic coordinates are always longitude, latitude and projected easting, northing.

ParameterTypeDescription
polygons Collection<?> The list of polygons.
Return
com.vividsolutions.jts.geom.MultiPolygon The created multi-polygon.

package ca.bc.gov.open.cpf.plugin.api.log

The Concurrent Processing Framework Java Plug-in Logging API.

class AppLog

The AppLog class is a logging API for use by a BusinessApplicationPlugin class. Plug-in classes can record error, info and debug messages in the execute method. These messages will be recorded in the Log4j log file (if that log level is enabled in the worker for the AppLog class). The message will also be recorded in the module log file on the master if that log level is enabled for the business application. This functionality allows viewing the logs for the all the workers from the CPF admin console.

The plug-in must implement the following method on the BusinessApplicationPlugin class to obtain a AppLog instance for this request.

private AppLog appLog;

public void setAppLog(final AppLog appLog) {
  this.appLog = appLog;
}
ParameterTypeDescription
name String
ParameterTypeDescription
name String
logLevel String
ParameterTypeDescription
moduleName String
businessApplicationName String
groupId String
logLevel String

Record the info message in the log if isInfoEnabled() is true.

ParameterTypeDescription
message String The message.

Record the error message in the log.

ParameterTypeDescription
message String The message.

Record the error message in the log with the exception.

ParameterTypeDescription
message String The message.
exception Throwable

Get the logging level (ERROR, INFO, DEBUG).

Return
String The logging level (ERROR, INFO, DEBUG).

Record the info message in the log if isInfoEnabled() is true.

ParameterTypeDescription
message String The message.

Check to see if debug level logging is enabled. Use this in an if block around logging operations that create large amounts of log data to prevent that data from being created if logging is not enabled.

Return
boolean True if debug level logging is enabled.

Check to see if info or debug level logging is enabled. Use this in an if block around logging operations that create large amounts of log data to prevent that data from being created if logging is not enabled.

Return
boolean True if info or debug level logging is enabled.

Set the current logging level (ERROR, INFO, DEBUG).

ParameterTypeDescription
logLevel String The logging level (ERROR, INFO, DEBUG).

Record the warning message in the log.

ParameterTypeDescription
message String The warning.

package ca.bc.gov.open.cpf.plugin.api.security

The Concurrent Processing Framework Java Plug-in Security API.

interface SecurityService

The security service provides a mechanism for business applications to get information about the user and enforce access control.

The plug-in can use the methods on the security service to check if the user is in a specific group, can access a resource or perform a specified action on a resource. If the user does not have the correct permission then a subclass of RuntimeException can be thrown by the plug-in with a description of why the user did not have the appropriate permission.

To use the security service the plug-in must implement the following field and method within the plug-in class. The CPF will invoke this method before the execute method to pass the security service to the plug-in.

private SecurityService securityService;

public void setSecurityService(SecurityService securityService) {
  this.securityService = securityService;
}

See each of the methods below for examples of using the security service. All of the examples assume that the above field and method are defined.

Check to see if the user can access the resource.

public void execute() {
  String resourceClass = "report";
  String resourceId = "demo";
  if (securityService.canAccessResource(resourceClass, resourceId)) {
    // Perform the request
  } else {
    throw new SecurityException("User cannot access the demo report");
  }
  }
ParameterTypeDescription
resourceClass String The type of resource.
resourceId String The resource identifier.
Return
boolean True if the user can access the resource, false otherwise.

Check to see if the user can perform the action on the resource.

public void execute() {
  String resourceClass = "report";
  String resourceId = "demo";
  String actionName = "view";
  if (securityService.canAccessResource(resourceClass, resourceId, actionName)) {
    // Perform the request
  } else {
    throw new SecurityException("User cannot perform the view action on the demo report");
  }
  }
ParameterTypeDescription
resourceClass String The type of resource.
resourceId String The resource identifier.
actionName String The action name.
Return
boolean True if the user can perform the action on the resource, false otherwise.

Check to see if the user is can perform the named action.

public void execute() {
  if (securityService.canPerformAction("view")) {
    // Perform the request
  } else {
    throw new SecurityException("User cannot perform the view action");
  }
  }
ParameterTypeDescription
actionName String The action name.
Return
boolean True if the user can perform the named action, false otherwise.

Get the consumer key of the user.

Return
String The user's consumer key.

Get the additional attributes about the user.

Return
Map<String, Object> The additional attributes about the user.

Get the classification (type) of user account.

Return
String The classification (type) of user account.

Get the login username of the user.

Return
String The login username of the user.

Check to see if the user is a member of the named group.

public void execute() {
  if (securityService.isInGroup("DEMO_PARTNER")) {
    // Perform the request
  } else {
    throw new SecurityException("User is not a member of the DEMO_PARTNER_GROUP");
  }
  }
ParameterTypeDescription
groupName String The group name.
Return
boolean True if the user is a member of the group, false otherwise.