org.glassfish.contextpropagation.spi

Interface ContextMapPropagator

public interface ContextMapPropagator

Used by messaging protocols to integrate with the context-propagation framework.

Method Summary

Modifier and Type	Method and Description
void	receiveRequest(InputStream in) Deserializes context from an InputStream provided by a protocol that is receiving a request.
void	receiveResponse(InputStream in, PropagationMode mode) Deserializes context from an InputStream provided by a protocol that is receiving a request.
void	restoreThreadContexts(AccessControlledMap contexts) Copies the entries that have the propagation mode THREAD to this thread's ContextMap.
void	sendRequest(OutputStream out, PropagationMode propagationMode) Transfers the entries with the specified PropagationMode from ContextMaps, in thread-local storage, to the protocol OutputStream while it is sending an out-bound request.
void	sendResponse(OutputStream out, PropagationMode propagationMode) Transfers the entries with the specified PropagationMode from ContextMaps, in thread-local storage, to the protocol OutputStream while it is sending an out-bound response.
void	useWireAdapter(WireAdapter wireAdapter) A protocol that propagates context data can choose an alternate WireAdapter, and thus a different encoding format on the wire.

Method Detail

sendRequest

void sendRequest(OutputStream out,
                 PropagationMode propagationMode)
          throws IOException

Transfers the entries with the specified PropagationMode from ContextMaps, in thread-local storage, to the protocol OutputStream while it is sending an out-bound request. This must be called at the appropriate time before any thread context-switches. This call does not affect the contents of thread-local storage in any way.

Parameters:

out - TheOutputStream that the protocol wants the data written to

propagationMode - The PropagationMode being utilized in this call. Only entries that support that propagation mode are propagated.

Throws:

IOException - if the data cannot be serialized.

sendResponse

void sendResponse(OutputStream out,
                  PropagationMode propagationMode)
           throws IOException

Transfers the entries with the specified PropagationMode from ContextMaps, in thread-local storage, to the protocol OutputStream while it is sending an out-bound response. This must be called at the appropriate time before any thread context-switches. This call does not affect the contents of thread-local storage in any way.

Parameters:

out - TheOutputStream that the protocol wants the data written to

propagationMode - The PropagationMode being utilized in this call. Only entries that support that propagation mode are propagated.

Throws:

IOException - if the data cannot be serialized.

receiveRequest

void receiveRequest(InputStream in)
             throws IOException

Deserializes context from an InputStream provided by a protocol that is receiving a request. This must be called at the appropriate time after any thread context-switches. All existing thread-local contexts are overwritten, although in general the thread execution model should ensure that there are no existing thread-local contexts. While the receiver will attempt to read all and only the context propagation data, it may not do so under unusual circumstances such as when there is a bug in a third-party context implementation. For that reason, if IOException is thrown, the sender is responsible for positioning the stream to the point immediately after the context-propagation data.

Parameters:

in - A InputStream provided by the protocol and containing the serialized contexts serialized context propagation bytes and no more.

Throws:

IOException - if the data cannot be read.

receiveResponse

void receiveResponse(InputStream in,
                     PropagationMode mode)
              throws IOException

Deserializes context from an InputStream provided by a protocol that is receiving a request. This must be called at the appropriate time after any thread context-switches. All existing thread-local contexts with the specified propagation mode are removed before the context entries are read from the specified input stream in may be null which means that the remote server removed all of the contexts with propagation modes that include the specified propagation mode.

Parameters:

in - A InputStream provided by the protocol and containing the serialized contexts serialized context propagation bytes and no more. Its read methods must return -1 when the end of the context data has been reached

mode - The PropagationMode associated to the protocol invoking this method.

Throws:

IOException - if the data cannot be read.

restoreThreadContexts

void restoreThreadContexts(AccessControlledMap contexts)

Copies the entries that have the propagation mode THREAD to this thread's ContextMap.

Parameters:

contexts - an ContextMapInterceptor obtained via #copyThreadContexts.

useWireAdapter

void useWireAdapter(WireAdapter wireAdapter)

A protocol that propagates context data can choose an alternate WireAdapter, and thus a different encoding format on the wire.

Parameters:

wireAdapter -