Merge pull request #306 from technige/1.1-apidocs

Some API doc updates

Author: Zhen Li

driver/src/main/java/org/neo4j/driver/v1/AuthToken.java

@@ -19,10 +19,9 @@
 package org.neo4j.driver.v1;
 
 /**
- * This is a combination of a <b>Principal</b>, for instance a username,
- * and one or more <b>Credentials</b>, for instance a password. It is used
- * to authenticate with a Neo4j instance. See {@link AuthTokens}
- * for available types of {@link AuthToken}.
+ * Token for holding authentication details, such as <em>user name</em> and <em>password</em>.
+ * Such a token is required by a {@link Driver} to authenticate with a Neo4j
+ * instance.
  *
  * @see AuthTokens
  * @see GraphDatabase#driver(String, AuthToken)

driver/src/main/java/org/neo4j/driver/v1/Config.java

@@ -493,6 +493,7 @@ private TrustStrategy( Strategy strategy, File certFile )
 
         /**
          * Return the strategy type desired.
+         *
          * @return the strategy we should use
          */
         public Strategy strategy()
@@ -530,17 +531,15 @@ public static TrustStrategy trustCustomCertificateSignedBy( File certFile )
         }
 
         /**
-         *
-         * @return
+         * Trust strategy for certificates that can be verified through the local system store.
          */
         public static TrustStrategy trustSystemCertificates()
         {
             return new TrustStrategy( Strategy.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES );
         }
 
         /**
-         *
-         * @return
+         * Trust strategy for certificates that can be verified through the local system store.
          *
          * @since 1.1
          */

driver/src/main/java/org/neo4j/driver/v1/Driver.java

@@ -18,55 +18,40 @@
  */
 package org.neo4j.driver.v1;
 
-import java.net.URI;
-
 /**
- * A Neo4j database driver, through which you can create {@link Session sessions} to run statements against the database.
+ * Accessor for a specific Neo4j graph database.
  * <p>
- * An example:
- * <pre class="doctest:DriverDocIT#exampleUsage">
- * {@code
- * // Create a driver with default configuration
- * Driver driver = GraphDatabase.driver( "bolt://localhost:7687" );
- *
- * // Establish a session
- * Session session = driver.session();
- *
- * // Running a simple statement can be done like this
- * session.run( "CREATE (n {name:'Bob'})" );
- *
- * // Or, run multiple statements together in an atomic transaction:
- * try( Transaction tx = session.beginTransaction() )
- * {
- *     tx.run( "CREATE (n {name:'Alice'})" );
- *     tx.run( "CREATE (n {name:'Tina'})" );
- *     tx.success();
- * }
- *
- * // Retrieve results
- * StatementResult result = session.run( "MATCH (n) RETURN n.name" );
- * List<String> names = new LinkedList<>();
- * while( result.hasNext() )
- * {
- *     names.add( result.next().get("n.name").asString() );
- * }
- *
- * // Sessions are pooled, to avoid the overhead of creating new connections - this means
- * // it is very important to close your session when you are done with it, otherwise you will
- * // run out of sessions.
- * session.close();
- *
- * // And, to clean up resources, always close the driver when your application is done
- * driver.close();
- * }
- * </pre>
+ * Driver implementations are typically thread-safe, act as a template
+ * for {@link Session} creation and host a connection pool. All configuration
+ * and authentication settings are held immutably by the Driver. Should
+ * different settings be required, a new Driver instance should be created.
  * <p>
+ * A driver maintains a connection pool for each remote Neo4j server. Therefore
+ * the most efficient way to make use of a Driver is to use the same instance
+ * across the application.
+ * <p>
+ * To construct a new Driver, use one of the
+ * {@link GraphDatabase#driver(String, AuthToken) GraphDatabase.driver} methods.
+ * The <a href="https://tools.ietf.org/html/rfc3986">URI</a> passed to
+ * this method determines the type of Driver created.
+ * <br>
+ * <table border="1" cellpadding="4" style="border-collapse: collapse">
+ *     <thead>
+ *         <tr><th>URI Scheme</th><th>Driver</th></tr>
+ *     </thead>
+ *     <tbody>
+ *         <tr>
+ *             <td><code>bolt</code></td>
+ *             <td>Direct driver: connects directly to the host and port specified in the URI.</td>
+ *         </tr>
+ *         <tr>
+ *             <td><code>bolt+routing</code></td>
+ *             <td>Routing driver: can automatically discover members of a Causal Cluster and route {@link Session sessions} based on {@link AccessMode}.</td>
+ *         </tr>
+ *     </tbody>
+ * </table>
  *
- * A driver maintains a connection pool for each Neo4j instance. For resource efficiency reasons you are encouraged
- * to use the same driver instance across your application. You can control the connection pooling behavior when you
- * create the driver using the {@link Config} you pass into {@link GraphDatabase#driver(URI, Config)}.
- *
- * @since 1.0
+ * @since 1.0 (<em>bolt+routing</em> URIs since 1.1)
  */
 public interface Driver extends AutoCloseable
 {
@@ -78,17 +63,22 @@ public interface Driver extends AutoCloseable
     boolean isEncrypted();
 
     /**
-     * Establish a session
+     * Create a new general purpose {@link Session}.
      *
-     * @return a session that could be used to run {@link Session#run(String) a statement} or
-     * {@link Session#beginTransaction() a transaction }.
+     * @return a new {@link Session} object.
      */
     Session session();
 
+    /**
+     * Create a new {@link Session} for a specific type of work.
+     *
+     * @param mode the type of access required by units of work in this session, e.g. {@link AccessMode#READ read access}.
+     * @return a new {@link Session} object.
+     */
     Session session(AccessMode mode);
 
     /**
-     * Close all the resources assigned to this driver
+     * Close all the resources assigned to this driver, including any open connections.
      */
     void close();
 }

driver/src/main/java/org/neo4j/driver/v1/Logger.java

@@ -18,6 +18,9 @@
  */
 package org.neo4j.driver.v1;
 
+/**
+ * Logs messages for driver activity.
+ */
 public interface Logger
 {
     void error( String message, Throwable cause );

driver/src/main/java/org/neo4j/driver/v1/Logging.java

@@ -18,7 +18,16 @@
  */
 package org.neo4j.driver.v1;
 
+/**
+ * Accessor for {@link Logger} instances.
+ */
 public interface Logging
 {
+    /**
+     * Obtain a {@link Logger} instance by name.
+     *
+     * @param name name of a {@link Logger}
+     * @return {@link Logger} instance
+     */
     Logger getLog( String name );
 }

driver/src/main/java/org/neo4j/driver/v1/Record.java

@@ -30,13 +30,15 @@
 import org.neo4j.driver.v1.util.Pair;
 
 /**
- * A record is the object you work with when reading {@link StatementResult} - results
- * are streams of records, where records carry the values your statement returned.
+ * Container for Cypher result values.
+ * <p>
+ * Streams of records are returned from Cypher statement execution, contained
+ * within a {@link StatementResult}.
+ * <p>
+ * A record is a form of ordered map and, as such, contained values can be
+ * accessed by either positional {@link #get(int) index} or textual
+ * {@link #get(String) key}.
  *
- * Records are made up of named, ordered {@link #fields() fields}, each field has
- * a key and a value, both are determined by the statement you've executed. To
- * access the values in your result, you can either use the field key or the field
- * index, meaning the position the field has in the record.
  * @since 1.0
  */
 @Immutable

driver/src/main/java/org/neo4j/driver/v1/Session.java

@@ -21,6 +21,8 @@
 import org.neo4j.driver.v1.util.Resource;
 
 /**
+ * Provides a context of work for database interactions.
+ * <p>
  * A <em>Session</em> hosts a series of {@linkplain Transaction transactions}
  * carried out against a database. Within the database, all statements are
  * carried out within a transaction. Within application code, however, it is

driver/src/main/java/org/neo4j/driver/v1/StatementResult.java

@@ -28,7 +28,7 @@
 
 
 /**
- * The result of running a statement, conceptually a stream of {@link Record records}.
+ * The result of running a Cypher statement, conceptually a stream of {@link Record records}.
  *
  * The standard way of navigating through the result returned by the database is to
  * {@link #next() iterate} over it.

driver/src/main/java/org/neo4j/driver/v1/Transaction.java

@@ -21,29 +21,25 @@
 import org.neo4j.driver.v1.util.Resource;
 
 /**
- * Represents a transaction in the Neo4j database.
- *
- * This interface may seem surprising in that it does not have explicit "commit" or "rollback" methods.
- * It is designed to minimize the complexity of the code you need to write to use transactions in a safe way, ensuring
- * that transactions are properly rolled back even if there is an exception while the transaction is running.
- *
- * <h2>Example:</h2>
- *
+ * Logical container for an atomic unit of work.
+ * <p>
+ * A driver Transaction object corresponds to a server transaction.
+ * Transactions are typically wrapped in a try-with-resources block
+ * which ensures that <code>COMMIT</code> or <code>ROLLBACK</code>
+ * occurs correctly on close.Note that <code>ROLLBACK</code> is the
+ * default action unless {@link #success()} is called before closing.
  * <pre class="docTest:TransactionDocIT#classDoc">
  * {@code
- * try( Transaction tx = session.beginTransaction() )
+ * try(Transaction tx = session.beginTransaction())
  * {
- *     tx.run( "CREATE (n)" );
+ *     tx.run("CREATE (a:Person {name: {x}})", parameters("x", "Alice"));
  *     tx.success();
  * }
  * }
  * </pre>
  *
- * <h2>Important note on semantics</h2>
- *
- * Please see the section under {@link StatementRunner} for an important overview of the guarantees
- * the transaction gives you around when statements are executed.
- *
+ * @see Session#run
+ * @see StatementRunner
  * @since 1.0
  */
 public interface Transaction extends Resource, StatementRunner
@@ -67,7 +63,7 @@ public interface Transaction extends Resource, StatementRunner
      * {@code
      * try(Transaction tx = session.beginTransaction() )
      * {
-     *     tx.run( "CREATE (n)" );
+     *     tx.run("CREATE (a:Person {name: {x}})", parameters("x", "Alice"));
      *     tx.failure();
      * }
      * }

driver/src/main/java/org/neo4j/driver/v1/Value.java

@@ -37,7 +37,7 @@
 import org.neo4j.driver.v1.util.Immutable;
 
 /**
- * Represents a value from Neo4j.
+ * A unit of data that adheres to the Neo4j type system.
  *
  * This interface describes a number of <code>isType</code> methods along with
  * <code>typeValue</code> methods. The first set of these correlate with types from

driver/src/main/javadoc/overview.html

@@ -5,27 +5,74 @@
 </HEAD>
 <BODY>
 
-This is the reference driver implementation for <a href="http://neo4j.com">Neo4j</a>, it allows you to connect to a
-Neo4j server and interact with it.
-If you are using Java, this is generally the interface you'd use to integrate Neo4j in your application.
+<p>These pages document the official <a href="https://neo4j.com" target="_top">Neo4j</a> driver for Java.</p>
 
-<h3>Getting Connected</h3>
+<h3>Example</h3>
 
-<p>Once you have the driver and a connector on your classpath, you can establish sessions with Neo4j.</p>
+<pre><code>import org.neo4j.driver.v1.*;
 
-<pre><code>Driver driver = GraphDatabase.driver( "bolt://localhost:7687", AuthTokens.basic( "neo4j", "p4ssw0rd" ) );
-try( Session session = driver.session() )
+import static org.neo4j.driver.v1.Values.parameters;
+
+public class SmallExample
 {
-    StatementResult result = session.run( "RETURN 'hello, world!'" );
-    while( result.hasNext() )
+    // Driver objects are thread-safe and are typically made available application-wide.
+    Driver driver;
+
+    public SmallExample(String uri, String user, String password)
+    {
+        driver = GraphDatabase.driver(uri, AuthTokens.basic(user, password));
+    }
+
+    private void addPerson(String name)
+    {
+        // Sessions are lightweight and disposable connection wrappers.
+        try (Session session = driver.session())
+        {
+            // Wrapping Cypher in an explicit transaction provides atomicity
+            // and makes handling errors much easier.
+            try (Transaction tx = session.beginTransaction())
+            {
+                tx.run("MERGE (a:Person {name: {x}})", parameters("x", name));
+                tx.success();  // Mark this write as successful.
+            }
+        }
+    }
+
+    private void printPeople(String initial)
     {
-        Record record = result.next();
-        System.out.println( record.get(0).asString() );
+        try (Session session = driver.session())
+        {
+            // Auto-commit transactions are a quick and easy way to wrap a read.
+            StatementResult result = session.run(
+                    "MATCH (a:Person) WHERE a.name STARTS WITH {x} RETURN a.name AS name",
+                    parameters("x", initial));
+            // Each Cypher execution returns a stream of records.
+            while (result.hasNext())
+            {
+                Record record = result.next();
+                // Values can be extracted from a record by index or name.
+                System.out.println(record.get("name").asString());
+            }
+        }
+    }
+
+    public void close()
+    {
+        // Closing a driver immediately shuts down all open connections.
+        driver.close();
+    }
+
+    public static void main(String... args)
+    {
+        SmallExample example = new SmallExample("bolt://localhost:7687", "neo4j", "password");
+        example.addPerson("Ada");
+        example.addPerson("Alice");
+        example.addPerson("Bob");
+        example.printPeople("A");
+        example.close();
     }
 }
 </code></pre>
 
-Have a look at the <a href="org/neo4j/driver/v1/Driver.html" title="interface in org.neo4j"><code>Driver</code></a>class to get started.
-
 </BODY>
 </HTML>