VariablesBroker

The X:Forge VariablesBroker is a central mechanism that manages the various X:Forge contexts and the data they contain. Generally, an X:Forge context is a scoped object container with a unique contextId. This means that ...

  • ... two contexts with the same contextId are considered to be one and the same (uniqueness of contextId).
  • ... an X:Forge context starts and ends at a particular time (scoped).
  • ... any Java object can be stored in or retrieved from an X:Forge context (object container).

Configuration

The VariablesBroker cannot be configured, it runs automatically in the background.

Usage

Getting the VariablesBroker

A reference to the VariablesBroker can be obtained like this: 

VariablesBroker broker = VariablesBroker.getBroker();

X:Forge Contexts

X:Forge ships with several contexts that the VariablesBroker can manage. They differ as to how they calculate their own, unique identifier and some of them have additional features. Here are the contexts available in the core system: 

  1. DefaultVariablesContext varsContext = new DefaultVariablesContext();

    Should be used as a repository for user variables and is unique per thread.

  2. ThreadContext threadContext = new ThreadContext();

    Should be used as a repository for internal variables (no user access) and is unique per thread.

  3. RequestContext requestContext = new RequestContext();

    Like the ThreadContext, but additionally starts and ends an XForgeMonitorContext internally. In a request/response type of model (e.g. web applications) it is often advisable to cache responses. To that end there is a special monitoring feature in X:Forge, where a component can be asked, whether it has changed since the last request or not. Depending on the answer it may be reasonable to return the cached response to the user, instead of regenerating it. Any application that wishes to monitor the components it uses, should define a new class that extends RequestContext and defines a so-called urlcontextclass field. The class from this field will then be used as the context class and support monitoring.

  4. TestContext testContext = new TestContext();

    The X:Forge test application (see run.sh or run.bat) demonstrates the monitoring feature and uses this context, which extends RequestContext.

  5. C1RequestContext C1RequestContext = new C1RequestContext();

    For use with X:Forge's Cocoon1 Processor, it extends RequestContext.

  6. C2RequestContext C2RequestContext = new C2RequestContext();

    For use with X:Forge's Cocoon2 Transformer, it extends RequestContext.

  7. UniqueContext uniqueContext = new UniqueContext();

    It has a static contextId of "1" and therefore is common to all threads.

Creating Custom Contexts

Any class that implements the interface org.bibop.xml.xforge.XForgeContext can be used as a context with the VariablesBroker. The interface basically means that the class has to be able to calculate its own, unique contextId.

Additionally, a context may implement the interface org.bibop.xml.xforge.ContextEventListener, which is good for monitoring its lifecycle. Here are the interface definitions: 

org.bibop.xml.xforge.XForgeContext:

public String getContextId() throws XForgeException;


org.bibop.xml.xforge.ContextEventListener:

public void beforeStart() throws XForgeException;
public void afterStart() throws XForgeException;
public void beforeEnd() throws XForgeException;
public void afterEnd() throws XForgeException;

Using Contexts with the VariablesBroker

The VariablesBroker supports a number of operations on contexts: 

MyContext myContext = new MyContext();
Object myObject = new Object();

broker.startContextScope(myContext);

broker.putObject(myContext,"myKey",myObject);

(MyObject)broker.getObject(new MyContext(),"myKey");

broker.endContextScope(myContext);

A context's scope must be started, before objects can be stored in or retrieved from it. During the start phase the methods beforeStart() and afterStart() from the above-mentioned interface ContextEventListener are executed, during the end phase the methods beforeEnd() and afterEnd() are executed.

Using Contexts in XML

It is also possible to access objects from a context in an XML resource. Example from test/all.xml: 


<contexttest xmlns:thread="http://xforge.org/xforge/
				  3.0/context/org.bibop.xml.xforge.helpers.ThreadContext">
    A serialized object from the thread context: <xf:get name="thread:testfile"/>
</contexttest>

Resulting XML


<contexttest xmlns:thread="http://xforge.org/xforge/
			          3.0/context/org.bibop.xml.xforge.helpers.ThreadContext">
    A serialized object from the thread context: test/all.xml
</contexttest>

Errors

Known Error Conditions

  • A null-context was started.
  • A context gives null or "" as its contextId.
  • An object was stored in a context, whose name was null or "".
  • An object was retrieved from a context, which was not previously defined and started.
  • An object was retrieved from a context and its value was null.
  • There is no object with the given key in the referenced context.

Error Handling

All exceptions are thrown back to the caller. Here is an example:


Exception message: context cannot be null
org.bibop.xml.xforge.XForgeException: context cannot be null
        at org.bibop.xml.xforge.VariablesBroker.startContextScope(VariablesBroker.java:74)
        at org.bibop.xml.xforge.Test.test(Test.java:199)
        at org.bibop.xml.xforge.Test.main(Test.java:122)