Pull in existing code from talsma-ict.

.gitignore

@@ -1,4 +1,7 @@
+# Build / maven artifacts
 *.class
+target/
+pom.xml.versionsBackup
 
 # Mobile Tools for Java (J2ME)
 .mtj.tmp/
@@ -10,3 +13,8 @@
 
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
 hs_err_pid*
+
+# IntelliJ project files
+.idea/
+*.iml
+

.mvn/wrapper/.gitignore

@@ -0,0 +1 @@
+!maven-wrapper.jar

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1 @@
+distributionUrl=https://repo1.maven.org/maven2/org/apache/maven/apache-maven/3.3.9/apache-maven-3.3.9-bin.zip

.settings.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright 2017 The OpenTracing Authors
+
+    Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+    in compliance with the License. You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software distributed under the License
+    is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+    or implied. See the License for the specific language governing permissions and limitations under
+    the License.
+
+-->
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
+      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
+                          http://maven.apache.org/xsd/settings-1.0.0.xsd">
+  <servers>
+    <server>
+      <id>sonatype</id>
+      <username>${env.SONATYPE_USER}</username>
+      <password>${env.SONATYPE_PASSWORD}</password>
+    </server>
+    <server>
+      <id>bintray</id>
+      <username>${env.BINTRAY_USER}</username>
+      <password>${env.BINTRAY_KEY}</password>
+    </server>
+    <server>
+      <id>jfrog-snapshots</id>
+      <username>${env.BINTRAY_USER}</username>
+      <password>${env.BINTRAY_KEY}</password>
+    </server>
+    <server>
+      <id>github.com</id>
+      <username>${env.GH_USER}</username>
+      <password>${env.GH_TOKEN}</password>
+    </server>
+  </servers>
+</settings>
+

.travis.yml

@@ -0,0 +1,53 @@
+# Run `travis lint` when changing this file to avoid breaking the build.
+# Default JDK is really old: 1.8.0_31; Trusty's is less old: 1.8.0_51
+# https://docs.travis-ci.com/user/ci-environment/#Virtualization-environments
+sudo: false
+dist: trusty
+
+cache:
+  directories:
+  - $HOME/.m2
+
+language: java
+
+jdk:
+  - oraclejdk8
+
+addons:
+  apt:
+    packages:
+      - oracle-java8-installer
+
+before_install:
+  # allocate commits to CI, not the owner of the deploy key
+  - git config user.name "opentracingci"
+  - git config user.email "opentracingci+opentracing@googlegroups.com"
+  # setup https authentication credentials, used by ./mvnw release:prepare
+  - git config credential.helper "store --file=.git/credentials"
+  - echo "https://$GH_TOKEN:@github.com" > .git/credentials
+
+install:
+  # Override default travis to use the maven wrapper
+  - ./mvnw install -DskipTests=true -Dmaven.javadoc.skip=true -B -V
+
+script:
+  - ./travis/publish.sh
+
+# Don't build release tags. This avoids publish conflicts because the version commit exists both on master and the release tag.
+# See https://github.com/travis-ci/travis-ci/issues/1532
+branches:
+  except:
+    - /^[0-9]/
+
+env:
+  global:
+  # Ex. travis encrypt -r opentracing-contrib/java-spanmanager BINTRAY_USER=your_github_account
+  - secure: "RS267NqO3TR8MuAjP7XK3hItutoXDicHXF5tsKMiPjCTdxlVMWFqFI9zFhXQjKoCAUxsvaRnGIoF3xAZgH/nlC1q7QQzq0XKPpaoSmFv4+EwyjxF1O6DuhaUDDbFbmcFQzofvSUxgl0L45o5z9iJ1Y2Z+4kesWA/6jD499fhC+ekBIskmFrcI7Y+z92VDt5Y9ZPf49/P4iVQHiKk02omHa7OIR2wL3HHXuPy8lmKTky8p/IJa0tGQq7DfoD78ud3OaiXpEr4IjBLcJMGMOCO6DGS2/G8UfPrMEWv8iWGua2MMgfuHvIgtGVxTVJ+OtDuWndbzP558tjz33h2yxE/ASpVGtznRkEQlK6F1Yno3INhq9j3OEU0DG+vLluT1zWdkNriVkza89Wp9CBzi1IszV+9+cjkUWDWxomDu4K+O9y9RpBsXgxrTTBqymopKkg/8KHXWNjTEZRGqlgYvZD37nvpxIFzf35lXcK6HcWsFYoYlIB8h/Iieboymy8uyEcqK1TSsQFR88ZaacT4fK+goa+rFdcsTUO7sUzZJOmLQGgvRCKARu80pN/k2+d+XPRvCnl+pcSB0s8ZoInTSEi+gB3uNw1uyl8bzhy3mIlw6eMaUiT7krZzQCv94tl6tyrVyOXavsnNsRzBbkxC3w9CtK9DVqQSYFYQ8bZKX/KLl4c="
+  # Ex. travis encrypt BINTRAY_KEY=xxx-https://bintray.com/profile/edit-xxx --add
+  - secure: "ZOm+CpZs0hUBc5eREK9i87HL7bmHSDENdpH9hY4N/MPPaYLb04MEkaJ8pW1qGeLbmumATXcE3mfWdJ95LKROn+qUBdUofXbq430EScOkMnIzntkyfKVeq5wr/qigArkhgY6S70u6tUrS2NDLnfwR4gBYCHUKY7InpGUR/cggwdnbYVVKuu31j+xylMZNDAA5EXpVzAfeKSEDEiwS0ej5lPfo0KQCN3f3fDjiJASLsiBl5IdxDHwONxvZWqcWOKpRYIfXYSFOFdgdIGWfQarAPJlUsefVV9jXUtCfB2PXRn6fdScjE0LOWcfQSYdVO+l8sslpufp+DPH0V7edWwZbFgshUIETtu0eoAOLmGbd571WzVmAnYpalY8m4MJFFLVjLe32npvDtxvibo1vFp7l9NPvkQCV6BwS8iLsWJDpraeJmb3ZfOr1hUObJs/JayDVEe6rB3nSkjs4Y5dyBc3hPurPBnYWl4HSDsRmKZ1ieGaIh8FuEOl0MToDO/ZCTQJB3A6CvnlYbI0t4WFU7Q68zRSJih4bUxaQD3aERzGgpMatGAoxMi1hfv0krMAJQTHSZqKpTrftJ/CTjXn2cJavO+Eai3lODzZ42tnz/blzOApfSKU4biu3QwohTMIPqaLOA1KfF6hJkSKfsTzjbSnqqdEc09liYSCoRbLleEXBr9w="
+  # Ex. travis encrypt GH_TOKEN=XXX-https://github.com/settings/tokens-XXX --add
+  - secure: "ktakwcLywOMAMeJpj2+haZHgdkbs5Me1JA1fDoPIcNJMttHSa3A8JEYxTFmwX5/ybNuXJpL98HblGQfYPIH1oL4oyO7oif1t/LzjUibFUDzgMVMgUy8oirGUVRwOH9Uj3/eILBLbMQO+yodbDvHHhiVT+xv1K1q3Qy+vwSabSr8YjYADvlL4Oz60C2BAPLpuG/VjZPQ96nQopVI/a+3IvgEega0kRHw0LFFT87Ht/MOpo++uU9FPJ8QU3Tf7EYuuuR+xJIJ4W04Cewp6TdreiPWynf1aLwVnsy4cXIt+e6K0KJg9PGtlGjwJGllB7TMYtFmQ+qCyVYs+OqmDpUqQ4JCUKpZ6KyRIdh+I+3CNYttMCFYBTvBvMBFEyzSO2OOJWysF3vahCmCVHkZdJacHQ5gaGrVpzZ/9nDdkmO2trH6xlmp+MPWehXsuMLgIVJLyJSEZb/hQCojzjpDY7vTAyleC/5DwyF7iInf7CO6ZNHnWODyMfgLOkB8yuXhRAQjMejXObRYcT5u6wiJaQb/m3IqXOdrZuOo/dbFzMZSnIXmC6TaK6NnWu3Noibh+Hyg9odsy7tAPCAsJUOBy+JQdeIJNeV76cxigN37EQSlFD9k2s82LIFrNqC0za3kuQfE+iWPeTrTBVJfIxq7KZrN9f0jfj/gvpPA0borwRKt+5xQ="
+  # Ex. travis encrypt SONATYPE_USER=your_sonatype_account
+  - secure: "VyTo3xcnUMpXofZlgY5D8qBrypOclWPcyG1u8skwozrJkeJMg31DOkU6s3dLxPq1NMBKaiVnaKMzOrTvGMu11+7pWc+afamZ1UW/I4ZxToZPl2/Dq8iTHqt1PiIwNd6Y1cKrOC2bnBKjXONN0rpoHmgFERvLYqfXTjs0qZrFQRth3TfgxyQux3EXBmxZioQYEgZqwOISPRWyK0tFJ+9VNpUFbzw7JnpP4XwFRe2HaVyCRpbWyQ1pIhcr98dZEa9KsdGJtnOVdZm+Ej8QyNvTOwJgqFOblstaUcYTXVZErZWDQ9OMd8plExhPzpaqymz/0xB/tXaHnHTEf0yQCpjHi18UzrQveXJ20jk+n0unuqGeq6L/XpWLG2kIxTeBPt4MCDd+FCyli55jiQpzlRqAwOcWndiy47qoJzmqseWvp7DKoNvXwwSRgPXJ5e2u/ZQdbRmIwZmzxemhTBoa23ekoP2LvKPJH2mfDc5e1S10boHVjmuahKeKAbSw28CJ1m3mBGg1wyTLVtneauOaAK4zCzXfZ6JkdHKQSoAD+AiYNrYnfZk76kcUNVgi+wqadHgNXinni1WGM8MGu9nfsmYSY2PO4/2zqmASYhc417LRzkx0iu4wNMiy8zowbbhnFNxt8LrLbJV90eu6Z4XEcPAThfL5xzH8bSvyXuiYuT5sXV0="
+  # Ex. travis encrypt SONATYPE_PASSWORD=your_sonatype_password
+  - secure: "kQYGrYzMw8lN0Vp4GbEOHxYIR+w1YtJ6LaYz00x6Lb/3pyaINFDGnLmKuANNXvHr4UyrT+q4bg8EWII4ctdbbvsSOBvxq0VkADBBGpYvlpa92598TsrfeJ9ZDz5kthajyQXK1kZU0kkBRHVbJ4I1CBqlJOHRYv9h2m99D+Fe3sHnPePre2e2BNJbFJj6EomKBTNarZQOdR7EFJ3DBmsalAmcZm52npSaeI/8D06QGNlEqvBufOwF6EYNN+IVJZsmhjoSyrYx/qqPIecQOVZfaDCk5Y6QNU4JWQaSDtLfVZjJ3QTIj86fjRqd30TBUtl9Dq+iBwuRCImBV6I9PpfLXoQMIaguE1UWt4lfDwBhsylnm9g35BQ/V0iOFnWXyhablK6irKAgYXlQMuvxaqrNnLf6tK5DIoPO0nJS9n1Sj8uH6sW/MfDJ4I3V7wfBDBN40Bi3N8LAcmf9vcDfKq6yqi4rXQ45eM2BffV/fWt4miN7vBjnBEyWPAzAfNr4b1m5U5eHtyk6sLrzWUK9eMIlN3CrIAKy7LLOYhgi7vnYuqyU9wCAzxIORFKE6NSn3bokTCr3WchCNmM2fvHpIh9b6BzPBgiO9MGllxq4PpyXpgpG9zygpA1t5ZXnUD1/Gs5UWy6peHqV85RtKBv/M/SwDFlewZG/Aj0LNThV6a9ZEyA="

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to opentracing-contrib / java-spanmanager
+
+If you would like to contribute code you can do so through GitHub by forking the repository
+and sending a pull request (on a branch other than `master` or `gh-pages`).
+
+
+## License
+
+By contributing your code, you agree to license your contribution under the terms of the APLv2:
+https://github.com/opentracing-contrib/java-spanmanager/blob/master/LICENSE
+
+All files are released with the Apache 2.0 license.
+
+If you are adding a new file it should have a header like below.  
+This can be automatically added by running `./mvnw license:format`.
+
+```
+/**
+ * Copyright 2017 The OpenTracing Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+ ```

README.md

@@ -1 +1,229 @@
-# java-spanmanager
+[![Build Status][ci-img]][ci] [![Released Version][maven-img]][maven]
+
+# Span manager for Java
+
+:heavy_exclamation_mark: **Warning:** This library is still a work in progress!
+
+This library provides a way to manage spans and propagate them to other threads.
+
+## SpanManager
+
+Defines _current span_ management.
+
+A SpanManager separates the creation of a `Span` from its use later on.
+This relieves application developers from passing the current span around through their code.
+Only tracing-related code will need access to a SpanManager reference, provided as an ordinary dependency.
+
+SpanManager provides the following methods:
+
+ 1. `manage(span)` makes the given span the _current_ managed span.  
+    Returns a `ManagedSpan` containing a `release()` method
+    to later 'unmanage' the span with.
+ 2. `currentSpan()` returns the _current_ managed span,
+    or the `NoopSpan` if no span is managed.
+ 3. `clear()` provides unconditional cleanup of _all managed spans_ for the current process.
+
+## DefaultSpanManager
+
+A _default_ SpanManager maintaining a `Stack`-like `ThreadLocal` storage of _linked managed spans_.
+
+Releasing a _linked managed span_ uses the following algorithm:
+ 1. If the released span is not the _current_ span, the current span is left alone.
+ 2. Otherwise, the first parent that is <em>not yet released</em> is set as the new current span.
+ 3. If no current parents remain, the current span is cleared.
+ 4. Consecutive `release()` calls for already-released spans will be ignored.
+
+## Concurrency
+
+### SpanPropagatingExecutorService
+
+This `ExecutorService` _propagates the current span_ 
+from the caller into each call that is executed.  
+The current span of the caller is obtained from the configured `SpanManager`.
+
+_Please Note:_ The current span is merely _propagated_ (as-is).  
+It is explicitly **not** finished when the calls end,
+nor will new spans be automatically related to the propagated span.
+
+### SpanPropagatingExecutors
+
+Contains factory-methods similar to standard java `Executors`:  
+ - `SpanPropagatingExecutors.newFixedThreadPool(int, SpanManager)`
+ - `SpanPropagatingExecutors.newSingleThreadExecutor(SpanManager)`
+ - `SpanPropagatingExecutors.newCachedThreadPool(SpanManager)`
+ - Variants of the above with additional `ThreadFactory` argument.
+
+## ManagedSpanTracer
+
+This convenience `Tracer` automates managing the _current span_:
+ 1. It wraps another `Tracer`.
+ 2. `Spans` created with this tracer are:
+    - automatically _managed_ when started, and
+    - automatically _released_ when finished.
+
+## Examples
+
+### Manually propagating any Span into a background thread
+
+To propagate a `Span` into a new `Thread`, the _currentSpan_ from the caller must be
+remembered by the `Runnable`:
+
+```java
+    class ExampleRunnable implements Runnable {
+        private final SpanManager spanManager;
+        private final Span currentSpanFromCallingThread;
+
+        ExampleRunnable(SpanManager spanManager) {
+            this(spanManager, NoopSpan.INSTANCE);
+        }
+
+        private ExampleRunnable(SpanManager spanManager, Span currentSpanFromCallingThread) {
+            this.spanManager = spanManager;
+            this.currentSpanFromCallingThread = currentSpanFromCallingThread;
+        }
+
+        ExampleRunnable withCurrentSpan() {
+            return new ExampleRunnable(spanManager, spanManager.currentSpan());
+        }
+
+        @Override
+        public void run() {
+            try (ManagedSpan parent = spanManager.manage(currentSpanFromCallingThread)) {
+
+                // Any background code that requires tracing
+                // and may use spanManager.currentSpan().
+
+            } // parent.release() restores spanManager.currentSpan() to NoopSpan in new thread.
+        }
+    }
+```
+
+Then the application can propagate this _currentSpan_ into background threads:
+
+```java
+    class App {
+        public static void main(String... args) throws InterruptedException {
+            Config config = ...;
+            Tracer tracer = config.getTracer();
+            SpanManager spanManager = config.getSpanManager();
+            ExampleRunnable runnable = new ExampleRunnable(spanManager);
+
+            try (Span appSpan = tracer.buildSpan("main").start();           // start appSpan
+                    ManagedSpan managed = spanManager.manage(appSpan)) {    // update currentSpan
+
+                Thread example = new Thread(runnable.withCurrentSpan());
+                example.start();
+                example.join();
+
+            } // managed.release() + appSpan.finish()
+
+            System.exit(0);
+        }
+    }
+
+```
+
+### Threadpool that propagates SpanManager.currentSpan() into threads
+
+```java
+    class TracedCall implements Callable<String> {
+        SpanManager spanManager = ... // inject or DefaultSpanManager.getInstance();
+
+        @Override
+        public String call() {
+            Span currentSpan = spanManager.currentSpan(); // Propagated span from caller
+            // ...
+        }
+    }
+
+    class Caller {
+        SpanManager spanManager = ... // inject or DefaultSpanManager.getInstance(); 
+        ExecutorService threadpool = new SpanPropagatingExecutorService(anyThreadpool(), spanManager);
+
+        void run() {
+            // ...code that sets the current Span somewhere:
+            try (ManagedSpan current = spanManager.manage(someSpan)) {
+
+                // scheduling the traced call:
+                Future<String> result = threadpool.submit(new TracedCall());
+
+            }
+        }
+    }
+
+```
+
+### Propagating threadpool with 'ManagedSpan' Tracer
+
+When starting a new span and making it the _currentSpan_, the manual example above used:
+```java
+    try (Span span = tracer.buildSpan("main").start();           // start span
+            ManagedSpan managed = spanManager.manage(span)) {    // set currentSpan() to span
+        // ...traced block of code...
+    }
+```
+
+The `ManagedSpanTracer` automatically makes every started span the current span.
+It also releases it again when the span is finished:
+
+```java
+    class Caller {
+        SpanManager spanManager = ... // inject or DefaultSpanManager.getInstance();
+        Tracer tracer = new ManagedSpanTracer(anyTracer(), spanManager);
+        ExecutorService threadpool = new SpanPropagatingExecutorService(anyThreadpool(), spanManager);
+
+        void run() {
+            try (Span parent = tracer.buildSpan("parentOperation").start()) { // parent == currentSpan
+
+                // Scheduling the traced call:
+                Future<String> result = threadpool.submit(new TracedCall());
+
+            } // parent.finish() + ((ManagedSpan) parent).release()
+        }
+    }
+```
+
+### Example with asynchronous request / response filters
+
+When asynchronous processing is handled by separate request/response filters,
+a `try-with-resources` code block is insufficient.
+
+Existing filters that start / finish new spans asynchronously can simply 
+be supplied with the `ManagedSpanTracer` around the existing tracer.
+This sets the _currentSpan_ from the request filter
+and calls `release()` automatically from the response filter
+when the existing filter finishes the span.  
+An example would be using the [opentracing jaxrs filters](https://github.com/opentracing-contrib/java-jaxrs) 
+in combination with the ManagedSpanTracer:
+```java
+    // Add example when opentracing jaxrs library stabilizes
+```
+
+Alternatively, the following hypothetic filter pair could be used on an asynchronous server:  
+Handling the request:
+```java
+    final SpanManager spanManager = ... // inject or DefaultSpanManager.getInstance();
+    void onRequest(RequestContext reqCtx) {
+        Span span = ... // either obtain Span from previous filter or start from the request
+        ManagedSpan managedSpan = spanManager.manage(span); // span is now currentSpan.
+        reqCtx.put(SOMEKEY, managedSpan);
+    }
+```
+
+For the response:
+```java
+    final SpanManager spanManager = ...
+    void onResponse(RequestContext reqCtx, ResponseContext resCtx) {
+        spanManager.clear(); // Clear stack containing the currentSpan if this is a boundary-filter
+        // or: 
+        // ManagedSpan managedSpan = reqCtx.get(SOMEKEY);
+        // managedSpan.release();
+
+        // If the corresponding request filter starts a span, don't forget to call span.finish() here!
+    }
+```
+
+  [ci-img]: https://img.shields.io/travis/opentracing-contrib/java-spanmanager/master.svg
+  [ci]: https://travis-ci.org/opentracing-contrib/java-spanmanager
+  [maven-img]: https://img.shields.io/maven-central/v/io.opentracing.contrib/java-spanmanager.svg
+  [maven]: http://search.maven.org/#search%7Cga%7C1%7Cjava-spanmanager

RELEASE.md

@@ -0,0 +1,6 @@
+# OpenTracing Release Process
+
+This repo uses semantic versions. Please keep this in mind when choosing version numbers.  
+
+For the up-to-date release process, please refer the 
+[release process from the OpenTracing Java API](https://github.com/opentracing/opentracing-java/blob/master/RELEASE.md).