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

Class 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 Detail

      • ConcurrentProcessingFramework

        public ConcurrentProcessingFramework()
        Construct a new ConcurrentProcessingFramework.

    • Method Detail

      • addTestParameters

        public void addTestParameters​(BusinessApplication businessApplication,
                              Map parameters)

      • cancelJob

        public void cancelJob​(@PathVariable("batchJobId")
                      Long batchJobId)
               throws IOException

        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.
        Throws:
        IOException

      • close

        @PreDestroy
public void close()

      • createJobWithMultipleRequests

        @ResponseBody
public Object createJobWithMultipleRequests​(@PathVariable("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, 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("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, 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("batchJobId")
                      Long batchJobId)
               throws IOException

        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.
        Throws:
        IOException

      • 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("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("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("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("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("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.

      • 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("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("batchJobId")
                          Long batchJobId,
                          @PathVariable("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("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.

      • setBatchJobResultUiBuilder

        public void setBatchJobResultUiBuilder​(BatchJobResultUiBuilder batchJobResultUiBuilder)

      • setBatchJobService

        public void setBatchJobService​(BatchJobService batchJobService)

      • setBatchJobUiBuilder

        public void setBatchJobUiBuilder​(BatchJobUiBuilder batchJobUiBuilder)