ca.bc.gov.open.cpf.plugin.api.BusinessApplicationPlugin Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of cpf-api-plugin Show documentation
Concurrent Processing Framework Business Application Plugin API
There is a newer version: 5.1.1-RELEASE
/*
 * Copyright © 2008-2016, Province of British Columbia
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *         http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package ca.bc.gov.open.cpf.plugin.api;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 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 {
  :
}
 *
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(value = ElementType.TYPE)
public @interface BusinessApplicationPlugin {
  /**
   * A Spring security expression
   * indicating if a user has permission to submit single or multiple requests for batch execution.
   *
   * @return The batch mode permission
   */
  String batchModePermission() default "permitAll";

  @Deprecated
  String[] compatibleVersions() default {};

  /**
   * 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.
   */
  String description() default "";

  /**
   * A URL to a web page providing additional documentation for the business
   * application. This is displayed as a link on the application description
   * page.
   */
  String descriptionUrl() default "";

  /**
   * 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).
   */
  String[] inputDataContentTypes() default {};

  /**
   * 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.
   */
  String instantModePermission() default "denyAll";

  /**
   * The level of logging to include for requests processed by the plug-in.
   *
   * 
   *   
   *     
   *     
   *       
   *         
   *         
   *       
   *     
   *     
   *       
   *         
   *         
   *       
   *       
   *         
   *         
   *       
   *       
   *         
   *         
   *       
   *     
   *   Log LevelsLevel Description
ERROR Only include un-handled application errors.
INFO Includes more details on the execution of groups or plug-in info level messages.
DEBUG The most detailed log level, should only be used during development.
   * 
   *
   * Enabling INFO or DEBUG will increase the time it takes to process a request
   * so should not be enabled in production unless an issue is being investigated.
   */
  String logLevel() default "ERROR";

  /**
   * 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.
   */
  int maxConcurrentRequests() default 100;

  /** The maximum number of requests that a user can submit in a batch job. */
  int maxRequestsPerJob() default Integer.MAX_VALUE;

  /**
   * 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.
   */
  String name() default "";

  /**
   * 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.
   */
  int numRequestsPerWorker() default 1;

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

  /**
   * 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.
   */
  boolean perRequestInputData() default 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.
   * */
  boolean perRequestResultData() default false;

  /**
   * 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).
   */
  String[] resultDataContentTypes() default {};

  /**
   * The display title displayed on the web site for the plug-in (e.g. Fibonacci
   * Sequence).
   */
  String title() default "";

  @Deprecated
  String version() default "";
}
Level	Description
ERROR	Only include un-handled application errors.
INFO	Includes more details on the execution of groups or plug-in info level messages.
DEBUG	The most detailed log level, should only be used during development.