Put into place the top-level design that fulfils the new Specification

 - Only span creation method is in Tracer.startSpan(..)
 - Add Tracer's inject(..) and join(..) methods

reference: #10

opentracing/src/main/java/opentracing/Span.java

@@ -16,19 +16,10 @@
 /**
  * Span represents an active, un-finished span in the opentracing system.
  *
- * <p>Spans are created by the {@link Tracer} interface and {@link #startChild(String)}.
+ * <p>Spans are created by the {@link Tracer} interface.
  */
 public interface Span {
 
-  /**
-   * Denotes the beginning of a subordinate unit of work.
-   *
-   * @param operationName name of the operation represened by the new span from the perspective of
-   * the current service.
-   * @return a new child Span in "started" state.
-   */
-  Span startChild(String operationName);
-
   /**
    * Sets the end timestamp and records the span.
    *
@@ -38,7 +29,7 @@ public interface Span {
   void finish();
 
   /**
-   * Adds a tag to the span.
+   * Set a key:value tag on the Span.
    *
    * <p>Tag values can be of arbitrary types, however the treatment of complex types is dependent on
    * the underlying tracing system implementation. It is expected that most tracing systems will
@@ -54,10 +45,17 @@ public interface Span {
   Span setTag(String key, boolean value);
 
   /** Same as {@link #setTag(String, String)}, but for numeric values. */
-  // numbers kindof suck.. we've no idea if this is a float, how many bits, etc.
   Span setTag(String key, Number value);
 
-  Span setTraceAttribute(String key, String value);
+  /**
+   * Set a Baggage item, represented as a simple string:string pair.
+   *
+   * Note that newly-set Baggage items are only guaranteed to propagate to future children of the given Span.
+   */
+  Span setBaggageItem(String key, String value);
+
+  /** Get a Baggage item by key. */
+  String getBaggageItem(String key);
 
   /**   *
    * Add a new log event to the Span, accepting an event name string and an optional structured payload argument.

opentracing/src/main/java/opentracing/Tracer.java

@@ -13,25 +13,47 @@
  */
 package opentracing;
 
+
 /**
- * Tracer is a simple, thin interface for Span creation.
+ * Tracer is a simple, thin interface for Span creation, and Span propagation into different transport formats.
  */
 public interface Tracer {
 
   /**
-   * Create, start, and return a new Span with the given `operationName`, all without specifying a
-   * parent Span that can be used to incorporate the newly-returned Span into an existing trace.
+   * Create, start, and return a new Span with the given `operationName`.
+   * An optional parent Span can be specified used to incorporate the newly-returned Span into an existing trace.
    *
    * <p>Example:
    * <pre>{@code
    * Tracer tracer = ...
-   * Span feed = tracer.startTrace("GetFeed");
-   * Span http = tracer.startTrace("HandleHTTPRequest")
+   * Span feed = tracer.startTrace("GetFeed", null);
+   * Span http = tracer.startTrace("HandleHTTPRequest", feed)
    *                   .setTag("user_agent", req.UserAgent)
    *                   .setTag("lucky_number", 42);
    * }</pre>
    */
-  Span startTrace(String operationName);
+  Span startSpan(String operationName, /* @Nullable */ Span parent);
 
-  SpanPropagator getSpanPropagator();
+  /**
+   * Same as {@link #startSpan(String, Span)},
+   * but allows to specify a past timestamp in microseconds when the Span was created.
+   */
+  Span startSpan(String operationName, long microseconds, /* @Nullable */ Span parent);
+
+  /** Takes two arguments:
+   *    a Span instance, and
+   *    a “carrier” object in which to inject that Span for cross-process propagation.
+   *
+   */
+  <T> void inject(Span span, T carrier);
+
+  /**  Takes two arguments:
+   *    the operation name for the Span it’s about to create, and
+   *    a “carrier” object from which to extract identifying information needed by the new Span instance.
+   *
+   * Unless there’s an error, it returns a freshly-started Span which can be used in the host process like any other.
+   * (Note that some OpenTracing implementations consider the Spans on either side of an RPC to have the same identity,
+   * and others consider the caller to be the parent and the receiver to be the child)
+   */
+  <T> Span join(String operationName, T carrier);
 }