Clarify that Tracer.extract can return null

opentracing-api/pom.xml

@@ -31,6 +31,14 @@
         <main.basedir>${project.basedir}/..</main.basedir>
         <main.java.version>1.6</main.java.version>
         <main.signature.artifact>java16</main.signature.artifact>
+        <findbugs.jsr305.version>3.0.2</findbugs.jsr305.version>
     </properties>
 
+    <dependencies>
+        <dependency>
+            <groupId>com.google.code.findbugs</groupId>
+            <artifactId>jsr305</artifactId>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
 </project>

opentracing-api/src/main/java/io/opentracing/Tracer.java

@@ -15,6 +15,8 @@
 
 import io.opentracing.propagation.Format;
 
+import javax.annotation.Nullable;
+
 /**
  * Tracer is a simple, thin interface for Span creation and propagation across arbitrary transports.
  */
@@ -80,18 +82,21 @@ public interface Tracer extends ActiveSpanSource {
      * </code></pre>
      *
      * If the span serialized state is invalid (corrupt, wrong version, etc) inside the carrier this will result in an
-     * IllegalArgumentException.
+     * IllegalArgumentException. If the span serialized state is missing the method returns null.
+     *
      *
      * @param <C> the carrier type, which also parametrizes the Format.
      * @param format the Format of the carrier
      * @param carrier the carrier for the SpanContext state. All Tracer.extract() implementations must support
      *                io.opentracing.propagation.TextMap and java.nio.ByteBuffer.
      *
-     * @return the SpanContext instance holding context to create a Span.
+     * @return the SpanContext instance holding context to create a Span if carrier represents a SpanContext, null
+     * otherwise
      *
      * @see io.opentracing.propagation.Format
      * @see io.opentracing.propagation.Format.Builtin
      */
+    @Nullable
     <C> SpanContext extract(Format<C> format, C carrier);
 
 

pom.xml

@@ -44,6 +44,7 @@
 
         <main.basedir>${project.basedir}</main.basedir>
 
+        <findbugs-jsr305.version>3.0.2</findbugs-jsr305.version>
         <junit.version>4.12</junit.version>
         <assertj.version>3.8.0</assertj.version>
         <mockito.version>1.10.19</mockito.version>
@@ -147,6 +148,12 @@
                 <version>${project.version}</version>
             </dependency>
 
+            <dependency>
+                <groupId>com.google.code.findbugs</groupId>
+                <artifactId>jsr305</artifactId>
+                <version>${findbugs-jsr305.version}</version>
+            </dependency>
+
             <dependency>
                 <groupId>junit</groupId>
                 <artifactId>junit</artifactId>