You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2015/07/30 23:14:17 UTC

incubator-tinkerpop git commit: Update javadocs around transactions and Graph.close()

Repository: incubator-tinkerpop
Updated Branches:
  refs/heads/tp30 d384111fc -> 58b699e6b


Update javadocs around transactions and Graph.close()


Project: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/commit/58b699e6
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/tree/58b699e6
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/diff/58b699e6

Branch: refs/heads/tp30
Commit: 58b699e6b636eb40a6868725c85a245996798fbd
Parents: d384111
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Thu Jul 30 16:58:43 2015 -0400
Committer: Stephen Mallette <sp...@genoprime.com>
Committed: Thu Jul 30 16:58:43 2015 -0400

----------------------------------------------------------------------
 .../tinkerpop/gremlin/structure/Graph.java      | 14 ++++++++-
 .../gremlin/structure/Transaction.java          | 30 ++++++++++----------
 2 files changed, 28 insertions(+), 16 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/58b699e6/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/Graph.java
----------------------------------------------------------------------
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/Graph.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/Graph.java
index 99b82dd..d4c15d8 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/Graph.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/Graph.java
@@ -239,11 +239,23 @@ public interface Graph extends AutoCloseable, Host {
     public Iterator<Edge> edges(final Object... edgeIds);
 
     /**
-     * Configure and control the transactions for those graphs that support this feature.
+     * Configure and control the transactions for those graphs that support this feature.  Note that this method does
+     * not indicate the creation of a "transaction" object.  A {@link Transaction} in the TinkerPop context is a
+     * transaction "factory" or "controller" that helps manage transactions owned by the underlying graph database.
      */
     public Transaction tx();
 
     /**
+     * Closing a {@code Graph} is equivalent to "shutdown".  Users should consult the documentation of the underlying
+     * graph database implementation for what this "shutdown" will mean as it pertains to open transactions.  It will
+     * typically be the end user's responsibility to synchronize the thread that calls {@code close()} with other
+     * threads that are accessing open transactions. In other words, be sure that all work performed on the
+     * {@code Graph} instance is complete prior to calling this method.
+     */
+    @Override
+    void close() throws Exception;
+
+    /**
      * Construct a particular {@link Io} implementation for reading and writing the {@code Graph} and other data.
      * End-users will "select" the {@link Io} implementation that they want to use by supplying the {@link Io.Builder}
      * that constructs it.  In this way, {@code Graph} vendors can supply their {@link IoRegistry} to that builder

http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/58b699e6/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/Transaction.java
----------------------------------------------------------------------
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/Transaction.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/Transaction.java
index e97a914..d80c87f 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/Transaction.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/Transaction.java
@@ -18,6 +18,8 @@
  */
 package org.apache.tinkerpop.gremlin.structure;
 
+import org.apache.tinkerpop.gremlin.structure.util.AbstractTransaction;
+
 import java.io.Closeable;
 import java.util.Collections;
 import java.util.Set;
@@ -27,8 +29,8 @@ import java.util.function.Function;
 
 /**
  * A set of methods that allow for control of transactional behavior of a {@link Graph} instance. Vendors may
- * consider using {@link org.apache.tinkerpop.gremlin.structure.util.AbstractTransaction} as a base implementation
- * that provides default features for most of these methods.
+ * consider using {@link AbstractTransaction} as a base implementation that provides default features for most of
+ * these methods.
  * <p/>
  * It is expected that this interface be implemented by vendors in a {@link ThreadLocal} fashion. In other words
  * transactions are bound to the current thread, which means that any graph operation executed by the thread occurs
@@ -93,9 +95,8 @@ public interface Transaction extends Closeable {
     public Transaction onReadWrite(final Consumer<Transaction> consumer);
 
     /**
-     * Describes what happens to a transaction on a call to {@link org.apache.tinkerpop.gremlin.structure.Graph#close()}.
-     * This value can be set using standard behavior defined in {@link CLOSE_BEHAVIOR} or a mapper {@link Consumer}
-     * function.
+     * Describes what happens to a transaction on a call to {@link Graph#close()}. This value can be set using
+     * standard behavior defined in {@link CLOSE_BEHAVIOR} or a mapper {@link Consumer} function.
      */
     public Transaction onClose(final Consumer<Transaction> consumer);
 
@@ -155,9 +156,9 @@ public interface Transaction extends Closeable {
     }
 
     /**
-     * Behaviors to supply to the {@link #onClose(java.util.function.Consumer)}.
+     * Behaviors to supply to the {@link #onClose(Consumer)}.
      */
-    public static enum CLOSE_BEHAVIOR implements Consumer<Transaction> {
+    public enum CLOSE_BEHAVIOR implements Consumer<Transaction> {
         /**
          * Any open transaction will commit on close.
          */
@@ -190,9 +191,9 @@ public interface Transaction extends Closeable {
     }
 
     /**
-     * Behaviors to supply to the {@link #onReadWrite(java.util.function.Consumer)}.
+     * Behaviors to supply to the {@link #onReadWrite(Consumer)}.
      */
-    public static enum READ_WRITE_BEHAVIOR implements Consumer<Transaction> {
+    public enum READ_WRITE_BEHAVIOR implements Consumer<Transaction> {
         /**
          * Transactions are automatically started when a read or a write occurs.
          */
@@ -215,12 +216,11 @@ public interface Transaction extends Closeable {
     }
 
     /**
-     * A {@link Workload} represents a unit of work constructed by the
-     * {@link Workload#submit(java.util.function.Function)} method on the {@link Transaction} interface.
-     * The unit of work is a {@link java.util.function.Function} typically containing mutations to the {@link Graph}.  The
-     * {@link Workload} is responsible for executing the unit of work in the context of a retry strategy, such that a
-     * failed unit of work is rolled back and executed again until retries are exhausted or the unit of work succeeds
-     * with a commit operation.
+     * A {@link Workload} represents a unit of work constructed by the {@link Workload#submit(Function)} method on
+     * the {@link Transaction} interface. The unit of work is a {@link Function} typically containing mutations to
+     * the {@link Graph}.  The {@link Workload} is responsible for executing the unit of work in the context of a
+     * retry strategy, such that a failed unit of work is rolled back and executed again until retries are exhausted
+     * or the unit of work succeeds with a commit operation.
      *
      * @param <R> The type of the result from the unit of work.
      */