Plug-in Java 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.

@AllowedValues(value = {
  "MD5",
  "SHA"
})
@JobParameter
@RequestParameter
public void setAlgorithmName(final String algorithmName) {
  this.algorithmName = algorithmName;
}

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 {
  :
}

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;
}

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;
}

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;
}

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;
}

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;
}

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;
  }
}

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;
}

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.

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))

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;
}

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.

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");
  }
  }

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");
  }
  }

public void execute() {
  if (securityService.canPerformAction("view")) {
    // Perform the request
  } else {
    throw new SecurityException("User cannot perform the view action");
  }
  }

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");
  }
  }