Commit bdf90859 authored by Jonathan Mace's avatar Jonathan Mace

Add tracingplane-core files

parent 893bca35
# Tracing Plane - Core
Defines two core Tracing Plane interfaces - `BaggageContext` and `BaggageProvider`.
\ No newline at end of file
package brown.tracingplane;
/**
* <p>
* A {@link BaggageContext} is an opaque context object belonging to an execution. Baggage contexts are propagated
* alongside requests as they execute -- they should be passed to new threads, included with work items (e.g.,
* {@link java.lang.Runnable}, {@link java.util.concurrent.Callable}, etc.), serialized in network headers, and so on.
* </p>
*
* <p>
* {@link BaggageContext} objects have no direct methods for manipulating contexts or accessing data that they carry.
* This is because, in the common case, a {@link BaggageContext} is typically empty, and an empty context is typically
* implemented using null values.
* </p>
*
* <p>
* To propagate {@link BaggageContext} objects, call {@link BaggageProvider} methods such as
* {@link BaggageProvider#branch(BaggageContext)}, {@link BaggageProvider#serialize(BaggageContext)}, etc.
* </p>
*/
public interface BaggageContext {
}
package brown.tracingplane;
import java.nio.ByteBuffer;
/**
* <p>
* A {@link BaggageProvider} provides an implementation of {@link BaggageContext} objects. Manipulation of
* {@link BaggageContext} objects is primarily done through {@link BaggageProvider} methods.
* </p>
*/
public interface BaggageProvider<B extends BaggageContext> {
/**
* @return a new instance of {@link B}, which may be null to indicate an empty baggage
*/
public B newInstance();
/**
* Discards <code>baggage</code>. If this TransitLayer performs anything like reference counting, then this method
* is where decrementing reference counts would happen.
*
* @param baggage a baggage instance
*/
public void discard(B baggage);
/**
* Create and return a copy of <code>from</code>. If this TransitLayer performs anything like reference counting,
* then this method might just return <code>from</code> while incrementing reference counts.
*
* This method might create a new instance of {@link B} and might even modify the contents of <code>from</code>
*
* @param from a baggage instance, possibly null
* @return a baggage instance branched from <code>from</code>, possibly null
*/
public B branch(B from);
/**
* Merge the contents of <code>left</code> and <code>right</code> and return as baggage. <code>left</code> and
* <code>right</code> should be treated as discarded (or reused) after this method call.
*
* @param left a baggage instance, possibly null
* @param right a baggage instance, possibly null
* @return a baggage instance with merged contents from <code>left</code> and <code>right</code>
*/
public B join(B left, B right);
/**
* Deserialize the provided serialized baggage representation.
*
* @param serialized a serialized baggage
* @param offset offset into the array where the baggage bytes begin
* @param length lenft of the baggage bytes
* @return a deserialized baggage instance, possibly null
*/
public B deserialize(byte[] serialized, int offset, int length);
/**
* Deserialize the provided serialized baggage representation.
*
* @param buf a serialized baggage
* @return a deserialized baggage instance, possibly null
*/
public B deserialize(ByteBuffer buf);
/**
* Serialize the provided baggage instance to its byte representation. This method should behave as though
* {@link #branch(Baggage)} is also being called prior to serialization.
*
* @param baggage a baggage instance to serialize, possibly null
* @return the serialized representation of <code>baggage</code>, which might be null or an empty byte array
*/
public byte[] serialize(B baggage);
/**
* Serialize the provided baggage instance to its byte representation and trim the baggage so that its serialized
* size is {@code <= maximumSerializedSize}. This method should behave as though {@link #branch(Baggage)} is also
* being called prior to serialization.
*
* @param baggage a baggage instance to serialize, possibly null
* @param maximumSerializedSize the maximum size in bytes of the serialized baggage.
* @return the serialized representation of <code>baggage</code>, which might be null or an empty byte array
*/
public byte[] serialize(B baggage, int maximumSerializedSize);
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment