BDLContextProvider

java.lang.Object
- brown.tracingplane.impl.BDLContextProvider

All Implemented Interfaces:

BaggageProvider<BDLContext>
```
public class BDLContextProvider
extends java.lang.Object
implements BaggageProvider<BDLContext>
```
BaggageProvider for BDLContext, which extends NestedBaggageContext to provide object representations for a range of data types, and to convert to and from those object representations using BDL-generated classes.

BDLContextProvider has several static API methods for getting and setting objects within BaggageContext instances. In general, you should not need to use these methods directly; instead, they are used by the BDL-generated accessors.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addListener(BaggageListener.BranchListener<BDLContext> listener)` Registers a `BaggageListener.BranchListener` that will be invoked any time `branch(BDLContext)` is invoked.
`void`	`addListener(BaggageListener.JoinListener<BDLContext> listener)` Registers a `BaggageListener.JoinListener` that will be invoked any time `join(BDLContext, BDLContext)` is invoked.
`BDLContext`	`branch(BDLContext from)` Create and return a copy of `from`.
`BDLContext`	`compact(BDLContext left, BDLContext right)` Additional operation provided by `BDLContext` to compact a context.
`BDLContext`	`deserialize(byte[] serialized, int offset, int length)` Deserialize the provided serialized baggage representation.
`BDLContext`	`deserialize(java.nio.ByteBuffer buf)` Deserialize the provided serialized baggage representation.
`void`	`discard(BDLContext baggage)` Discards `baggage`.
`static Bag`	`get(BaggageContext baggage, BagKey key)` This method fetches the object stored in the provided `BaggageContext` under the specified key, or returns null if there is no object present.
`boolean`	`isValid(BaggageContext baggage)`
`BDLContext`	`join(BDLContext left, BDLContext right)` Merge the contents of `left` and `right` and return as baggage.
`BDLContext`	`newInstance()`
`byte[]`	`serialize(BDLContext baggage)` Serialize the provided baggage instance to its byte representation.
`byte[]`	`serialize(BDLContext baggage, int maximumSerializedSize)` Serialize the provided baggage instance to its byte representation and trim the baggage so that its serialized size is `<= maximumSerializedSize`.
`static BaggageContext`	`set(BaggageContext baggage, BagKey key, Bag value)` Maps the specified key to the provided bag value.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - isValid
```
public boolean isValid(BaggageContext baggage)
```
    Specified by:
    
    isValid in interface BaggageProvider<BDLContext>
    
    Parameters:
    
    baggage - a BaggageContext to test
    
    Returns:
    
    true if baggage is an instance of B or if baggage is null.
  - newInstance
```
public BDLContext newInstance()
```
    Specified by:
    
    newInstance in interface BaggageProvider<BDLContext>
    
    Returns:
    
    a new instance of B, which may be null to indicate an empty baggage
  - discard
```
public void discard(BDLContext baggage)
```
    Description copied from interface: BaggageProvider
    
    Discards baggage. If this TransitLayer performs anything like reference counting, then this method is where decrementing reference counts would happen.
    
    Specified by:
    
    discard in interface BaggageProvider<BDLContext>
    
    Parameters:
    
    baggage - a baggage instance
  - branch
```
public BDLContext branch(BDLContext from)
```
    Description copied from interface: BaggageProvider
    
    Create and return a copy of from. If this TransitLayer performs anything like reference counting, then this method might just return from while incrementing reference counts. This method might create a new instance of B and might even modify the contents of from
    
    Specified by:
    
    branch in interface BaggageProvider<BDLContext>
    
    Parameters:
    
    from - a baggage instance, possibly null
    
    Returns:
    
    a baggage instance branched from from, possibly null
  - addListener
```
public void addListener(BaggageListener.BranchListener<BDLContext> listener)
```
    Registers a BaggageListener.BranchListener that will be invoked any time branch(BDLContext) is invoked.
    
    Parameters:
    
    listener - a BaggageListener.BranchListener
  - join
```
public BDLContext join(BDLContext left,
                       BDLContext right)
```
    Description copied from interface: BaggageProvider
    
    Merge the contents of left and right and return as baggage. left and right should be treated as discarded (or reused) after this method call.
    
    Specified by:
    
    join in interface BaggageProvider<BDLContext>
    
    Parameters:
    
    left - a baggage instance, possibly null
    
    right - a baggage instance, possibly null
    
    Returns:
    
    a baggage instance with merged contents from left and right
  - compact
```
public BDLContext compact(BDLContext left,
                          BDLContext right)
```
    Additional operation provided by BDLContext to compact a context. This is a prototype, its behavior is datatype-dependent and generally should not be used. Its implementation is kinda hacky since I'm not sure if this should be incorporated into the main API yet. Currently only CounterImpl actually implements compaction.
  - addListener
```
public void addListener(BaggageListener.JoinListener<BDLContext> listener)
```
    Registers a BaggageListener.JoinListener that will be invoked any time join(BDLContext, BDLContext) is invoked.
    
    Parameters:
    
    listener - a BaggageListener.JoinListener
  - deserialize
```
public BDLContext deserialize(byte[] serialized,
                              int offset,
                              int length)
```
    Description copied from interface: BaggageProvider
    
    Deserialize the provided serialized baggage representation.
    
    Specified by:
    
    deserialize in interface BaggageProvider<BDLContext>
    
    Parameters:
    
    serialized - a serialized baggage
    
    offset - offset into the array where the baggage bytes begin
    
    length - lenft of the baggage bytes
    
    Returns:
    
    a deserialized baggage instance, possibly null
  - deserialize
```
public BDLContext deserialize(java.nio.ByteBuffer buf)
```
    Description copied from interface: BaggageProvider
    
    Deserialize the provided serialized baggage representation.
    
    Specified by:
    
    deserialize in interface BaggageProvider<BDLContext>
    
    Parameters:
    
    buf - a serialized baggage
    
    Returns:
    
    a deserialized baggage instance, possibly null
  - serialize
```
public byte[] serialize(BDLContext baggage)
```
    Description copied from interface: BaggageProvider
    
    Serialize the provided baggage instance to its byte representation. This method should behave as though #branch(Baggage) is also being called prior to serialization.
    
    Specified by:
    
    serialize in interface BaggageProvider<BDLContext>
    
    Parameters:
    
    baggage - a baggage instance to serialize, possibly null
    
    Returns:
    
    the serialized representation of baggage, which might be null or an empty byte array
  - serialize
```
public byte[] serialize(BDLContext baggage,
                        int maximumSerializedSize)
```
    Description copied from interface: BaggageProvider
    
    Serialize the provided baggage instance to its byte representation and trim the baggage so that its serialized size is <= maximumSerializedSize. This method should behave as though #branch(Baggage) is also being called prior to serialization.
    
    Specified by:
    
    serialize in interface BaggageProvider<BDLContext>
    
    Parameters:
    
    baggage - a baggage instance to serialize, possibly null
    
    maximumSerializedSize - the maximum size in bytes of the serialized baggage.
    
    Returns:
    
    the serialized representation of baggage, which might be null or an empty byte array
  - get
```
public static Bag get(BaggageContext baggage,
                      BagKey key)
```
    This method fetches the object stored in the provided BaggageContext under the specified key, or returns null if there is no object present.
    
    This method is typically invoked by BDL-generated classes when calling the getFrom(BaggageContext) method. For example, if we generated a bag called XTraceBaggage and registered it to BagKey.indexed(7), then a call to get(BaggageContext, BagKey.indexed(7)) would return either null (if there is no XTraceBaggage instance present), or an instance of XTraceBaggage.
    
    Parameters:
    
    baggage - a BaggageContext instance, expected to be an instance of BDLContext
    
    key - the key to look up
    
    Returns:
    
    if baggage is an instance of BDLContext, returns the object mapped to key if there is one. Otherwise, returns null.
  - set
```
public static BaggageContext set(BaggageContext baggage,
                                 BagKey key,
                                 Bag value)
```
    Maps the specified key to the provided bag value. This method possibly modifies the provided baggage instance, or might return a new instance depending on whether baggage is modifiable.
    
    To construct a new BaggageContext with the specified mapping, simply pass null for baggage.
    
    Parameters:
    
    baggage - the baggage to modify, which may be null, indicating the empty baggage.
    
    key - the key to update
    
    bag - the new bag to map to this key
    
    Returns:
    
    a possibly new baggage instance with the updated mapping.

Class BDLContextProvider

Method Summary

Methods inherited from class java.lang.Object

Method Detail

isValid

newInstance

discard

branch

addListener

join

compact

addListener

deserialize

deserialize

serialize

serialize

get

set