ExecutableComponent

All Known Implementing Classes:

ExecutionEnvironment, IDExecutionEnvironment, NullExecution, SystemExecutionEnvironment
```
public interface ExecutableComponent
```
This interface describes the methods that are necessary to enable the RuntimeManager to control the single applications accordingly to the requirements of the process management system. Every component executed in the context of the ADEPT process engine or rather the corresponding wrapper (i. e. the execution environment) has to implement that API.
Implementations of this interface need to provide a constructor accepting the name of the instance (String), and the corresponding activity instance object (ActivityInstance). The constructor should check the configuration for mandatory parameters and throw a ApplicationEnvironmentException in case not all mandatory parameters are provided.
At first one of the methods init(SessionContext) or initResume(String, SessionContext) are executed exactly once. This initialises the component including its UI if available. Afterwards run() is called which executes the component.
Important remark: The runtime environment ensures that every call to these methods initiated by the runtime environment is executed by the main thread of the component. So these methods do not have to be made thread safe when the component has no other concurrent executing threads itself. But since the component needs to react to external signals, the executing thread may be interrupted any time. In this case it should call RuntimeEnvironment.dispatch() which dispatches the external signal by calling one of the signal methods (close() suspend(), kill(), signal(int)). The value returned by this methods is afterwards returned by RuntimeEnvironment.dispatch(). This allows the executing thread to react to the external signal.
For cleaning-up statically acquired resources (for instance when using Axis or similar frameworks), a static method may be provided by an implementation class of this interface having the following signature: public static void "unloadingClass"(UnloadingClassEvent).
This method is called before the class is unloaded. For normal components this is right after they have terminated. If they are shared, the method will called right before the runtime environment terminates. Note that this method cannot rely on being called by the main thread of the component! The event provides some information which may be relevant for cleaning-up statically.
The method will be called on the implementing class of the executable component. If superclasses also implement this method, your implementation may need to call them. Therefore your own implementation must expect that the corresponding executable component has never been executed, that is no method except the constructor has been called! This is the case, if a subclass overrides all the methods of your class and does not provide the static cleanup. Additionally, the method may be called several times in case different subclasses are unloaded and all call the method of the superclass. And obviously, the static cleanup may not access instance-specific fields or alike.

Author:

Markus Lauer, Ulrich Kreher

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`ExecutableComponent.Signals` Definition of the constants for signals that could be interpreted by execution environments.

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`CONF_DATA_DIRECTORY` Key for the platform data directory which is injected into each activity configuration.
`static java.lang.String`	`CONF_LIB_DIRECTORY` Key for the platform directory for external libraries which is injected into each activity configuration.
`static java.lang.String`	`CONF_LOG_DIRECTORY` Key for the platform log directory which is injected into each activity configuration.
`static java.lang.String`	`UNLOADING_CLASS_METHOD` The name of the static method which is called before the class of an `ExecutableComponent` is unloaded.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`close()` Instructs the component to terminate.
`void`	`commit()` Instructs the component to commit its modifications not managed by ADEPT.
`void`	`init(SessionContext sessionContext)` Initialises and prepares the execution of the application and provides all necessary data which maybe necessary for this.
`void`	`initResume(java.lang.String savepointId, SessionContext sessionContext)` Initialises and prepares the resuming of the application and provides all necessary data which maybe necessary for this.
`boolean`	`kill()` Enforces the application to abort its execution at once.
`Vote`	`prepareCommit()` Instructs the component to vote for Commit or Abort of the distributed transaction it participates in and to prepare a commit.
`boolean`	`reset()` Instructs the component to reset.
`boolean`	`rollback()` Instructs the component to undo all its modifications done within the current transaction.
`void`	`run()` Resembles `Runnable.run()` except that this method is expected to throw exceptions indicating that the environment was unexpected or an internal failure occurred.
`boolean`	`signal(int signal)` Signals an event to the application.
`boolean`	`suspend()` Instructs the component to store its internal state to the data context and to terminate at once.

- Field Detail
  - UNLOADING_CLASS_METHOD
```
static final java.lang.String UNLOADING_CLASS_METHOD
```
    The name of the static method which is called before the class of an ExecutableComponent is unloaded. This allows to clean-up static resources. In case of a shared class, this will be called before terminating the runtime manager, otherwise right after the execution of the component.
    
    See Also:
    
    Constant Field Values
  - CONF_LIB_DIRECTORY
```
static final java.lang.String CONF_LIB_DIRECTORY
```
    Key for the platform directory for external libraries which is injected into each activity configuration.
    
    See Also:
    
    Constant Field Values
  - CONF_DATA_DIRECTORY
```
static final java.lang.String CONF_DATA_DIRECTORY
```
    Key for the platform data directory which is injected into each activity configuration.
    
    See Also:
    
    Constant Field Values
  - CONF_LOG_DIRECTORY
```
static final java.lang.String CONF_LOG_DIRECTORY
```
    Key for the platform log directory which is injected into each activity configuration.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - init
```
void init(SessionContext sessionContext)
```
    Initialises and prepares the execution of the application and provides all necessary data which maybe necessary for this. This method or initResume(String, SessionContext) is only called once in the lifetime of an executable component. One of these methods is guaranteed to be called before calling any other method.
    When leaving this method the execution has to be completely prepared. This includes for instance the availability of the GUI in the GUI context, which is necessary for Web applications with HTML-UI.
    
    Parameters:
    
    sessionContext - The session context in which the component is to be executed.
    
    Throws:
    
    ApplicationEnvironmentException - If the component is not provided with the expected environment, for instance, the right input data, an ApplicationEnvironmentException will be thrown.
  - initResume
```
void initResume(java.lang.String savepointId,
                SessionContext sessionContext)
```
    Initialises and prepares the resuming of the application and provides all necessary data which maybe necessary for this. This method or init(SessionContext) is only called once in the lifetime of an executable component. One of these methods is guaranteed to be called before calling any other method.
    When leaving this method the execution has to be completely prepared for resuming. That is, the state of the application has to be restored. This includes the GUI.
    Usually this method will delegate also call init(SessionContext).
    
    Parameters:
    
    savepointId - The identifier of the savepoint at which the application should resume. This must not be null, but it may be the empty string.
    
    sessionContext - The session context in which the component is to be executed.
    
    Throws:
    
    ApplicationEnvironmentException - If the component is not provided with the expected environment, for instance, the right input data, an ApplicationEnvironmentException will be thrown.
  - run
```
void run()
```
    Resembles Runnable.run() except that this method is expected to throw exceptions indicating that the environment was unexpected or an internal failure occurred. Both exceptions as well as RuntimeException will set the corresponding process activity to FAILED.
    
    Throws:
    
    ApplicationEnvironmentException - If the component is not provided with the expected environment, for instance, the right input data, an ApplicationEnvironmentException will be thrown.
    
    ApplicationFailedException - If the component fails due to internal reasons, an ApplicationFailedException (resembling a RuntimeException) will be thrown.
    
    java.lang.RuntimeException - If there is a runtime exception which is not caught by the component, it will be caught by the runtime environment which will set the process activity to FAILED.
  - close
```
boolean close()
```
    Instructs the component to terminate. Within this method the component should deallocate all allocated resources.
    
    Returns:
    
    TRUE: The application is closing. FALSE: The application refuses the request, because its job is not done, yet.
  - reset
```
boolean reset()
```
    Instructs the component to reset. This is quite similar to kill() but the application does not fail but terminate normally (by calling RuntimeEnvironment.applicationReset(). The component will be re-initialised and executed again later.
    
    Returns:
    
    TRUE: The application accepts the reset. FALSE: The application refuses the request, because its busy or does not want to be reset. However, ignoring may lead to a kill.
  - signal
```
boolean signal(int signal)
```
    Signals an event to the application.
    
    Parameters:
    
    signal - the code that specifies the type of the signaled event.
    
    Returns:
    
    TRUE: The application reacts on the given event. FALSE: The application cannot react.
    
    See Also:
    
    for possible signals. Usually the ones that have corresponding methods, e. g. {@link Signals#SUSPEND} or {@link Signals#CLOSE}, will not be signaled via this method.
  - suspend
```
boolean suspend()
```
    Instructs the component to store its internal state to the data context and to terminate at once. The application should be able to continue its job later when resuming.
    
    Returns:
    
    TRUE: Component will suspend. FALSE: Instruction refused.
  - kill
```
boolean kill()
```
    Enforces the application to abort its execution at once. In the case of running a internal transaction application should abort the transaction and should rollback. Within this method the component should deallocate all allocated resources.
    
    Returns:
    
    TRUE: The component terminates at once. FALSE: Component refuses.
  - prepareCommit
```
Vote prepareCommit()
            throws IsNotSupportedException
```
    Instructs the component to vote for Commit or Abort of the distributed transaction it participates in and to prepare a commit.
    
    Returns:
    
    its vote about its commitment or abortion
    
    Throws:
    
    IsNotSupportedException - If the 2 Phase Commit Protocol is not supported an IsNotSupportedException is thrown.
  - rollback
```
boolean rollback()
          throws IsNotSupportedException
```
    Instructs the component to undo all its modifications done within the current transaction. This method has to be implemented in case the application is resettable.
    
    Returns:
    
    Returns true in case resetting/rollback was successful, false if not.
    
    Throws:
    
    IsNotSupportedException - If the component does not support rollback, an IsNotSupportedException will be thrown.
  - commit
```
void commit()
     throws IsNotSupportedException
```
    Instructs the component to commit its modifications not managed by ADEPT.
    
    Throws:
    
    IsNotSupportedException - If the component does not support commit, an IsNotSupportedException will be thrown.

Interface ExecutableComponent

Nested Class Summary

Field Summary

Method Summary

Field Detail

UNLOADING_CLASS_METHOD

CONF_LIB_DIRECTORY

CONF_DATA_DIRECTORY

CONF_LOG_DIRECTORY

Method Detail

init

initResume

run

close

reset

signal

suspend

kill

prepareCommit

rollback

commit