ca.bc.gov.open.cpf.api.web.rest

Class ConcurrentProcessingFramework

java.lang.Object

ca.bc.gov.open.cpf.api.web.rest.ConcurrentProcessingFramework

@Controller
public class ConcurrentProcessingFramework
extends Object

The Concurrent Processing Framework REST API allows client applications in Java, JavaScript or other programming languages to query the available business applications, create jobs and download the results of jobs on behalf of their users.

Most of the resources can return JSON or XML documents by appending the .json or .xml file format extension to the URI Templates before any query string parameters. JSON is the preferred format due to it's well defined map, list and value structure. Some resources that always return a specific data type will ignore the file format extension if specified.

The CPF REST API can also be accessed directly using a web browser by not specifying a file format extension. If a file format extension is not included in the request then the HTML user interface will be displayed instead of the resources described in this API. The HTML user interface allows full access to the CPF without any programming experience required. The HTML user interface will be slightly different from the responses described in this API.

Constructor Summary

Constructors

Constructor and Description
ConcurrentProcessingFramework() Construct a new ConcurrentProcessingFramework.

Method Summary

Modifier and Type	Method and Description
void	addTestParameters(BusinessApplication businessApplication, Map parameters)
void	close()
Object	createJobWithMultipleRequests(String businessApplicationName, String[] inputDataContentTypes, List<org.springframework.web.multipart.MultipartFile> inputDataFiles, List<String> inputDataUrls, String srid, String resultDataContentType, int resultSrid, int resultNumAxis, int resultScaleFactorXy, int resultScaleFactorZ, String notificationUrl, String notificationEmail) Construct a new new job containing multiple requests to be processed by the business application.
Object	createJobWithSingleRequest(String businessApplicationName, String inputDataContentType, Object inputDataFile, String inputDataUrl, String srid, String resultDataContentType, int resultSrid, int resultNumAxis, int resultScaleFactorXy, int resultScaleFactorZ, String notificationUrl, String notificationEmail) Construct a new new job containing multiple requests to be processed by the business application.
void	deleteJob(Long batchJobId) Cancel the user's job.
Map<String,? extends Object>	getAuthenticated() Check that a user is authenticated.
Object	getBusinessApplications() Get the list of links to the Get Business Applications Resources resource for each business application the user is authorized to access.
Object	getBusinessApplicationsInstant(String businessApplicationName, boolean specification, String srid, String format, int resultSrid, int resultNumAxis, int resultScaleFactorXy, int resultScaleFactorZ) The instant resource has the two modes described below, the specification mode and the execute instant request mode.
Object	getBusinessApplicationsJobs(String businessApplicationName) Get the list of links to the Get Jobs Info resource for each of the user's jobs for the business application.
com.revolsys.ui.model.PageInfo	getBusinessApplicationsMultiple(String businessApplicationName) Get the specification of the Create Job With Multiple Requests service.
Object	getBusinessApplicationsResources(String businessApplicationName) Get the resources for a business application.
com.revolsys.ui.model.PageInfo	getBusinessApplicationsSingle(String businessApplicationName) Get the specification of the Create Job With Single Request service.
String	getInputMediaType(BusinessApplication application, String inputContentType)
Object	getJobs() Get the list of links to the Get Jobs Info resource for each of the user's jobs.
Object	getJobsInfo(Long batchJobId) Get the details of a job.
void	getJobsResult(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, Long batchJobId, int resultId) Get the contents of a user's job result file.
Object	getJobsResults(Long batchJobId) Get the list of links to the Get Jobs Result resource for each of the results for a user's job.
Object	getRoot() Get the root resource of the CPF web services.
void	setBatchJobResultUiBuilder(BatchJobResultUiBuilder batchJobResultUiBuilder)
void	setBatchJobService(BatchJobService batchJobService)
void	setBatchJobUiBuilder(BatchJobUiBuilder batchJobUiBuilder)
void	setBusinessAppBuilder(BusinessApplicationUiBuilder businessAppBuilder)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ConcurrentProcessingFramework

public ConcurrentProcessingFramework()

Construct a new ConcurrentProcessingFramework.

Method Detail

addTestParameters

public void addTestParameters(BusinessApplication businessApplication,
                              Map parameters)

close

@PreDestroy
public void close()

createJobWithMultipleRequests

@ResponseBody
public Object createJobWithMultipleRequests(@PathVariable(value="businessApplicationName")
                                                          String businessApplicationName,
                                                          @RequestParam(value="inputDataContentType",required=false)
                                                          String[] inputDataContentTypes,
                                                          @RequestParam(value="inputData",required=false)
                                                          List<org.springframework.web.multipart.MultipartFile> inputDataFiles,
                                                          @RequestParam(value="inputDataUrl",required=false)
                                                          List<String> inputDataUrls,
                                                          @RequestParam(value="srid",required=false)
                                                          String srid,
                                                          @RequestParam(value="resultDataContentType",required=false)
                                                          String resultDataContentType,
                                                          @RequestParam(value="resultSrid",required=false,defaultValue="3005")
                                                          int resultSrid,
                                                          @RequestParam(value="resultNumAxis",required=false,defaultValue="2")
                                                          int resultNumAxis,
                                                          @RequestParam(value="resultScaleFactorXy",required=false,defaultValue="-1")
                                                          int resultScaleFactorXy,
                                                          @RequestParam(value="resultScaleFactorZ",required=false,defaultValue="-1")
                                                          int resultScaleFactorZ,
                                                          @RequestParam(value="notificationUrl",required=false)
                                                          String notificationUrl,
                                                          @RequestParam(value="notificationEmail",required=false)
                                                          String notificationEmail)

Construct a new new job containing multiple requests to be processed by the business application.

The service parameters must be passed using the multipart/form-data encoding in the body of a HTTP POST request (e.g. a HTML form).

In addition to the standard parameters listed in the API each business application has additional job and request parameters. The Get Business Applications Multiple resource should be consulted to get the full list of supported parameters.

Structured Input Data

For structured input data business applications the requests are specified using either a single inputData file or a single inputDataUrl can be specified. The file must be in the file format specified by a single inputDataContentType. The contents of the file must contain one record for each request to be processed in the batch job. The fields of each record must contain the request parameters supported by the business application. The names of the parameters are case sensitive.

Opaque input data

For opaque input data (e.g. JPEG image, ESRI Shapefile) the requests can be specified as one or more inputData files or one or more inputDataUrl parameters. It is not possible to mix inputData and inputDataUrl parameters in the same job. If all the requests have the same content type a single inputDataContentType can be specified. Otherwise an inputDataContentType must be specified for each inputData or inputDataUrl in the same order.

NOTE: The maximum size including all parameters and protocol overhead of a multi-part request is 20MB. Therefore inputDataUrl should be used instead of inputData where possible.

Parameters:

businessApplicationName - The name of the business application.

inputDataContentTypes - The MIME type of the input data specified by an inputData or inputDataUrl parameter.

inputDataFiles - The multi-part file containing the input data.

inputDataUrls - The http: URL to the file or resource containing input data.

srid - The coordinate system code of the projection for the input geometry.

resultDataContentType - The MIME type of the result data specified to be returned after running the request.

resultSrid - The coordinate system code of the projection for the result geometry.

resultNumAxis - The number of coordinate axis in the result geometry (e.g. 2 for 2D or 3 for 3D).

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

resultScaleFactorZ - The scale factor to apply the z coordinate. 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).

notificationUrl - The http: URL to be notified when the job is completed. A copy of the Job status will be posted to process running at this URL.

notificationEmail - The email address to send the job status to when the job is completed.

Returns:

The resource.

createJobWithSingleRequest

@ResponseBody
public Object createJobWithSingleRequest(@PathVariable(value="businessApplicationName")
                                                       String businessApplicationName,
                                                       @RequestParam(value="inputDataContentType",required=false)
                                                       String inputDataContentType,
                                                       @RequestParam(value="inputData",required=false)
                                                       Object inputDataFile,
                                                       @RequestParam(value="inputDataUrl",required=false)
                                                       String inputDataUrl,
                                                       @RequestParam(value="srid",required=false)
                                                       String srid,
                                                       @RequestParam(value="resultDataContentType",required=false)
                                                       String resultDataContentType,
                                                       @RequestParam(value="resultSrid",required=false,defaultValue="3005")
                                                       int resultSrid,
                                                       @RequestParam(value="resultNumAxis",required=false,defaultValue="2")
                                                       int resultNumAxis,
                                                       @RequestParam(value="resultScaleFactorXy",required=false,defaultValue="-1")
                                                       int resultScaleFactorXy,
                                                       @RequestParam(value="resultScaleFactorZ",required=false,defaultValue="-1")
                                                       int resultScaleFactorZ,
                                                       @RequestParam(value="notificationUrl",required=false)
                                                       String notificationUrl,
                                                       @RequestParam(value="notificationEmail",required=false)
                                                       String notificationEmail)
                                                throws IOException

Construct a new new job containing multiple requests to be processed by the business application.

The job and request parameters for the business application must be passed using the multipart/form-data encoding in the body of a HTTP POST request (e.g. a HTML form).

In addition to the standard parameters listed in the API each business application has additional job and request parameters. The Get Business Applications Single resource should be consulted to get the full list of supported parameters.

Structured Input Data

For structured input data business applications the request parameters are specified in the HTTP POST form.

Opaque input data

For opaque input data (e.g. JPEG image, ESRI Shapefile) the requests can be specified as one inputData files or one inputDataUrl parameter. It is not possible to mix inputData and inputDataUrl parameters in the same job.

NOTE: The maximum size including all parameters and protocol overhead of a multi-part request is 20MB. Therefore inputDataUrl should be used instead of inputData where possible for opaque data.

Parameters:

businessApplicationName - The name of the business application.

inputDataContentType - The MIME type of the input data specified by an inputData or inputDataUrl parameter.

inputDataFile - The multi-part file containing the input data.

inputDataUrl - The http: URL to the file or resource containing input data.

srid - The coordinate system code of the projection for the input geometry.

resultDataContentType - The MIME type of the result data specified to be returned after running the request.

resultSrid - The coordinate system code of the projection for the result geometry.

resultNumAxis - The number of coordinate axis in the result geometry (e.g. 2 for 2D or 3 for 3D).

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

resultScaleFactorZ - The scale factor to apply the z coordinate. 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).

notificationUrl - The http: URL to be notified when the job is completed. A copy of the Job status will be posted to process running at this URL.

notificationEmail - The email address to send the job status to when the job is completed.

Returns:

The resource.

Throws:

IOException

deleteJob

public void deleteJob(@PathVariable(value="batchJobId")
                      Long batchJobId)

Cancel the user's job. This will mark the job as cancelled and remove all requests and results from the job. The job will be removed after a few days.

This service should be invoked after the results from the job are downloaded. If this method is not called the job will automatically be deleted 7 days after the result download was started.

This method can also be used to cancel a job before it was finished. If a job was submitted in error or no longer required use this method to cancel the job to help free resources on the system to process other jobs.

Parameters:

batchJobId - The job identifier.

getAuthenticated

@ResponseBody
public Map<String,? extends Object> getAuthenticated()

Check that a user is authenticated. This can be used by JavaScript applications to force a login page to be displayed. Returns a map with authenticated=true if the user is authenticated. Response is undefined if the user is not authenticated as the authentication mechanism will not allow access to the resource.

Returns:

The authenticated message.

getBusinessApplications

@ResponseBody
public Object getBusinessApplications()

Get the list of links to the Get Business Applications Resources resource for each business application the user is authorized to access.

The method returns a Resource Description document. Each child resource supports following custom attributes.

Business Application Fields

Attribute	Description
businessApplicationName	The name of the business application.

Returns:

The resource.

getBusinessApplicationsInstant

@ResponseBody
public Object getBusinessApplicationsInstant(@PathVariable(value="businessApplicationName")
                                                           String businessApplicationName,
                                                           @RequestParam(value="specification",defaultValue="false")
                                                           boolean specification,
                                                           @RequestParam(value="srid",required=false)
                                                           String srid,
                                                           @RequestParam(value="format",required=false)
                                                           String format,
                                                           @RequestParam(value="resultSrid",required=false,defaultValue="3005")
                                                           int resultSrid,
                                                           @RequestParam(value="resultNumAxis",required=false,defaultValue="2")
                                                           int resultNumAxis,
                                                           @RequestParam(value="resultScaleFactorXy",required=false,defaultValue="-1")
                                                           int resultScaleFactorXy,
                                                           @RequestParam(value="resultScaleFactorZ",required=false,defaultValue="-1")
                                                           int resultScaleFactorZ)

The instant resource has the two modes described below, the specification mode and the execute instant request mode. If the format parameter is not included or the specification parameter equals true then the specification mode is enabled, otherwise the execute instant request mode is enabled.

Specification

Get the specification of the execute instant request mode of this service.

The method returns a Resource Description document with the following additional fields which are the parameters to the execute instant request mode..

Business Application Instant Fields

Attribute	Description
description	The description of services offered by the business application.
businessApplicationName	The name of the business application.
businessApplicationTitle	The display title of the business application.
businessApplicationDescription	The description of services offered by the business application.
businessApplicationDescriptionUrl	A link to a web page describing more details about the business application.
parameters	The array of parameters that can be passed to the service. Each parameter is an object containing the following fields. Parameters Attribute Description name The case sensitive name of the parameter. type The data type of the parameter. description The description of the parameter. descriptionUrl The link to a more detailed description of the parameter. jobParameter Boolean flag indicating if the parameter can be specified globally on the job. requestParameter Boolean flag indicating if the parameter can be specified on each request in the job.
inputDataContentTypes	The array of MIME media types of input data accepted by the business application.
perRequestInputData	Boolean flag indicating that the business application accepts opaque data (true) or structured data (false).
resultDataContentTypes	The array of MIME media types of result data generated by the business application.
perRequestResultData	Boolean flag indicating that the business application returns opaque data (true) or structured data (false).

Execute Instant Request

Execute a single instant request using the business application with the results returned in the request.

The job and request parameters for the business application must be passed using the query string parameters in a HTTP get request or application/form-url-encoded, multipart/form-data encoding in the body of a HTTP POST request (e.g. a HTML form).

In addition to the standard parameters listed in the API each business application has additional job and request parameters. Invoke the specification mode of this resource should be consulted to get the full list of supported parameters.

NOTE: The instant resource does not support opaque input data.

Parameters:

businessApplicationName - The name of the business application.

srid - The coordinate system code of the projection for the input geometry.

format - The MIME type of the result data specified to be returned after running the request.

resultSrid - The coordinate system code of the projection for the result geometry.

resultNumAxis - The number of coordinate axis in the result geometry (e.g. 2 for 2D or 3 for 3D).

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

resultScaleFactorZ - The scale factor to apply the z coordinate. 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).

Returns:

The result.

getBusinessApplicationsJobs

@ResponseBody
public Object getBusinessApplicationsJobs(@PathVariable(value="businessApplicationName")
                                                        String businessApplicationName)

Get the list of links to the Get Jobs Info resource for each of the user's jobs for the business application.

The method returns a Resource Description document. Each child resource supports following custom attributes.

Job Fields

Attribute	Description
batchJobId	The unique identifier of the job.
batchJobUrl	The URL to the Get Jobs Info resource without the file format extension.
jobStatus	The current status of the job.
creationTimestamp	The time when the job was created.

Parameters:

businessApplicationName - The name of the business application.

Returns:

The resource.

getBusinessApplicationsMultiple

@ResponseBody
public com.revolsys.ui.model.PageInfo getBusinessApplicationsMultiple(@PathVariable(value="businessApplicationName")
                                                                                    String businessApplicationName)

Get the specification of the Create Job With Multiple Requests service.

The method returns a Resource Description document with the following additional fields which are the parameters to the Create Job With Multiple Requests service..

Business Application Fields

Attribute	Description
description	The description of services offered by the business application.
businessApplicationName	The name of the business application.
businessApplicationTitle	The display title of the business application.
businessApplicationDescription	The description of services offered by the business application.
businessApplicationDescriptionUrl	A link to a web page describing more details about the business application.
parameters	The array of parameters that can be passed to the service. Each parameter is an object containing the following fields. Parameters Attribute Description name The case sensitive name of the parameter. type The data type of the parameter. description The description of the parameter. descriptionUrl The link to a more detailed description of the parameter. jobParameter Boolean flag indicating if the parameter can be specified globally on the job. requestParameter Boolean flag indicating if the parameter can be specified on each request in the job.
inputDataContentTypes	The array of MIME media types of input data accepted by the business application.
perRequestInputData	Boolean flag indicating that the business application accepts opaque data (true) or structured data (false).
resultDataContentTypes	The array of MIME media types of result data generated by the business application.
perRequestResultData	Boolean flag indicating that the business application returns opaque data (true) or structured data (false).

Parameters:

businessApplicationName - The name of the business application.

Returns:

The resource.

getBusinessApplicationsResources

@ResponseBody
public Object getBusinessApplicationsResources(@PathVariable(value="businessApplicationName")
                                                             String businessApplicationName)

Get the resources for a business application. The resource contains links to the instant, create single request job, and create multi request jobs resources.

The method returns a Resource Description document.

Parameters:

businessApplicationName - The name of the business application.

Returns:

The resource.

getBusinessApplicationsSingle

@ResponseBody
public com.revolsys.ui.model.PageInfo getBusinessApplicationsSingle(@PathVariable(value="businessApplicationName")
                                                                                  String businessApplicationName)

Get the specification of the Create Job With Single Request service.

The method returns a Resource Description document with the following additional fields which are the parameters to the Create Job With Single Request service..

Business Application Single Request Fields

Attribute	Description
description	The description of services offered by the business application.
businessApplicationName	The name of the business application.
businessApplicationTitle	The display title of the business application.
businessApplicationDescription	The description of services offered by the business application.
businessApplicationDescriptionUrl	A link to a web page describing more details about the business application.
parameters	The array of parameters that can be passed to the service. Each parameter is an object containing the following fields. Patameters Attribute Description name The case sensitive name of the parameter. type The data type of the parameter. description The description of the parameter. descriptionUrl The link to a more detailed description of the parameter. jobParameter Boolean flag indicating if the parameter can be specified globally on the job. requestParameter Boolean flag indicating if the parameter can be specified on each request in the job.
inputDataContentTypes	The array of MIME media types of input data accepted by the business application.
perRequestInputData	Boolean flag indicating that the business application accepts opaque data (true) or structured data (false).
resultDataContentTypes	The array of MIME media types of result data generated by the business application.
perRequestResultData	Boolean flag indicating that the business application returns opaque data (true) or structured data (false).

Parameters:

businessApplicationName - The name of the business application.

Returns:

The resource.

getInputMediaType

public String getInputMediaType(BusinessApplication application,
                                String inputContentType)

getJobs

@ResponseBody
public Object getJobs()

Get the list of links to the Get Jobs Info resource for each of the user's jobs.

The method returns a Resource Description document. Each child resource supports following custom attributes.

Job Fields

Attribute	Description
batchJobId	The unique identifier of the job.
batchJobUrl	The URL to the Get Jobs Info resource without the file format extension.
jobStatus	The current status of the job.
creationTimestamp	The time when the job was created.

Returns:

The resource.

getJobsInfo

@ResponseBody
public Object getJobsInfo(@PathVariable(value="batchJobId")
                                        Long batchJobId)

Get the details of a job.

The method returns a BatchJob object with the following attributes.

Job Fields

Attribute	Description
id	The unique identifier of the job.
businessApplicationName	The name of the business application.
<parameter>	the job parameters.
resultSrid	The coordinate system code of the projection for the result geometry.
resultNumAxis	The number of coordinate axis in the result geometry (e.g. 2 for 2D or 3 for 3D).
resultScaleFactorXy	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).
resultScaleFactorZ	The scale factor to apply the z coordinate. 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).
resultDataContentType	The MIME type of the result data specified to be returned after running the request.
jobStatus	The current status of the job.
secondsToWaitForStatusCheck	The number of seconds to wait before checking the status again
numSubmittedRequests	The number of requests submitted.
numCompletedRequests	The number of requests that completed execution successfully.
numFailedRequests	The number of requests that failed to execute.
resultsUrl

Parameters:

batchJobId - The unique identifier of the job.

Returns:

The resource.

getJobsResult

@ResponseBody
public void getJobsResult(javax.servlet.http.HttpServletRequest request,
                                        javax.servlet.http.HttpServletResponse response,
                                        @PathVariable(value="batchJobId")
                                        Long batchJobId,
                                        @PathVariable(value="resultId")
                                        int resultId)
                                 throws IOException

Get the contents of a user's job result file. The content type will be the content type requested in the job.

Parameters:

batchJobId - The unique identifier of the job.

resultId - The unique identifier of the result file.

Throws:

IOException

getJobsResults

@ResponseBody
public Object getJobsResults(@PathVariable(value="batchJobId")
                                           Long batchJobId)

Get the list of links to the Get Jobs Result resource for each of the results for a user's job.

The method returns a Resource Description document. Each child resource supports following custom attributes.

Result Fields

Attribute	Description
batchJobResultType	The type of result file structuredResultData, opaqueResultData, errorResultData.
batchJobResultContentType	The MIME type of the result file.

Parameters:

batchJobIdentifier - The unique identifier of the job.

Returns:

The resource.

getRoot

@ResponseBody
public Object getRoot()

Get the root resource of the CPF web services. The resource contains links to the Get Jobs and Get Business Applications resources.

The method returns a Resource Description document.

Returns:

The resource.

setBatchJobResultUiBuilder

public void setBatchJobResultUiBuilder(BatchJobResultUiBuilder batchJobResultUiBuilder)

setBatchJobService

public void setBatchJobService(BatchJobService batchJobService)

setBatchJobUiBuilder

public void setBatchJobUiBuilder(BatchJobUiBuilder batchJobUiBuilder)

setBusinessAppBuilder

public void setBusinessAppBuilder(BusinessApplicationUiBuilder businessAppBuilder)