Add some documentation and methods

atomlayer/baggagecontext-impl/README.md

+# TracingPlane:AtomLayer/BaggageContext
+
+This package implements a `BaggageContext` based solely on atoms and lexicographic merge.  It provides no interpretation of the atoms, but does provide an implementation of the main `BaggageProvider` methods -- specifically serialization, merge/join, and trim.
+
+This atom-only `BaggageContext` should be used in systems that wish to propagate baggage, but have no need to inspect or modify its contents (e.g., if baggage is just passing through).  For this use case, none of the more heavyweight libraries (e.g., the baggage protocol and BDL client library) are necessary.
\ No newline at end of file

atomlayer/baggagecontext-impl/src/main/java/brown/tracingplane/impl/AtomContext.java

 package brown.tracingplane.impl;
 
 import java.nio.ByteBuffer;
+import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 import java.util.concurrent.atomic.AtomicIntegerFieldUpdater;
 import brown.tracingplane.BaggageContext;
@@ -62,11 +64,11 @@ public class AtomContext implements BaggageContext {
         atoms = null;
     }
 
-    AtomContext branch() {
+    public AtomContext branch() {
         return new AtomContext(atoms);
     }
 
-    AtomContext merge(AtomContext other) {
+    public AtomContext merge(AtomContext other) {
         if (other == null || other.atoms == null || other.atoms.object == null) {
             return this;
         }
@@ -93,7 +95,19 @@ public class AtomContext implements BaggageContext {
         return this;
     }
 
-    int serializedSize() {
+    /**
+     * If others hold references to our atoms, duplicates the atoms.
+     */
+    void toExclusive() {
+        if (atoms != null && atoms.object != null && !atoms.exclusive()) {
+            RefCount<List<ByteBuffer>> newAtoms = new RefCount<>(new ArrayList<>(atoms.object));
+            atoms.deref();
+            newAtoms.ref();
+            atoms = newAtoms;
+        }
+    }
+
+    public int serializedSize() {
         int size = 0;
         for (ByteBuffer atom : atoms.object) {
             size += atom.remaining() + ProtobufVarint.sizeOf(atom.remaining());
@@ -101,6 +115,32 @@ public class AtomContext implements BaggageContext {
         return size;
     }
 
+    /**
+     * <p>
+     * Returns the {@link List} that backs this {@link AtomContext} object. This method is only for observing the atoms,
+     * not for updating them.
+     * </p>
+     * 
+     * @return the atoms of this {@link AtomContext}
+     */
+    public List<ByteBuffer> getUnmodifiableAtoms() {
+        return atoms == null ? null : atoms.object == null ? null : Collections.unmodifiableList(atoms.object);
+    }
+
+    /**
+     * <p>
+     * Returns the {@link List} that backs this {@link AtomContext} object, so modifications to the list will be
+     * reflected by this context and vice versa. {@link AtomContext} uses reference counting as an optimization, so a
+     * call to this method might result in duplicating atoms if others currently hold a reference to them.
+     * </p>
+     * 
+     * @return the atoms of this {@link AtomContext}
+     */
+    public List<ByteBuffer> getModifiableAtoms() {
+        toExclusive();
+        return atoms();
+    }
+
     List<ByteBuffer> atoms() {
         return atoms == null ? null : atoms.object;
     }

atomlayer/baggagecontext-impl/src/test/java/brown/tracingplane/impl/TestAtomContext.java

@@ -146,5 +146,31 @@ public class TestAtomContext {
         assertEquals(1, ctx2.atoms.count);
         assertEquals(ctx1.atoms.object, ctx2.atoms.object);
     }
+    
+    @Test
+    public void testExclusive() {
+        AtomContext ctx1 = new AtomContext(genAtoms(3, 10));
+        
+        AtomContext ctx2 = provider.branch(ctx1);
+
+        RefCount<List<ByteBuffer>> atoms1 = ctx1.atoms;
+        RefCount<List<ByteBuffer>> atoms2 = ctx2.atoms;
+        List<ByteBuffer> atomsCtx1 = ctx1.atoms.object;
+        List<ByteBuffer> atomsCtx2 = ctx2.atoms.object;
+
+        assertSame(atoms1, atoms2);
+        assertSame(atomsCtx1, atomsCtx2);
+        assertEquals(2, ctx1.atoms.count);
+        assertEquals(2, ctx2.atoms.count);
+        
+        ctx1.toExclusive();
+        
+        assertNotSame(atoms1, ctx1.atoms);
+        assertNotSame(atomsCtx1, ctx1.atoms.object);
+        assertEquals(atomsCtx1, ctx1.atoms.object);
+        assertEquals(1, ctx1.atoms.count);
+        assertEquals(1, ctx2.atoms.count);
+        
+    }
 
 }

atomlayer/core/README.md

+# TracingPlane:AtomLayer/Core
+
+This package provides the core representation and implementations for the Tracing Plane's *atom* based `BaggageContext` implementation.  This includes utility classes and methods based around lexicographic comparison and atom merging.
\ No newline at end of file

baggagecontext/transitlayer/README.md

-# Tracing Plane - Transit Layer
+# TracingPlane:BaggageContext/TransitLayer
+
+This package provides the following:
+
+* The core interfaces for the Tracing Plane's `TransitLayer` -- to enhance the existing `BaggageContext` and `Baggage` interfaces that exist in `BaggageContext/API` and `BaggageContext/StaticAPI`.
+* The out-of-the-box `TransitLayer` implementation, which is a NoOp and does nothing -- method calls are essentially ignored
+* A `TransitLayer` implementation based on thread-local variables.  This is the recommended context propagation library to use with the tracing plane.  It is the default `TransitLayer` implementation in the Tracing Plane distribution jars.
+
+## Transit Layer
 
 The Tracing Plane provides an out-of-the-box context propagation library called the "Transit Layer".  The Transit Layer uses thread-local storage to store `BaggageContext` instances for threads, and provides a static API in `brown.tracingplane.ActiveBaggage` that invokes transit layer methods.  `ActiveBaggage` provides methods as follows: