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.
The Concurrent Processing Framework Java Plug-in API.
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.
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.
Name | Type | Default | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
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.
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. |
||||||||
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 | "" |
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.
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.
Name | Type | Default | Description |
---|---|---|---|
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. |
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.
Name | Type | Default | Description |
---|---|---|---|
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. |
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.
Name | Type | Default | Description |
---|---|---|---|
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. |
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.
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.
Name | Type | Default | Description |
---|---|---|---|
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. |
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.
The following example shows the value object implementation for the above example.
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.
Get a GeometryFactory with no coordinate system, 3D axis (x, y & z) and a fixed x, y &anp; floating z precision models.
Parameter | Type | Description |
---|---|---|
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. |
Parameter | Type | Description |
---|---|---|
geometry | com.vividsolutions.jts.geom.Geometry | The geometry to get the factory from. |
Get a GeometryFactory with the coordinate system, 3D axis (x, y & z) and a floating precision models.
Parameter | Type | Description |
---|---|---|
srid | int | The EPSG coordinate system id. |
Get a GeometryFactory with the coordinate system, 2D axis (x & y) and a fixed x, y precision model.
Parameter | Type | Description |
---|---|---|
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. |
Get a GeometryFactory with no coordinate system, 3D axis (x, y & z) and a fixed x, y & floating z precision models.
Parameter | Type | Description |
---|---|---|
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. |
Get a GeometryFactory with the coordinate system, number of axis and a floating precision model.
Parameter | Type | Description |
---|---|---|
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. |
Get a GeometryFactory with the coordinate system, number of axis and a fixed x, y & fixed z precision models.
Parameter | Type | Description |
---|---|---|
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. |
Parameter | Type | Description |
---|---|---|
geometry | com.vividsolutions.jts.geom.Geometry | |
writeSrid | boolean |
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.
Parameter | Type | Description |
---|---|---|
geometry | G | The 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.
Parameter | Type | Description |
---|---|---|
wkt | String | The WKT or http://postgis.net/docs/manual-2.0/using_postgis_dbmanagement.html#EWKB_EWKT encoded 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.
Parameter | Type | Description |
---|---|---|
coordinates | double[] | The coordinates. |
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.
Parameter | Type | Description |
---|---|---|
coordinates | double[] | The coordinates. |
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.
Parameter | Type | Description |
---|---|---|
lines | Collection<?> | The list of lines. |
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.
Parameter | Type | Description |
---|---|---|
points | List<?> | The list of points. |
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.
Parameter | Type | Description |
---|---|---|
coordinates | double[] | The coordinates. |
Parameter | Type | Description |
---|---|---|
object | Object |
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.
Parameter | Type | Description |
---|---|---|
rings | List<?> | The list of rings. |
Parameter | Type | Description |
---|---|---|
polygonList | Collection<?> |
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.
com.vividsolutions.jts.geom.Polygon
List
see createPolygon(List)
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.
Parameter | Type | Description |
---|---|---|
polygons | Collection<?> | The list of polygons. |
The Concurrent Processing Framework Java Plug-in Logging API.
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.
Parameter | Type | Description |
---|---|---|
name | String |
Record the info message in the log if isInfoEnabled()
is true.
Parameter | Type | Description |
---|---|---|
message | String | The message. |
Record the error message in the log.
Parameter | Type | Description |
---|---|---|
message | String | The message. |
Record the info message in the log if isInfoEnabled()
is true.
Parameter | Type | Description |
---|---|---|
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.
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.
Set the current logging level (ERROR, INFO, DEBUG).
Parameter | Type | Description |
---|---|---|
logLevel | String | The logging level (ERROR, INFO, DEBUG). |
Record the warning message in the log.
Parameter | Type | Description |
---|---|---|
message | String | The warning. |
The Concurrent Processing Framework Java Plug-in Security API.
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.
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 is can perform the named action.
Parameter | Type | Description |
---|---|---|
actionName | String | The action name. |
Get the classification (type) of user account.
Check to see if the user is a member of the named group.
Parameter | Type | Description |
---|---|---|
groupName | String | The group name. |