Java: Add 'EnvironmentConfiguredTracer'

Adding 'ppaml_tracer_init_from_env' (commit b9dfb8d0) makes the Java
code substantially more complicated, as it introduces a second mechanism
to construct 'Tracer's.  While I could simply provide two constructors
in the 'Tracer' class, this would make for an ugly and dangerous
implementation; after all, the life cycle of a tracer configured
explicitly is noticeably different from the life cycle of a tracer
configured by sourcing environment variables.  Instead, I’ve changed
'Tracer' to be an interface implemented by 'ExplicitlyConfiguredTracer'
and 'EnvironmentConfiguredTracer'.

This is an API-breaking change.

12 files changed, 384 insertions, 143 deletions

diff --git a/bindings/java/build.xml b/bindings/java/build.xml
index d4e57f6..59fd854 100644
--- a/bindings/java/build.xml
+++ b/bindings/java/build.xml
@@ -55,7 +55,7 @@ Oregon, 97204-1622. -->
       <fileset dir="${src.c}" />
     </copy>
     <javah classpath="${build.classes}"
-           class="${package}.Tracer,${package}.Phase"
+           class="${package}.TracerCWrapper,${package}.Phase"
            destdir="${build.native}"
            verbose="yes" />
   </target>
diff --git a/bindings/java/examples/src/com/galois/ppaml/tracer/examples/Simple.java b/bindings/java/examples/src/com/galois/ppaml/tracer/examples/Simple.java
index a698573..f4a6b99 100644
--- a/bindings/java/examples/src/com/galois/ppaml/tracer/examples/Simple.java
+++ b/bindings/java/examples/src/com/galois/ppaml/tracer/examples/Simple.java
@@ -3,6 +3,7 @@
 
 package com.galois.ppaml.tracer.examples;
 
+import com.galois.ppaml.tracer.ExplicitlyConfiguredTracer;
 import com.galois.ppaml.tracer.Phase;
 import com.galois.ppaml.tracer.Tracer;
 
@@ -72,7 +73,7 @@ public class Simple {
 
 	public static void main(String[] args) {
 		// Start ppamltracer.
-		Tracer tracer = new Tracer("/tmp/simple_report");
+		Tracer tracer = new ExplicitlyConfiguredTracer("/tmp/simple_report");
 
 		// Run the app.
 		(new Simple()).go(tracer);
diff --git a/bindings/java/src/c/Makefile.am b/bindings/java/src/c/Makefile.am
index c30a4cf..275d482 100644
--- a/bindings/java/src/c/Makefile.am
+++ b/bindings/java/src/c/Makefile.am
@@ -24,8 +24,8 @@ lib_LTLIBRARIES = libppamltracer_java.la
 libppamltracer_java_la_SOURCES = \
 	$(srcdir)/com_galois_ppaml_tracer_Phase.c \
 	$(srcdir)/com_galois_ppaml_tracer_Phase.h \
-	$(srcdir)/com_galois_ppaml_tracer_Tracer.c \
-	$(srcdir)/com_galois_ppaml_tracer_Tracer.h \
+	$(srcdir)/com_galois_ppaml_tracer_TracerCWrapper.c \
+	$(srcdir)/com_galois_ppaml_tracer_TracerCWrapper.h \
 	$(srcdir)/pointer.h
 libppamltracer_java_la_CFLAGS = \
 	-std=c99 \
diff --git a/bindings/java/src/c/com_galois_ppaml_tracer_Tracer.c b/bindings/java/src/c/com_galois_ppaml_tracer_TracerCWrapper.c
index 2c23966..19a313c 100644
--- a/bindings/java/src/c/com_galois_ppaml_tracer_Tracer.c
+++ b/bindings/java/src/c/com_galois_ppaml_tracer_TracerCWrapper.c
@@ -1,4 +1,5 @@
-/* com_galois_ppaml_tracer_Tracer.c -- JNI wrapper for com.galois.ppaml.tracer.Tracer
+/* com_galois_ppaml_tracer_TracerCWrapper.c -- JNI wrapper for
+ *     com.galois.ppaml.tracer.TracerCWrapper
  * Copyright (C) 2014  Galois, Inc.
  *
  * This library is free software: you can redistribute it and/or modify it
@@ -23,12 +24,12 @@
 #include <ppaml/tracer.h>
 
 #include <jni.h>
-#include <com_galois_ppaml_tracer_Tracer.h>
+#include <com_galois_ppaml_tracer_TracerCWrapper.h>
 
 #include "pointer.h"
 
 JNIEXPORT
-jlong JNICALL Java_com_galois_ppaml_tracer_Tracer_mallocTracer(
+jlong JNICALL Java_com_galois_ppaml_tracer_TracerCWrapper_mallocTracer(
 	JNIEnv *const env,
 	jclass Tracer)
 {
@@ -36,7 +37,7 @@ jlong JNICALL Java_com_galois_ppaml_tracer_Tracer_mallocTracer(
 }
 
 JNIEXPORT
-jint JNICALL Java_com_galois_ppaml_tracer_Tracer_ppaml_1tracer_1init(
+jint JNICALL Java_com_galois_ppaml_tracer_TracerCWrapper_ppaml_1tracer_1init(
 	JNIEnv *const env,
 	jclass Tracer,
 	jlong tracer,
@@ -58,7 +59,16 @@ done:	(*env)->ReleaseStringUTFChars(env, reportNameBase, cReportNameBase);
 }
 
 JNIEXPORT
-jint JNICALL Java_com_galois_ppaml_tracer_Tracer_ppaml_1tracer_1done(
+jint JNICALL Java_com_galois_ppaml_tracer_TracerCWrapper_ppaml_1tracer_1init_1from_1env(
+	JNIEnv *const env,
+	jclass Tracer,
+	jlong tracer)
+{
+	return ppaml_tracer_init_from_env(pointer_of_jlong(tracer));
+}
+
+JNIEXPORT
+jint JNICALL Java_com_galois_ppaml_tracer_TracerCWrapper_ppaml_1tracer_1done(
 	JNIEnv *const env,
 	jclass Tracer,
 	jlong tracer)
@@ -67,7 +77,7 @@ jint JNICALL Java_com_galois_ppaml_tracer_Tracer_ppaml_1tracer_1done(
 }
 
 JNIEXPORT
-void JNICALL Java_com_galois_ppaml_tracer_Tracer_freeTracer(
+void JNICALL Java_com_galois_ppaml_tracer_TracerCWrapper_freeTracer(
 	JNIEnv *const env,
 	jclass Tracer,
 	jlong tracer)
diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/ConfigurationException.java b/bindings/java/src/java/com/galois/ppaml/tracer/ConfigurationException.java
new file mode 100644
index 0000000..57ed28e
--- /dev/null
+++ b/bindings/java/src/java/com/galois/ppaml/tracer/ConfigurationException.java
@@ -0,0 +1,34 @@
+/* ConfigurationException -- signals a configuration failure
+ * Copyright (C) 2014  Galois, Inc.
+ *
+ * This library is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option)
+ * any later version.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this library.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * To contact Galois, complete the Web form at
+ * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest
+ * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */
+
+package com.galois.ppaml.tracer;
+
+/**
+ * Signals a failure related to tracer configuration.
+ */
+public class ConfigurationException extends java.lang.RuntimeException {
+
+    static final long serialVersionUID = 3219379892261890429L;
+
+    protected ConfigurationException(String s) {
+        super(s);
+    }
+
+}
diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/EnvironmentConfiguredTracer.java b/bindings/java/src/java/com/galois/ppaml/tracer/EnvironmentConfiguredTracer.java
new file mode 100644
index 0000000..925e3e2
--- /dev/null
+++ b/bindings/java/src/java/com/galois/ppaml/tracer/EnvironmentConfiguredTracer.java
@@ -0,0 +1,84 @@
+/* EnvironmentConfiguredTracer -- tracer initialized with ppaml_tracer_init_from_env
+ * Copyright (C) 2014  Galois, Inc.
+ *
+ * This library is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option)
+ * any later version.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this library.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * To contact Galois, complete the Web form at
+ * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest
+ * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */
+
+package com.galois.ppaml.tracer;
+
+/**
+ * A tracer initialized automatically from environment variables.
+ *
+ * <p>The currently-supported environment variables are:
+ *
+ * <dl>
+ *   <dt><code>PPAMLTRACER_TRACE_BASE</code></dt><dd>All trace file paths will
+ *     begin with this path.</dd>
+ */
+public final class EnvironmentConfiguredTracer extends TracerCWrapper {
+
+    /**
+     * Creates and initializes an <code>EnvironmentConfiguredTracer</code>.  The
+     * trace report will be stored in Open Trace Format.
+     */
+    public EnvironmentConfiguredTracer() {
+        super.open();
+    }
+
+    ////////////////////////// Low-level life cycle  //////////////////////////
+
+    ///// JNI adapter code /////
+
+    /**
+     * Installs data into the structure to make it ready for use.
+     *
+     * <p> <b>Precondition:</b> Initialization succeeded.
+     *
+     * @throws OTFManagerInitializationException the Open Trace Format file
+     * manager could not be initialized.
+     *
+     * @throws OTFWriterInitializationException the Open Trace Format writer
+     * could not be initialized.
+     *
+     * @throws OTFWriterResolutionException setting the trace resolution failed.
+     *
+     * @throws OTFWriterProcessDefinitionException defining the main OTF process
+     * failed.
+     */
+    @Override
+    protected void initializeCPointer() {
+        assert this.cPointer != 0;
+        final int r = ppaml_tracer_init_from_env(this.cPointer);
+        switch (r) {
+        case 0:
+            break;
+        case 1:
+            throw new OTFManagerInitializationException();
+        case 2:
+            throw new OTFWriterInitializationException();
+        case 3:
+            throw new OTFWriterResolutionException();
+        case 4:
+            throw new OTFWriterProcessDefinitionException("main");
+        case 5:
+            throw new UndefinedTracerBasePathException();
+        default:
+            throw new UnexpectedReturnValueError(r);
+        }
+    }
+
+}
diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/ExplicitlyConfiguredTracer.java b/bindings/java/src/java/com/galois/ppaml/tracer/ExplicitlyConfiguredTracer.java
new file mode 100644
index 0000000..5006e04
--- /dev/null
+++ b/bindings/java/src/java/com/galois/ppaml/tracer/ExplicitlyConfiguredTracer.java
@@ -0,0 +1,91 @@
+/* ExplicitlyConfiguredTracer -- tracer initialized with ppaml_tracer_init
+ * Copyright (C) 2014  Galois, Inc.
+ *
+ * This library is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option)
+ * any later version.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this library.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * To contact Galois, complete the Web form at
+ * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest
+ * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */
+
+package com.galois.ppaml.tracer;
+
+/**
+ * A tracer initialized with an explicit set of configuration parameters.
+ */
+public final class ExplicitlyConfiguredTracer extends TracerCWrapper {
+
+    /**
+     * Base file path for trace report output.
+     */
+    private final String reportNameBase;
+
+    /**
+     * Creates and initializes an <code>ExplicitlyConfiguredTracer</code>.  The
+     * trace report will be stored in Open Trace Format.
+     *
+     * @param reportNameBase all trace file paths will begin with this path.
+     */
+    public ExplicitlyConfiguredTracer(final String reportNameBase) {
+        this.reportNameBase = reportNameBase;
+        super.open();
+    }
+
+    ////////////////////////// Low-level life cycle  //////////////////////////
+
+    ///// JNI adapter code /////
+
+    /**
+     * Installs data into the structure to make it ready for use.
+     *
+     * <p> <b>Precondition:</b> Initialization succeeded.
+     *
+     * @throws OutOfMemoryError converting <code>reportNameBase</code> from a
+     * <code>String</code> to a <code>char *</code> failed.
+     *
+     * @throws OTFManagerInitializationException the Open Trace Format file
+     * manager could not be initialized.
+     *
+     * @throws OTFWriterInitializationException the Open Trace Format writer
+     * could not be initialized.
+     *
+     * @throws OTFWriterResolutionException setting the trace resolution failed.
+     *
+     * @throws OTFWriterProcessDefinitionException defining the main OTF process
+     * failed.
+     */
+    @Override
+    protected void initializeCPointer() {
+        assert this.cPointer != 0;
+        assert reportNameBase != null;
+        final int r = ppaml_tracer_init(this.cPointer, reportNameBase);
+        switch (r) {
+        case 0:
+            break;
+        case -1:
+            throw new java.lang.OutOfMemoryError(
+                "failed to convert Java string to C string");
+        case 1:
+            throw new OTFManagerInitializationException();
+        case 2:
+            throw new OTFWriterInitializationException();
+        case 3:
+            throw new OTFWriterResolutionException();
+        case 4:
+            throw new OTFWriterProcessDefinitionException("main");
+        default:
+            throw new UnexpectedReturnValueError(r);
+        }
+    }
+
+}
diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/Phase.java b/bindings/java/src/java/com/galois/ppaml/tracer/Phase.java
index 23ed2f4..019704f 100644
--- a/bindings/java/src/java/com/galois/ppaml/tracer/Phase.java
+++ b/bindings/java/src/java/com/galois/ppaml/tracer/Phase.java
@@ -27,9 +27,9 @@ package com.galois.ppaml.tracer;
 public final class Phase extends CWrapper {
 
     /**
-     * The <code>Tracer</code> this phase is associated with.
+     * The <code>TracerCWrapper</code> this phase is associated with.
      */
-    private final Tracer tracer;
+    private final TracerCWrapper tracer;
 
     /**
      * The name of the phase.
@@ -38,14 +38,14 @@ public final class Phase extends CWrapper {
 
     /**
      * Creates and initializes a <code>Phase</code>.  You should not call this;
-     * call {@link Tracer.createPhase} instead.
+     * call <code>Tracer.createPhase</code> instead.
      *
-     * @param tracer the {@link Tracer} to associate the <code>Phase</code>
-     * with.
+     * @param tracer the {@link TracerCWrapper} to associate the
+     * <code>Phase</code> with.
      *
      * @param name the name of the phase.
      */
-    protected Phase(Tracer tracer, final String name) {
+    protected Phase(TracerCWrapper tracer, final String name) {
         this.tracer = tracer;
         this.name = name;
         super.open();
diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/Tracer.java b/bindings/java/src/java/com/galois/ppaml/tracer/Tracer.java
index fe0a180..24ca8e7 100644
--- a/bindings/java/src/java/com/galois/ppaml/tracer/Tracer.java
+++ b/bindings/java/src/java/com/galois/ppaml/tracer/Tracer.java
@@ -1,4 +1,4 @@
-/* Tracer -- wrapped ppaml_tracer_t
+/* Tracer -- Java analogue to ppaml_tracer_t
  * Copyright (C) 2014  Galois, Inc.
  *
  * This library is free software: you can redistribute it and/or modify it
@@ -21,29 +21,13 @@
 package com.galois.ppaml.tracer;
 
 /**
- * State class for ppamltracer.
+ * State bundle for ppamltracer.
  *
- * <p> ppamltracer is fundamentally a set of stateful operations; a
- * <code>Tracer</code> object holds the state ppamltracer needs to operate
+ * <p> ppamltracer is fundamentally a set of stateful operations; an object
+ * implementing <code>Tracer</code> holds the state ppamltracer needs to operate
  * properly.
  */
-public final class Tracer extends CWrapper {
-
-    /**
-     * Base file path for trace report output.
-     */
-    private final String reportNameBase;
-
-    /**
-     * Creates and initializes a <code>Tracer</code>.  The trace report will be
-     * stored in Open Trace Format.
-     *
-     * @param reportNameBase all trace file paths will begin with this path.
-     */
-    public Tracer(final String reportNameBase) {
-        this.reportNameBase = reportNameBase;
-        super.open();
-    }
+public interface Tracer {
 
     /**
      * Creates and initializes a {@link Phase} associated with this
@@ -51,113 +35,11 @@ public final class Tracer extends CWrapper {
      *
      * @param name the name of the phase.
      */
-    public Phase createPhase(final String name) {
-        return new Phase(this, name);
-    }
-
-
-    ////////////////////////// Low-level life cycle  //////////////////////////
-
-    ///// JNI shared library /////
-
-    static {
-        System.loadLibrary("ppamltracer_java");
-    }
+    public Phase createPhase(final String name);
 
     /**
-     * Wraps <code>malloc</code> to allocate a <code>ppaml_tracer_t</code>.
-     *
-     * @return Same as <code>malloc</code>.
+     * Finalizes and frees the underlying structure.
      */
-    private static native long mallocTracer();
-
-    /**
-     * Wraps <code>ppaml_tracer_init</code>.
-     *
-     * @return -1 if converting <code>reportNameBase</code> from a
-     * <code>String</code> to a <code>char *</code> failed; all other return
-     * codes are the same as <code>ppaml_tracer_init</code>.
-     */
-    private static native int ppaml_tracer_init(
-        long tracer,
-        final String reportNameBase);
-
-    /**
-     * Wraps <code>ppaml_tracer_done</code>.
-     *
-     * @return Same as <code>ppaml_tracer_done</code>.
-     */
-    private static native int ppaml_tracer_done(long tracer);
-
-    /**
-     * Wraps <code>free</code>.
-     */
-    private static native void freeTracer(long tracer);
-
-
-    ///// JNI adapter code /////
-
-    @Override
-    protected void allocateCPointer() {
-        this.cPointer = mallocTracer();
-    }
-
-    /**
-     * Installs data into the structure to make it ready for use.
-     *
-     * <p> <b>Precondition:</b> Initialization succeeded.
-     *
-     * @throws OutOfMemoryError converting <code>reportNameBase</code> from a
-     * <code>String</code> to a <code>char *</code> failed.
-     *
-     * @throws OTFManagerInitializationException the Open Trace Format file
-     * manager could not be initialized.
-     *
-     * @throws OTFWriterInitializationException the Open Trace Format writer
-     * could not be initialized.
-     *
-     * @throws OTFWriterResolutionException setting the trace resolution failed.
-     *
-     * @throws OTFWriterProcessDefinitionException defining the main OTF process
-     * failed.
-     */
-    @Override
-    protected void initializeCPointer() {
-        assert this.cPointer != 0;
-        assert reportNameBase != null;
-        final int r = ppaml_tracer_init(this.cPointer, reportNameBase);
-        switch (r) {
-        case 0:
-            break;
-        case -1:
-            throw new java.lang.OutOfMemoryError(
-                "failed to convert Java string to C string");
-        case 1:
-            throw new OTFManagerInitializationException();
-        case 2:
-            throw new OTFWriterInitializationException();
-        case 3:
-            throw new OTFWriterResolutionException();
-        case 4:
-            throw new OTFWriterProcessDefinitionException("main");
-        default:
-            throw new UnexpectedReturnValueError(r);
-        }
-    }
-
-    @Override
-    protected void finalizeCPointer() {
-        assert this.cPointer != 0;
-        final int r = ppaml_tracer_done(this.cPointer);
-        if (r != 0) {
-            throw new UnexpectedReturnValueError(r);
-        }
-    }
-
-    @Override
-    protected void freeCPointer() {
-        assert this.cPointer != 0;
-        freeTracer(this.cPointer);
-    }
+    public void close();
 
 }
diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/TracerCWrapper.java b/bindings/java/src/java/com/galois/ppaml/tracer/TracerCWrapper.java
new file mode 100644
index 0000000..4f4dc0a
--- /dev/null
+++ b/bindings/java/src/java/com/galois/ppaml/tracer/TracerCWrapper.java
@@ -0,0 +1,105 @@
+/* TracerCWrapper -- wrapped ppaml_tracer_t
+ * Copyright (C) 2014  Galois, Inc.
+ *
+ * This library is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option)
+ * any later version.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this library.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * To contact Galois, complete the Web form at
+ * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest
+ * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */
+
+package com.galois.ppaml.tracer;
+
+/**
+ * Abstract base class for all tracer implementations.
+ */
+abstract class TracerCWrapper extends CWrapper implements Tracer {
+
+    @Override
+    public Phase createPhase(final String name) {
+        return new Phase(this, name);
+    }
+
+
+    ////////////////////////// Low-level life cycle  //////////////////////////
+
+    ///// JNI shared library /////
+
+    static {
+        System.loadLibrary("ppamltracer_java");
+    }
+
+    /**
+     * Wraps <code>malloc</code> to allocate a <code>ppaml_tracer_t</code>.
+     *
+     * @return Same as <code>malloc</code>.
+     */
+    protected static native long mallocTracer();
+
+    /**
+     * Wraps <code>ppaml_tracer_init</code>.
+     *
+     * @return -1 if converting <code>reportNameBase</code> from a
+     * <code>String</code> to a <code>char *</code> failed; all other return
+     * codes are the same as <code>ppaml_tracer_init</code>.
+     */
+    protected static native int ppaml_tracer_init(
+        long tracer,
+        final String reportNameBase);
+
+    /**
+     * Wraps <code>ppaml_tracer_init_from_env</code>.
+     *
+     * @return Same as <code>ppaml_tracer_init_from_env</code>.
+     */
+    protected static native int ppaml_tracer_init_from_env(long tracer);
+
+    /**
+     * Wraps <code>ppaml_tracer_done</code>.
+     *
+     * @return Same as <code>ppaml_tracer_done</code>.
+     */
+    protected static native int ppaml_tracer_done(long tracer);
+
+    /**
+     * Wraps <code>free</code>.
+     */
+    protected static native void freeTracer(long tracer);
+
+
+    ///// JNI adapter code /////
+
+    @Override
+    protected void allocateCPointer() {
+        this.cPointer = mallocTracer();
+    }
+
+    @Override
+    protected abstract void initializeCPointer();
+
+    @Override
+    protected void finalizeCPointer() {
+        assert this.cPointer != 0;
+        final int r = ppaml_tracer_done(this.cPointer);
+        if (r != 0) {
+            throw new UnexpectedReturnValueError(r);
+        }
+    }
+
+    @Override
+    protected void freeCPointer() {
+        assert this.cPointer != 0;
+        freeTracer(this.cPointer);
+    }
+
+}
diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/UndefinedTracerBasePathException.java b/bindings/java/src/java/com/galois/ppaml/tracer/UndefinedTracerBasePathException.java
new file mode 100644
index 0000000..1a67826
--- /dev/null
+++ b/bindings/java/src/java/com/galois/ppaml/tracer/UndefinedTracerBasePathException.java
@@ -0,0 +1,34 @@
+/* UndefinedTracerBasePathException -- no tracer path specified
+ * Copyright (C) 2014  Galois, Inc.
+ *
+ * This library is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option)
+ * any later version.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this library.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * To contact Galois, complete the Web form at
+ * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest
+ * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */
+
+package com.galois.ppaml.tracer;
+
+/**
+ * Indicates that a tracer attempted to initialize with an undefined path.
+ */
+public class UndefinedTracerBasePathException extends ConfigurationException {
+
+    static final long serialVersionUID = 8041122764340259905L;
+
+    protected UndefinedTracerBasePathException() {
+        super("attempted to configure tracer with undefined base path");
+    }
+
+}
diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/package-info.java b/bindings/java/src/java/com/galois/ppaml/tracer/package-info.java
index f922274..7c0d6e5 100644
--- a/bindings/java/src/java/com/galois/ppaml/tracer/package-info.java
+++ b/bindings/java/src/java/com/galois/ppaml/tracer/package-info.java
@@ -30,7 +30,7 @@
  *
  * <pre>
  *   // Create report.
- *   Tracer tracer = new Tracer("/tmp/my_report");
+ *   Tracer tracer = new ExplicitlyConfiguredTracer("/tmp/my_report");
  *
  *   // Register phase 1 and do stuff.
  *   Phase phase = tracer.createPhase("phase 1");