io.reactivex.netty.contexts

Interface ContextsContainer

All Known Implementing Classes:

ContextsContainerImpl

public interface ContextsContainer

A contract to hold multiple request level contexts.
All implementations must be thread safe.

Method Summary

Modifier and Type	Method and Description
void	addContext(java.lang.String contextName, java.lang.String context) Adds a custom String context to this request scope.
<T> void	addContext(java.lang.String contextName, T context, ContextSerializer<T> serializer) Adds a custom context (arbitrary object) to this container.
void	consumeBidirectionalContextsFromResponse(ContextKeySupplier contextKeySupplier) Reads the bi-directional contexts from the HTTP response and updates this ContextsContainer with those contexts.
<T> T	getContext(java.lang.String contextName) Retrieves the value of the context added previously in this request scope via addContext(String, String) or addContext(String, Object, ContextSerializer) The context could have been set in a different service and transferred here on the wire.
<T> T	getContext(java.lang.String contextName, ContextSerializer<T> serializer) Retrieves the value of the context added previously in this request scope via addContext(String, String) or addContext(String, Object, ContextSerializer) The context could have been set in a different service and transferred here on the wire.
java.util.Map<java.lang.String,java.lang.String>	getModifiedBidirectionalContexts() Map of bi-directional context names and values (serialized form) that were modified within the current application.
java.util.Map<java.lang.String,java.lang.String>	getSerializedContexts() Map of context names and values (serialized form) associated with this request.
boolean	removeContext(java.lang.String contextName) Removes a context with name contextName added previously in this request scope via addContext(String, String) or addContext(String, Object, ContextSerializer) The context could have been set in a different service and transferred here on the wire.

Method Detail

addContext

<T> void addContext(java.lang.String contextName,
                    T context,
                    ContextSerializer<T> serializer)

Adds a custom context (arbitrary object) to this container.

This context will be passed for all outbound service calls made by RxClient.
Serialization/de-serialization mechanism for this context will be delegated to serializer. Serialization will be done when an outbound service call is made, to send this context on the wire.

De-serialization will be done in the outbound service for the above call, if and only if, a client invokes getContext(String) for the same context name. This method overwrites any existing value with the passed context name.

Context updates:

If the context is mutable, then every mutation should add the context back here otherwise, the mutation will be lost when the context gets passed to a remote application.

Bi-directional contexts:

The following scenario counts as an update to a bi-directional context:

• The added context is bi-directional.
• There already is a value associated with this context name.
• The associated value is of the same class as the new value.
• The associated value is not equal to the new value as indicated by Object.equals(Object)

In case this is actually an update, any subsequent calls to getModifiedBidirectionalContexts() will also include this context.

Type Parameters:

T - Type of the context.

Parameters:

contextName - Name of the context.

context - Context instance.

serializer - Serializer for the context.

Throws:

java.lang.IllegalArgumentException - If any of the arguments are null.

getModifiedBidirectionalContexts

java.util.Map<java.lang.String,java.lang.String> getModifiedBidirectionalContexts()
                                                                           throws ContextSerializationException

Map of bi-directional context names and values (serialized form) that were modified within the current application. See BiDirectional for details.

Returns:

Immutable map of name and value of the contexts. Empty map if none present.

Throws:

ContextSerializationException - If the serialization fails.

consumeBidirectionalContextsFromResponse

void consumeBidirectionalContextsFromResponse(ContextKeySupplier contextKeySupplier)
                                       throws ContextSerializationException

Reads the bi-directional contexts from the HTTP response and updates this ContextsContainer with those contexts.

Parameters:

contextKeySupplier - The ContextKeySupplier for the response.

Throws:

ContextSerializationException - If the de-serialization of the bidrectional context fails.

addContext

void addContext(java.lang.String contextName,
                java.lang.String context)

Adds a custom String context to this request scope.
This has exactly the same effect as calling addContext(String, Object, ContextSerializer) with the serializer as StringSerializer

Parameters:

contextName - Name of the context.

context - Context instance.

Throws:

java.lang.IllegalArgumentException - If any of the arguments are null.

removeContext

boolean removeContext(java.lang.String contextName)

Removes a context with name contextName added previously in this request scope via addContext(String, String) or addContext(String, Object, ContextSerializer)

The context could have been set in a different service and transferred here on the wire.

Parameters:

contextName - Name of the context to remove.

Returns:

true if the context existed and was removed. false if the context did not exist.

getContext

<T> T getContext(java.lang.String contextName)
          throws ContextSerializationException

Retrieves the value of the context added previously in this request scope via addContext(String, String) or addContext(String, Object, ContextSerializer)

The context could have been set in a different service and transferred here on the wire. In such a case, the serializer passed during addition of the context will be used for de-serialization.

All values of the context after de-serialization are cached, unless overwritten by a corresponding addContext(String, Object, ContextSerializer). Also, the serializer instance will be cached once created.

Parameters:

contextName - Name of the context.

Throws:

ContextSerializationException

getContext

<T> T getContext(java.lang.String contextName,
                 ContextSerializer<T> serializer)
          throws ContextSerializationException

Retrieves the value of the context added previously in this request scope via addContext(String, String) or addContext(String, Object, ContextSerializer)

The context could have been set in a different service and transferred here on the wire. In such a case, the serializer passed will be used for de-serialization and the serializer passed during context addition will be ignored.

Word of caution: If the value is cached as a result of a prior invocation of this method or getContext(String), the passed serializer will not be used.

This method should only be used if your serializer is stateful or requires custom initializations. Otherwise, the serializer associated with this context must be used i.e. by calling getContext(String)

All values of the context after de-serialization are cached, unless overwritten by a corresponding addContext(String, Object, ContextSerializer). Also, the serializer instance will be cached once created.

Parameters:

contextName - Name of the context.

serializer - The serializer instance to use if the context is required to be de-serialized.

Throws:

ContextSerializationException

getSerializedContexts

java.util.Map<java.lang.String,java.lang.String> getSerializedContexts()
                                                                throws ContextSerializationException

Map of context names and values (serialized form) associated with this request.

Returns:

Immutable map of name and value of the contexts. Empty map if none present.

Throws:

ContextSerializationException - If the serialization fails.