ProcessApplicationInterface (camunda BPM - Release Root 7.0.5-ee API)

All Known Implementing Classes:

AbstractProcessApplication, DefaultEjbProcessApplication, EjbProcessApplication, EmbeddedProcessApplication, InvoiceProcessApplication, ServletProcessApplication, SpringProcessApplication, SpringServletProcessApplication, WaitStatesProcessApplication
```
public interface ProcessApplicationInterface
```
A Process Application is an ordinary Java Application that uses the camunda process engine for BPM and Worklow functionality. Most such applications will start their own process engine (or use a process engine provided by the runtime container), deploy some BPMN 2.0 process definitions and interact with process instances derived from these process definitions. Since most process applications perform very similar bootstrapping, deployment and runtime tasks, we generalized this functionality. The concept is similar to the javax.ws.rs.core.Application class in JAX-RS: adding the process application class allows you to bootstrap and configure the provided services.

Adding a ProcessApplication class to your Java Application provides your applications with the following services:
- Bootstrapping embedded process engine(s) or looking up container managed process engine(s). You can define multiple process engines in a file named processes.xml which is added to your application. The ProcessApplication class makes sure this file is picked up and the defined process engines are started and stopped as the application is deployed / undeployed.
- Automatic deployment of classpath BPMN 2.0 resources. You can define multiple deployments (process archives) in the processes.xml file. The process application class makes sure the deployments are performed upon deployment of your application. Scanning your application for process definition resource files (engine in *.bpmn20.xml or *.bpmn) is supported as well.
- Classloading & Thread context switching: Resolution of application-local Java Delegate Implementations and Beans in case of a multi-application deployment. The process application class allows your java application to expose your local Java Delegate implementations or Spring / CDI beans to a shared, container managed process engine. This way you can start a single process engine that dispatches to multiple process applications that can be (re-)deployed independently.
Transforming an existing Java Application into a Process Application is easy and non-intrusive. You simply have to add:
- A Process Application class: The Process Application class constitutes the interface between your application and the process engine. There are different base classes you can extent to reflect different environments (e.g. Servlet vs. EJB Container):
  - ServletProcessApplication: To be used for Process Applications is a Servlet Container like Apache Tomcat.
  - EjbProcessApplication: To be used in a Java EE application server like JBoss, Glassfish or WebSphere Application Server.
  - EmbeddedProcessApplication: To be used when embedding the process engine is an ordinary Java SE application.
  - org.camunda.bpm.engine.spring.application.SpringProcessApplication: To be used for bootstrapping the process application from a Spring Application Context.
- A processes.xml file to META-INF: The deployment descriptor file allows to provide a declarative configuration of the deployment(s) this process application makes to the process engine. It can be empty and serve as simple marker file - but it must be present.
Author:

Daniel Meyer

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`createDeployment(String processArchiveName, DeploymentBuilder deploymentBuilder)` Override this method in order to programmatically add resources to the deployment created by this process application.
`void`	`deploy()` Deploy this process application into the runtime container.
`<T> T`	`execute(Callable<T> callable)` The default implementation simply modifies the Context `ClassLoader`
`ELResolver`	`getElResolver()` This allows the process application to provide a custom ElResolver to the process engine.
`ExecutionListener`	`getExecutionListener()` Allows the process application to provide an `ExecutionListener` which is notified about all execution events in all of the process instances deployed by this process application.
`String`	`getName()`
`ClassLoader`	`getProcessApplicationClassloader()` Override this method to provide an environment-specific `ClassLoader` to be used by the process engine for loading resources from the process application
`Map<String,String>`	`getProperties()` override this method in order to provide a map of properties.
`ProcessApplicationInterface`	`getRawObject()` Since `getReference()` may return a proxy object, this method returs the actual, unproxied object and is meant to be called from the `execute(Callable)` method.
`ProcessApplicationReference`	`getReference()` Returns a globally sharable reference to this process application.
`TaskListener`	`getTaskListener()` Allows the process application to provide a `TaskListener` which is notified about all Task events in all of the process instances deployed by this process application.
`void`	`undeploy()` Undeploy this process application from the runtime container.

- Method Detail
  - deploy
```
void deploy()
```
    Deploy this process application into the runtime container.
    NOTE: on some containers (like JBoss AS 7) the deployment of the process application is performed asynchronously and via introspection at deployment time. This means that there is no guarantee that the process application is fully deployed after this method returns.
    If you need a post deployment hook, use the @PostDeploy annotation.
  - undeploy
```
void undeploy()
```
    Undeploy this process application from the runtime container.
    
    If your application needs to be notified of the undeployment, add a @PreUndeploy method to your subclass.
  - getName
```
String getName()
```
    Returns:
    the name of this process application
  - getReference
```
ProcessApplicationReference getReference()
```
    Returns a globally sharable reference to this process application. This reference may be safely passed to the process engine. And other applications.
    
    Returns:
    a globally sharable reference to this process application.
  - getRawObject
```
ProcessApplicationInterface getRawObject()
```
    Since getReference() may return a proxy object, this method returs the actual, unproxied object and is meant to be called from the execute(Callable) method. (ie. from a Callable implementation passed to the method.).
  - execute
```
<T> T execute(Callable<T> callable)
          throws ProcessApplicationExecutionException
```
    The default implementation simply modifies the Context ClassLoader
    
    Parameters:
    callable - the callable to be executed "within" the context of this process application.
    
    Returns:
    the result of the callback
    
    Throws:
    
    Exception
    
    ProcessApplicationExecutionException
  - getProcessApplicationClassloader
```
ClassLoader getProcessApplicationClassloader()
```
    Override this method to provide an environment-specific ClassLoader to be used by the process engine for loading resources from the process application
    
    NOTE: the process engine must never cache any references to this ClassLoader or to classes obtained through this ClassLoader.
    
    Returns:
    the ClassLoader that can be used to load classes and resources from this process application.
  - getProperties
```
Map<String,String> getProperties()
```
    override this method in order to provide a map of properties.
    
    The properties are made available globally through the ProcessApplicationService
    
    See Also:
    ProcessApplicationService, ProcessApplicationInfo.getProperties()
  - getElResolver
```
ELResolver getElResolver()
```
    This allows the process application to provide a custom ElResolver to the process engine.
    
    The process engine will use this ElResolver whenever it is executing a process in the context of this process application.
    
    The process engine must only call this method from Callable implementations passed to execute(Callable)
  - createDeployment
```
void createDeployment(String processArchiveName,
                    DeploymentBuilder deploymentBuilder)
```
    Override this method in order to programmatically add resources to the deployment created by this process application.
    
    This method is invoked at deployment time once for each process archive deployed by this process application.
    
    NOTE: this method must NOT call the DeploymentBuilder.deploy() method.
    
    Parameters:
    deploymentBuilder - the DeploymentBuilder used to construct the deployment.
    processArchiveName - the name of the processArchive which is currently being deployed.
  - getExecutionListener
```
ExecutionListener getExecutionListener()
```
    Allows the process application to provide an ExecutionListener which is notified about all execution events in all of the process instances deployed by this process application.
    
    If this method returns 'null', the process application is not notified about execution events.
    
    Returns:
    an ExecutionListener or null.
  - getTaskListener
```
TaskListener getTaskListener()
```
    Allows the process application to provide a TaskListener which is notified about all Task events in all of the process instances deployed by this process application.
    
    If this method returns 'null', the process application is not notified about Task events.
    
    Returns:
    a TaskListener or null.

Interface ProcessApplicationInterface

Method Summary

Method Detail

deploy

undeploy

getName

getReference

getRawObject

execute

getProcessApplicationClassloader

getProperties

getElResolver

createDeployment

getExecutionListener

getTaskListener