org.jbpm.env
Class Environment

java.lang.Object
  org.jbpm.env.Environment

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

DefaultEnvironment

public abstract class Environment
extends java.lang.Object
implements java.io.Serializable

maintains contextual information for a thread in a set of Contexts.

Introduction

Objects have different lifecycles and different context's (aka scopes). An environment provides the structure to easily manage objects with different contexts.

Examples of contexts are:

• application: The application context is used to store e.g. data sources, session factories and other static resources needed by an application. The application context lives for the complete duration of the EnvironmentFactory. So if the EnvironmentFactory is maintained in a static member field, the application context lives for the duration of the application. The same application context is shared for all the Environments produced by one EnvironmentFactory.
• block: The block context is used for e.g. a transaction and transactional resources, user authentication. In combination with a WireContext, this results in an efficient and configurable use of transactional resources that need to be lazily initialized.
• The environment can accomodate other contexts as well. They can be added and removed dynamically. Examples of other potential contexts are web-request, web-session, web-application, business processDefinition, job, ...

An environment is typically installed like this

static EnvironmentFactory environmentFactory = new DefaultEnvironmentFactory();
 
 ...
 
 Environment environment = environmentFactory.openEnvironment();
 try {
 
   ... everything available in this block ... 
 
 } finally {
   environment.close();
 }
 

Purpose

The first purpose of the environment is to separate the application from the environment. Standard Java and Enterprise Java are quite different and an environment abstraction like this allows for the development of applications that can run in both Standard and Enterprise environments. Also test environments are easier to tweak this way.

A second purpose of the environment is to enable specific to global searching of resources. E.g. you could search for an 'adminEmailAddress' in the contexts 'processDefinition-execution', 'processDefinition-definition' and 'application' in the given order. That way, a global adminEmailAddress can be specified in the application context and it can be refined in more specific contexts processDefinition-definition or processDefinition-execution.

Search order

To find an object in the environment, a searchOrder can be specified. A search order is an sequence that specifies the order in which the contexts should be searched.

The default search order is the inverse sequence of how the contexts are added to the environment. This is because in general, we can assume that the more recent a context was added, the more specific it is.

Transaction, username and classloader

Three objects are used so frequently in an environment that they get special treatment:

• Transaction: an abstraction for marking a transaction with setRollbackOnly.
• Classloader: the current class loader.
• Username: the name of the currently authenticated user.

For these special properties, setters are also available. That is to support programmatic injection into the environment. Alternatively, they can be configured in one of the contexts.

Author:

Tom Baeyens

See Also:

EnvironmentFactory, Serialized Form

Constructor Summary

Environment()

Method Summary

abstract void	addContext(Context context)
abstract void	close() closes the Environment by removing all its contexts.
abstract <T> T	get(java.lang.Class<T> type) searches an object based on type.
abstract java.lang.Object	get(java.lang.String name) searches a named object in all the contexts in the default search order.
abstract java.lang.Object	get(java.lang.String name, java.lang.String[] searchOrder) searches a named object in all the contexts in the given search order.
abstract java.lang.ClassLoader	getClassLoader()
abstract Context	getContext(java.lang.String contextName)
static Environment	getCurrent()
abstract EnvironmentFactory	getEnvironmentFactory()
abstract java.lang.Throwable	getException() retrieves the first exception that was reported in this environment block.
abstract Transaction	getTransaction() convenience method for finding the Transaction.
abstract java.lang.String	getUserId() get the authenticated user id
protected static Environment	pop() pops the closing context from the stack of current contexts.
abstract void	removeContext(java.lang.String contextName)
abstract void	setClassLoader(java.lang.ClassLoader classLoader)
abstract void	setException(java.lang.Throwable exception) for clients to indicate that an exception has occurred in this environment block.
abstract void	setUserId(java.lang.String userId) set the authenticated user id

Methods inherited from class java.lang.Object

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

Constructor Detail

Environment

public Environment()

Method Detail

get

public abstract java.lang.Object get(java.lang.String name)

searches a named object in all the contexts in the default search order.

Returns:

the object if it exists in the environment, null if there is no object with the given name in the environment.

get

public abstract java.lang.Object get(java.lang.String name,
                                     java.lang.String[] searchOrder)

searches a named object in all the contexts in the given search order. The given search order doesn't have to include all contexts. It can be a subset of the contexts available.

Parameters:

searchOrder - list of contexts names. The object will be searched in these contexts, in the given order.

Returns:

the object if it exists in the environment, null if there is no object with the given name in the specified searchOrder contexts.

get

public abstract <T> T get(java.lang.Class<T> type)

searches an object based on type. The search doesn take superclasses of the context elements into account.

Returns:

the first object of the given type or null in case no such element was found.

See Also:

WireContext.get(Class)

getTransaction

public abstract Transaction getTransaction()

convenience method for finding the Transaction.

getUserId

public abstract java.lang.String getUserId()

get the authenticated user id

setUserId

public abstract void setUserId(java.lang.String userId)

set the authenticated user id

setException

public abstract void setException(java.lang.Throwable exception)

for clients to indicate that an exception has occurred in this environment block. Behaviour of method is configurable.

getException

public abstract java.lang.Throwable getException()

retrieves the first exception that was reported in this environment block.

close

public abstract void close()

closes the Environment by removing all its contexts. As a result of removing the contexts, the Context.setEnvironment(Environment) will be called with a null value for environment.

getContext

public abstract Context getContext(java.lang.String contextName)

addContext

public abstract void addContext(Context context)

removeContext

public abstract void removeContext(java.lang.String contextName)

getEnvironmentFactory

public abstract EnvironmentFactory getEnvironmentFactory()

getClassLoader

public abstract java.lang.ClassLoader getClassLoader()

setClassLoader

public abstract void setClassLoader(java.lang.ClassLoader classLoader)

getCurrent

public static Environment getCurrent()

pop

protected static Environment pop()

pops the closing context from the stack of current contexts. This is the first thing that needs to be done when an environment is closed.

See Also:

EnvironmentFactory.push(Environment)