Fix zpages readme and add helper function that starts a server. (#570)

3 files changed, 91 insertions, 21 deletions

diff --git a/contrib/zpages/README.md b/contrib/zpages/README.md
index 7660acd0..00f52341 100644
--- a/contrib/zpages/README.md
+++ b/contrib/zpages/README.md
@@ -10,16 +10,25 @@ allows library configuration control.
 
 For Maven add to your `pom.xml`:
 ```xml
-<dependency>
-  <groupId>io.opencensus</groupId>
-  <artifactId>opencensus-contrib-zpages</artifactId>
-  <version>0.6.0</version>
-</dependency>
+<dependencies>
+  <dependency>
+    <groupId>io.opencensus</groupId>
+    <artifactId>opencensus-contrib-zpages</artifactId>
+    <version>0.6.0</version>
+  </dependency>
+  <dependency>
+    <groupId>io.opencensus</groupId>
+    <artifactId>opencensus-impl</artifactId>
+    <version>0.6.0</version>
+    <scope>runtime</scope>
+  </dependency>
+</dependencies>
 ```
 
 For Gradle add to your dependencies:
 ```gradle
 compile 'io.opencensus:opencensus-contrib-zpages:0.6.0'
+runtime 'io.opencensus:opencensus-impl:0.6.0'
 ```
 
 ### Register the Z-Pages
@@ -27,11 +36,8 @@ compile 'io.opencensus:opencensus-contrib-zpages:0.6.0'
 ```java
 public class MyMainClass {
   public static void main(String[] args) throws Exception {
-    // ...
-    HttpServer server = HttpServer.create(new InetSocketAddress(8000), 10);
-    ZPageHandlers.registerAllToHttpServer(server);
-    server.start();
-    // ...
+    ZPageHandlers.startHttpServerAndRegisterAll(8080);
+    // ... do work
   }
 }
 ```
diff --git a/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/ZPageHandlers.java b/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/ZPageHandlers.java
index ad7544e2..1d8e656e 100644
--- a/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/ZPageHandlers.java
+++ b/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/ZPageHandlers.java
@@ -16,14 +16,32 @@
 
 package io.opencensus.contrib.zpages;
 
+import static com.google.common.base.Preconditions.checkState;
+
 import com.sun.net.httpserver.HttpServer;
 import io.opencensus.trace.Tracing;
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.util.logging.Logger;
+import javax.annotation.concurrent.GuardedBy;
+import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * A collection of HTML pages to display stats and trace data and allow library configuration
  * control.
  *
- * <p>Example usage with {@link HttpServer}:
+ * <p>Example usage with private {@link HttpServer}:
+ *
+ * <pre>{@code
+ * public class Main {
+ *   public static void main(String[] args) throws Exception {
+ *     ZPageHandlers.startHttpServerAndRegisterAll(8000);
+ *     ... // do work
+ *   }
+ * }
+ * }</pre>
+ *
+ * <p>Example usage with shared {@link HttpServer}:
  *
  * <pre>{@code
  * public class Main {
@@ -36,12 +54,22 @@ import io.opencensus.trace.Tracing;
  * }
  * }</pre>
  */
+@ThreadSafe
 public final class ZPageHandlers {
+  // The HttpServer listening socket backlog (maximum number of queued incoming connections).
+  private static final int BACKLOG = 5;
+  // How many seconds to wait for the HTTP server to stop.
+  private static final int STOP_DELAY = 1;
+  private static final Logger logger = Logger.getLogger(ZPageHandler.class.getName());
   private static final ZPageHandler tracezZPageHandler =
       TracezZPageHandler.create(
           Tracing.getExportComponent().getRunningSpanStore(),
           Tracing.getExportComponent().getSampledSpanStore());
 
+  private static final Object monitor = new Object();
+  @GuardedBy("monitor")
+  private static HttpServer server;
+
   /**
    * Returns a {@code ZPageHandler} for tracing debug. The page displays information about all
    * active spans and all sampled spans based on latency and errors.
@@ -51,6 +79,8 @@ public final class ZPageHandlers {
    *
    * <p>If no sampled spans based on latency and error codes are available for a given name, make
    * sure that the span name is registered to the {@code SampledSpanStore}.
+   *
+   * @return a {@code ZPageHandler} for tracing debug.
    */
   public static ZPageHandler getTracezZPageHandler() {
     return tracezZPageHandler;
@@ -65,5 +95,48 @@ public final class ZPageHandlers {
     server.createContext(tracezZPageHandler.getUrlPath(), new ZPageHttpHandler(tracezZPageHandler));
   }
 
+  /**
+   * Starts an {@code HttpServer} and registers all pages to it. When the JVM shuts down the server
+   * is stopped.
+   *
+   * <p>Users must call this function only once per process.
+   *
+   * @param port the port used to bind the {@code HttpServer}.
+   * @throws IllegalStateException if the server is already started.
+   * @throws IOException if the server cannot bind to the requested address.
+   */
+  public static void startHttpServerAndRegisterAll(int port) throws IOException {
+    synchronized (monitor) {
+      checkState(server == null, "The HttpServer is already started.");
+      server = HttpServer.create(new InetSocketAddress(port), BACKLOG);
+      ZPageHandlers.registerAllToHttpServer(server);
+      server.start();
+      logger.fine("HttpServer started on address " + server.getAddress().toString());
+    }
+
+    // This does not need to be mutex protected because it is guaranteed that only one thread will
+    // get ever here.
+    Runtime.getRuntime()
+        .addShutdownHook(
+            new Thread() {
+              @Override
+              public void run() {
+                // Use stderr here since the logger may have been reset by its JVM shutdown hook.
+                logger.fine("*** Shutting down gRPC server (JVM shutting down)");
+                ZPageHandlers.stop();
+                logger.fine("*** server shut down");
+              }
+            });
+  }
+
+  private static void stop() {
+    synchronized (monitor) {
+      // This should never happen because we register the shutdown hook only if we start the server.
+      checkState(server != null, "The HttpServer is already stopped.");
+      server.stop(STOP_DELAY);
+      server = null;
+    }
+  }
+
   private ZPageHandlers() {}
 }
diff --git a/examples/src/main/java/io/opencensus/examples/zpages/ZPagesTester.java b/examples/src/main/java/io/opencensus/examples/zpages/ZPagesTester.java
index a6b9b660..24dd7841 100644
--- a/examples/src/main/java/io/opencensus/examples/zpages/ZPagesTester.java
+++ b/examples/src/main/java/io/opencensus/examples/zpages/ZPagesTester.java
@@ -16,23 +16,14 @@
 
 package io.opencensus.examples.zpages;
 
-import com.sun.net.httpserver.HttpServer;
 import io.opencensus.contrib.zpages.ZPageHandlers;
-import java.net.InetSocketAddress;
-import java.util.logging.Logger;
 
 /**
  * Testing only class for the UI.
  */
 public class ZPagesTester {
-  private static final Logger logger = Logger.getLogger(ZPagesTester.class.getName());
-
   /** Main method. */
   public static void main(String[] args) throws Exception {
-    HttpServer server = HttpServer.create(new InetSocketAddress(8000), 10);
-    ZPageHandlers.registerAllToHttpServer(server);
-    server.start();
-    logger.info(server.getAddress().toString());
+    ZPageHandlers.startHttpServerAndRegisterAll(8080);
   }
-
 }