org.jbpm.api.env
Class Environment

java.lang.Object
  extended by org.jbpm.api.env.Environment
All Implemented Interfaces:
java.io.Serializable

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:

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 'execution', 'transaction' and 'process-engine' in the given order. That way, a global adminEmailAddress can be specified in the process-engine context and it can be refined in more specific contexts.

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:

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 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
<T> T
get(java.lang.Class<T> type, java.lang.String[] searchOrder)
          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()
          gets the most inner open environment.
static
<T> T
getFromCurrent(java.lang.Class<T> type)
           
static
<T> T
getFromCurrent(java.lang.Class<T> type, boolean required)
           
static java.lang.Object getFromCurrent(java.lang.String name)
           
static java.lang.Object getFromCurrent(java.lang.String name, boolean required)
           
abstract  java.lang.String getUserId()
          get the authenticated user id
static Environment popEnvironment()
          pops the closing context from the stack of current contexts.
static void pushEnvironment(Environment environment)
          after opening of a new environment succeeded, the environment must be pushed in the stack of current environments.
abstract  Context removeContext(Context context)
           
abstract  Context removeContext(java.lang.String contextName)
           
abstract  void setClassLoader(java.lang.ClassLoader classLoader)
           
abstract  void setContext(Context context)
           
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.

get

public abstract <T> T get(java.lang.Class<T> type,
                          java.lang.String[] searchOrder)
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.

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


close

public abstract void close()
closes the Environment by removing all its contexts.


getContext

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

setContext

public abstract void setContext(Context context)

removeContext

public abstract Context removeContext(Context context)

removeContext

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

getClassLoader

public abstract java.lang.ClassLoader getClassLoader()

setClassLoader

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

getCurrent

public static Environment getCurrent()
gets the most inner open environment.


getFromCurrent

public static <T> T getFromCurrent(java.lang.Class<T> type)

getFromCurrent

public static <T> T getFromCurrent(java.lang.Class<T> type,
                                   boolean required)

getFromCurrent

public static java.lang.Object getFromCurrent(java.lang.String name)

getFromCurrent

public static java.lang.Object getFromCurrent(java.lang.String name,
                                              boolean required)

popEnvironment

public static Environment popEnvironment()
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)

pushEnvironment

public static void pushEnvironment(Environment environment)
after opening of a new environment succeeded, the environment must be pushed in the stack of current environments.

See Also:
Environment#pop()


Copyright © 2009 JBoss, a division of Red Hat. All Rights Reserved.