Overview

Context is essentially a bag of properties with a well-defined lifecycle.

public interface Context {
    Object getProperty(String name);
    Map<String, Object> getProperties();
    boolean hasProperty(String name);
    Object removeProperty(String name);
    void setProperty(String name, Object val);
}

Each context has an associated scope, which serves to isolate individual contexts and defines the life cycle of a context.

public interface Exchange {  
    Context getContext();
    Context getContext(Scope scope);
    ...
}

public enum Scope {
    CORRELATION,
    EXCHANGE,
    MESSAGE;
}

The following scopes are currently defined:

• Correlation : context which can be propagated across service invocations (i.e. exchanges).
• Exchange : context which is specific to a given service invocation.  This   context should not be propagated automatically between exchanges.
• Message : context specific to a message within an exchange.  Individual   messages within an exchange may have duplicate context properties with   different values.

Scope Use Cases

The following use cases are an attempt to describe situations in which properties belong in a given scope based on the expectations for how  the  properties will be used and how long they are relevant in the  context  of the service invocation.  This is not an exhaustive nor is it  a proscriptive list of context properties and their associated scopes.

Message (In, Out, Fault)

Message   scope provides a way to associate context with a specific message in  an exchange.  Use cases which require an isolated context for each  message include:

• Assigning a unique identifier for a  message,  independent of the enclosing exchange.  This can be useful  when client  retry logic kicks in and attempts to send a message  multiple times (e.g.  WS-RM).  A new exchange is created with each try,  so the exchange ID  alone is not relevant.  The service implementation  or a handler can use  an identifier in the message context to perform  de-duping.
• Associating  security credentials with a message.   Attaching security credentials to  the exchange scope may be  inappropriate if separate credentials are  used for the request and  reply messages.
• Attaching relevant protocol and environment details to a message

Exchange

• Protocol or environmental properties that apply to the entire invocation.
• Service metadata such as the operation name
• Attaching processing hints and results from intermediate execution steps (e.g. handler logic)
• Addressing (from, to, etc.) information
• Transaction information   
  • need   to walk through this in more detail to determine if it's simply a flag   indicating the the exchange is being delivered in the context of a   transaction or if we need a getter for the actual Transaction object

Correlation

Correlation   scoped context is useful for sharing context across service   invocations.  Here are some use cases that rely on propagation of   correlation context between related exchanges.

• Associating a business key (e.g. order number) with a set of related business exchanges (e.g. order, order ack, invoice, etc.)
• Assigning a conversation identifier that can be used in BPM engines to reconcile process state
• Using a common log prefix so that related activities can be collated in server logs
• Using a common activity key to feed into higher level BAM reporting
• Storing   the result of service operations so that they do not have to be   repeated (e.g. resolution of a unique identifier for a customer)