Commit 789d7ec5 authored by Jonathan Mace's avatar Jonathan Mace

Updates to Javadocs

parent 564e83be
package brown.tracingplane;
/**
* It wouldn't be Java without a camel-case caravan of nouns.
* <p>
* Factory for {@link BaggageProvider} instances; primarily used to configure the {@link BaggageProvider} used by the
* {@link Baggage} static API.
* </p>
*
* <p>
* {@link BaggageProviderFactory} is expected to have a no-arg constructor so that it can be instantiated by reflection.
* </p>
*/
public interface BaggageProviderFactory {
......
......@@ -4,8 +4,7 @@ import java.nio.ByteBuffer;
/**
* <p>
* The static methods in the {@link Baggage} class are the main entry point for manipulating {@link BaggageContext}
* instances. The methods here mirror those provided by the {@link BaggageProvider} interface.
* The static API for manipulating {@link BaggageContext} instances using the default {@link BaggageProvider}.
* <p>
*
* <p>
......
......@@ -10,8 +10,7 @@ import brown.tracingplane.impl.NoOpBaggageContextProviderFactory;
/**
* <p>
* Loads the default configured {@link BaggageProvider} using reflection. Checks the <code>baggage.provider</code>
* property.
* Loads the {@link BaggageProviderFactory} specified by <code>baggage.provider</code> using reflection.
* </p>
*/
public class DefaultBaggageProvider {
......
/**
* <p>
* Implementations of {@link BaggageContext} at several different points in the Tracing Plane.
* </p>
*
* <p>
* {@link AtomContext} is the most lightweight atom-based context, which provides no accessor or convenience methods for
* manipulating data. {@link AtomContext} is purely for propagation (e.g., forwarding baggage contexts that you received
* from other network calls).
* </p>
*
* <p>
* {@link NestedBaggageContext} extends the Atom Context and implements the Baggage Protocol, which gives nested data
* structures.
* </p>
*
* <p>
* {@link BDLContext} is the full-featured baggage context, which provides interpretations for different data types
* using atoms.
* </p>
*
*/
package brown.tracingplane.impl;
......@@ -4,10 +4,14 @@ import java.nio.ByteBuffer;
/**
* <p>
* {@link ActiveBaggage} provides static methods that mirror the methods implemented by {@link BaggageProvider} and
* {@link TransitLayer}. Unlike the {@link brown.tracingplane.Baggage} interface, {@link ActiveBaggage} implicitly
* accesses the currently-active {@link BaggageContext} that is being managed by the {@link TransitLayer}. Unless it has
* been configured otherwise, this entails looking up the {@link BaggageContext} in thread-local storage.
* Extends the static {@link Baggage} API with further methods for saving, retrieving, and interacting with
* {@link BaggageContext} instances using the default {@link TransitLayer}.
* <p>
*
* <p>
* Unlike the {@link brown.tracingplane.Baggage} interface, {@link ActiveBaggage} implicitly accesses the
* currently-active {@link BaggageContext} that is being managed by the {@link TransitLayer}. Unless it has been
* configured otherwise, this entails looking up the {@link BaggageContext} in thread-local storage.
* </p>
*
* <p>
......
......@@ -10,8 +10,7 @@ import brown.tracingplane.impl.ThreadLocalTransitLayer;
/**
* <p>
* Loads the default configured {@link TransitLayer} using reflection. Checks the <code>baggage.transit</code> property.
* If <code>baggage.transit</code> is not set, then the default transit layer will be {@link ThreadLocalTransitLayer}.
* Loads the {@link TransitLayerFactory} specified by <code>baggage.transit</code> using reflection.
* </p>
*/
public class DefaultTransitLayer {
......
......@@ -3,6 +3,12 @@ package brown.tracingplane;
import java.nio.ByteBuffer;
/**
* <p>
* Maintains {@link BaggageContext} instances for requests. Most {@link TransitLayer} implementations will store
* {@link BaggageContext} instances using thread-local storage; this interface primarily exists to support wrappers to
* other implementations (e.g., OpenTracing).
* </p>
*
* <p>
* The static methods in the {@link ActiveBaggage} interface proxy to a {@link TransitLayer} implementation. Typically
* this implementation will be {@link ThreadLocalTransitLayer}, which maintains an active {@link BaggageContext}
......
package brown.tracingplane;
/**
* It wouldn't be Java without a camel-case caravan of nouns.
* <p>
* Factory for {@link TransitLayer} instances; primarily used to configure the {@link TransitLayer} used by the
* {@link ActiveBaggage} static API.
* </p>
*
* <p>
* {@link TransitLayerFactory} is expected to have a no-arg constructor so that it can be instantiated by reflection.
* </p>
*/
public interface TransitLayerFactory {
......
......@@ -171,6 +171,7 @@ public class AtomPrefixTypes {
}
/** Some bag options are contained within the header prefix -- currently only the {@link MergeBehavior} */
public static class BagOptionsInPrefix {
public static final int mask = 0x01;
......
......@@ -68,7 +68,10 @@ public class AtomPrefixes {
}
}
/** AtomPrefix has some convenience methods for checking what kind of prefix a byte is and what it supports */
/**
* The first byte of an atom is its prefix, which contains some metadata about the atom; the first bit of an atom
* denotes whether it is a data atom or header atom.
*/
public static abstract class AtomPrefix implements Comparable<AtomPrefix> {
protected final AtomType atomType;
......@@ -101,6 +104,7 @@ public class AtomPrefixes {
}
}
/** The first byte of a header atom also specifies whether it is indexed or keyed, and the header's level */
public static abstract class HeaderPrefix extends AtomPrefix {
public static final AtomType atomType = AtomType.Header;
......@@ -151,6 +155,10 @@ public class AtomPrefixes {
}
/**
* The payload of an indexed header is expected to be an unsigned variable-length lexicographically consistent
* integer: {@link brown.tracingplane.atomlayer.UnsignedLexVarint}
*/
public static class IndexedHeaderPrefix extends HeaderPrefix {
public static final HeaderType headerType = HeaderType.Indexed;
......@@ -191,6 +199,10 @@ public class AtomPrefixes {
}
/**
* The payload of a keyed header is expected to be arbitrary length bytes. It can often be interpreted as a String,
* though this is not a requirement.
*/
public static class KeyedHeaderPrefix extends HeaderPrefix {
public static final HeaderType headerType = HeaderType.Keyed;
......
......@@ -15,7 +15,9 @@ import brown.tracingplane.baggageprotocol.AtomPrefixes.AtomPrefix;
import brown.tracingplane.baggageprotocol.AtomPrefixes.HeaderPrefix;
import brown.tracingplane.baggageprotocol.BaggageLayerException.BaggageLayerRuntimeException;
/** TODO: documentation */
/**
* Iterates over a list of atoms, interpreting them according to the baggage protocol; readers interpret data atoms and construct corresponding object representations.
*/
public class BaggageReader implements ElementReader {
private static final Logger log = LoggerFactory.getLogger(BaggageReader.class);
......
......@@ -2,6 +2,9 @@ package brown.tracingplane.baggageprotocol;
import java.nio.ByteBuffer;
/**
* Iterator-like interface for reading data atoms
*/
public interface ElementReader {
public boolean hasData();
......
......@@ -2,7 +2,9 @@ package brown.tracingplane.baggageprotocol;
import java.nio.ByteBuffer;
/** Used to restrict usage of writer */
/**
* Iterator-like interface for writing atoms.
*/
public interface ElementWriter {
public ByteBuffer newDataAtom(int expectedSize);
......
......@@ -11,9 +11,12 @@ import brown.tracingplane.baggageprotocol.BagKey;
import brown.tracingplane.baggageprotocol.BaggageWriter;
import brown.tracingplane.bdl.Bag;
/**
* <p>Helper methods for {@link BDLContext} instances -- calculating serialized size, printing context contents, etc.</p>
*/
public class BDLContextUtils {
private BDLContextUtils(){}
private BDLContextUtils() {}
/**
* Ideally, this is an instance method, but for now we're doing it here
......@@ -22,7 +25,7 @@ public class BDLContextUtils {
if (instance == null || !(instance instanceof BDLContext)) {
return 0;
} else {
return AtomLayerSerialization.serializedSize(((BDLContext)instance).serialize().atoms());
return AtomLayerSerialization.serializedSize(((BDLContext) instance).serialize().atoms());
}
}
......@@ -45,7 +48,7 @@ public class BDLContextUtils {
/**
* Ideally, this is an instance method, but for now we're doing it here
*/
public static int serializedSize (BagKey key, Bag bag) {
public static int serializedSize(BagKey key, Bag bag) {
if (bag != null) {
BaggageWriter writer = BaggageWriter.create();
writer.enter(key);
......@@ -59,22 +62,22 @@ public class BDLContextUtils {
}
return 0;
}
public static Map<String, String> getSizeSummary(BaggageContext instance) {
if (instance == null || !(instance instanceof BDLContext)) {
return Collections.emptyMap();
}
return getSizeSummary((BDLContext) instance);
}
public static Map<String, String> getSizeSummary(BDLContext instance) {
if (instance == null) {
return Collections.emptyMap();
return Collections.emptyMap();
}
Map<String, String> summary = new HashMap<>();
summary.put("BaggageTotalSize", String.valueOf(serializedSize(instance)));
if (instance.bags != null) {
for (BagKey key : instance.bags.keySet()) {
Bag bag = instance.bags.get(key);
......@@ -88,26 +91,36 @@ public class BDLContextUtils {
summary.put("OverflowAtoms", TypeUtils.toHexString(instance.overflowAtoms, ","));
}
if (instance.unprocessedAtoms != null) {
summary.put("UnprocessedAtoms", TypeUtils.toHexString(instance.overflowAtoms, ","));
summary.put("UnprocessedAtoms", TypeUtils.toHexString(instance.overflowAtoms, ","));
}
return summary;
}
/** Utility for seeing who accesses baggage and where */
public static interface BaggageAccessListener {
public boolean enter();
public void get(BagKey bagKey);
public void set(BagKey bagKey);
public void compact();
public void exit();
}
public static class NullBaggageListener implements BaggageAccessListener {
public boolean enter() { return false; }
public boolean enter() {
return false;
}
public void get(BagKey bagKey) {}
public void set(BagKey bagKey) {}
public void compact() {}
public void exit() {}
}
......
......@@ -2,6 +2,11 @@ package brown.tracingplane.bdl;
import brown.tracingplane.baggageprotocol.BaggageWriter;
/**
* <p>
* Provides serialization, deserialization, branch, and merge logic for a bag type.
* </p>
*/
public interface BaggageHandler<T extends Bag> extends Parser<T>, Serializer<T>, Joiner<T>, Brancher<T> {
public boolean isInstance(Bag bag);
......
......@@ -6,7 +6,7 @@ import java.util.Map;
import java.util.Set;
/**
* Branchers for built-in types used by compiled baggage buffers classes
* Branch logic for primitive BDL types {@link #noop()}, sets, and maps.
*/
public class Branchers {
......
......@@ -7,7 +7,7 @@ import brown.tracingplane.atomlayer.SignedLexVarint;
import brown.tracingplane.atomlayer.UnsignedLexVarint;
/**
* Functions for converting to and from built-in baggagebuffers types and java types
* Converts between {@link ByteBuffer} and Object representations for primitive BDL types.
*/
public class Cast {
......
......@@ -15,6 +15,9 @@ import brown.tracingplane.baggageprotocol.BaggageReader;
import brown.tracingplane.baggageprotocol.BaggageWriter;
import brown.tracingplane.bdl.SpecialTypes.Counter;
/**
* Implements the special {@link Counter} type based on the P-Counter CRDT; the {@code counter} BDL type uses this.
*/
public class CounterImpl implements Counter {
private static final Random r = new Random(System.currentTimeMillis()); // TODO: properly seed rng uniquely
......@@ -86,15 +89,15 @@ public class CounterImpl implements Counter {
if (other == null || other.componentValues == null) {
return this;
}
boolean is_compaction = BDLUtils.is_compaction.get();
if (is_compaction) {
for (Entry<BagKey, Long> entry : other.componentValues.entrySet()) {
Long existingValue = componentValues.get(entry.getKey());
if (existingValue == null) {
// We can compact the new value into our own component ID
increment(entry.getValue());
increment(entry.getValue());
} else {
// We already knew about this component ID so we can't compact it
componentValues.put(entry.getKey(), Math.max(entry.getValue(), existingValue));
......@@ -135,6 +138,9 @@ public class CounterImpl implements Counter {
return b.toString();
}
/**
* Provides branch, merge, and serialization logic for {@link CounterImpl}
*/
public static class Handler implements BaggageHandler<CounterImpl> {
public static final Handler instance = new Handler();
......
......@@ -4,7 +4,7 @@ import java.util.Map;
import java.util.Set;
/**
* Joiners for built-in types used by compiled baggage buffers classes
* Merge logic for primitive BDL types {@link #first()}, sets, and maps.
*/
public class Joiners {
......
package brown.tracingplane.bdl;
/**
* Defines the interfaces for special BDL types such as {@link Counter}
*/
public class SpecialTypes {
/**
* A P-Counter CRDT, corresponding to the {@code counter} BDL type
*/
public interface Counter extends Bag {
public static Counter newInstance() {
......
......@@ -7,8 +7,8 @@ import brown.tracingplane.bdl.Parser.ElementParser;
import brown.tracingplane.bdl.Serializer.ElementSerializer;
/**
* BaggageBuffers generates classes that implement this interface, Struct. They also generate BaggageHandler
* implementations
* BDL supports structs, which are simply several data types combined into a single binary blob and
* encoded as one atom.
*/
public interface Struct {
......@@ -18,7 +18,7 @@ public interface Struct {
public interface StructReader<S> {
public S readFrom(ByteBuffer buf) throws Exception;
}
@FunctionalInterface
public interface StructSizer<S> {
public int serializedSize(S struct);
......@@ -28,9 +28,10 @@ public interface Struct {
public interface StructWriter<S> {
public void writeTo(ByteBuffer buf, S struct) throws Exception;
}
public interface StructHandler<S> extends StructReader<S>, StructWriter<S>, StructSizer<S>, ElementParser<S>, ElementSerializer<S> {
public interface StructHandler<S>
extends StructReader<S>, StructWriter<S>, StructSizer<S>, ElementParser<S>, ElementSerializer<S> {
@Override
public default S parse(ElementReader reader) {
ByteBuffer buf = null;
......@@ -47,7 +48,7 @@ public interface Struct {
}
return null;
}
@Override
public default void serialize(ElementWriter writer, S instance) {
if (instance != null) {
......@@ -60,7 +61,7 @@ public interface Struct {
}
}
}
}
}
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