brown.tracingplane

Class ActiveBaggage

java.lang.Object

brown.tracingplane.ActiveBaggage

public class ActiveBaggage
extends java.lang.Object

Extends the static Baggage API with further methods for saving, retrieving, and interacting with BaggageContext instances using the default TransitLayer.

Unlike the Baggage interface, ActiveBaggage implicitly accesses the currently-active BaggageContext that is being managed by the TransitLayer. Unless it has been configured otherwise, this entails looking up the BaggageContext in thread-local storage.

This class also provides static methods to get and set the currently active baggage. These methods proxy to the configured TransitLayer, which is responsible for maintaining active baggage (e.g., in thread-local storage).

If you wish to manipulate BaggageContext instances without affecting the currently active baggage context, use the static methods on the Baggage class.

Using this class requires that a BaggageProvider has been registered (e.g., using the baggage.provider property). By default, the TransitLayer used will be ThreadLocalTransitLayer; this can be overridden using baggage.transit.

Method Summary

Modifier and Type	Method and Description
static BaggageContext	branch() Create and return a branched copy of the currently active baggage context.
static byte[]	branchBytes() Create and return a branched, serialized copy of the currently active baggage context.
static void	discard() Discard the currently active BaggageContext.
static void	join(BaggageContext otherContext) Merges the contents of otherContext into the currently active context.
static void	join(byte[] serialized, int offset, int length) Deserializes the provided context and merges it into the currently active context.
static void	join(java.nio.ByteBuffer serializedContext) Deserializes the provided context and merges it into the currently active context.
static BaggageContext	peek() Gets the currently active BaggageContext.
static void	set(BaggageContext baggage) Discards the currently active BaggageContext, then activates the provided baggage.
static void	set(byte[] serialized, int offset, int length) Deserializes the provided context and merges it into the currently active context.
static void	set(java.nio.ByteBuffer serializedContext) Deserializes the provided context, discards any currently active context, and replaces it with the deserialized context.
static BaggageContext	take() Gets and removes the currently active BaggageContext.
static byte[]	takeBytes() Gets, removes, and serializes the currently active BaggageContext.
static void	update(BaggageContext baggage) Sets the currently active BaggageContext.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

discard

public static void discard()

Discard the currently active BaggageContext.

branch

public static BaggageContext branch()

Create and return a branched copy of the currently active baggage context. Typically, this will just duplicate the active context or increment a reference count. Sometimes it will create a new instance, or even modify the contents of the branched context.

Returns:

a baggage instance branched from the currently active context, possibly null

branchBytes

public static byte[] branchBytes()

Create and return a branched, serialized copy of the currently active baggage context. Typically, this will just duplicate the active context or increment a reference count. Sometimes it will create a new instance, or even modify the contents of the branched context.

Returns:

a baggage instance branched from the currently active context and serialized, possibly null

join

public static void join(BaggageContext otherContext)

Merges the contents of otherContext into the currently active context. otherContext should not be reused after calling this method, and should be treated as discarded.

Parameters:

otherContext - another baggage context, possibly null

join

public static void join(java.nio.ByteBuffer serializedContext)

Deserializes the provided context and merges it into the currently active context.

Parameters:

serializedContext - a serialized baggage context, possibly null

join

public static void join(byte[] serialized,
                        int offset,
                        int length)

Deserializes the provided context and merges it into the currently active context.

Parameters:

serialized - a serialized baggage context, possibly null

offset - offset into byte array

length - length of bytes to use

set

public static void set(BaggageContext baggage)

Discards the currently active BaggageContext, then activates the provided baggage. If baggage is just a modified version of the currently active BaggageContext, then it is better to use the update(BaggageContext) method instead.

Parameters:

baggage - The new baggage context to activate.

set

public static void set(java.nio.ByteBuffer serializedContext)

Deserializes the provided context, discards any currently active context, and replaces it with the deserialized context.

Parameters:

serializedContext - a serialized baggage context, possibly null

set

public static void set(byte[] serialized,
                       int offset,
                       int length)

Deserializes the provided context and merges it into the currently active context.

Parameters:

serialized - a serialized baggage context, possibly null

offset - offset into the byte array

length - length of serialized bytes

take

public static BaggageContext take()

Gets and removes the currently active BaggageContext. After calling this method, there will be no active BaggageContext.

Returns:

the current BaggageContext.

takeBytes

public static byte[] takeBytes()

Gets, removes, and serializes the currently active BaggageContext. After calling this method, there will be no active BaggageContext.

Returns:

the current BaggageContext.

peek

public static BaggageContext peek()

Gets the currently active BaggageContext. The BaggageContext instance remains active after calling this method. Use take() to if you wish to get and remove the currently active context.

Returns:

the active BaggageContext

update

public static void update(BaggageContext baggage)

Sets the currently active BaggageContext. A call to this method implies that the provided context argument is an updated version of the active context. Conversely, if you intend to replace the currently active context (e.g., because a different execution is beginning), use the set(BaggageContext) method.

Parameters:

context - an updated version of the currently active baggage context.