Mailing-List: contact commits-help@cassandra.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cassandra.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: aleksey@apache.org
To: commits@cassandra.apache.org
Date: Tue, 19 May 2015 13:42:30 -0000
Message-Id: <eeac30e3e63b4ce19927570f5d762169@git.apache.org>
Subject: [1/3] cassandra git commit: Improve javadoc around trigger execution

Repository: cassandra
Updated Branches:
  refs/heads/cassandra-2.2 86c9c00e9 -> 889c1872e


Improve javadoc around trigger execution

Patch by Sam Tunnicliffe; reviewed by brandonwilliams for CASSANDRA-9334


Project: http://git-wip-us.apache.org/repos/asf/cassandra/repo
Commit: http://git-wip-us.apache.org/repos/asf/cassandra/commit/37d81b9d
Tree: http://git-wip-us.apache.org/repos/asf/cassandra/tree/37d81b9d
Diff: http://git-wip-us.apache.org/repos/asf/cassandra/diff/37d81b9d

Branch: refs/heads/cassandra-2.2
Commit: 37d81b9dcb08dd8c16a560591f46481b5d316841
Parents: 0b92967
Author: Sam Tunnicliffe <sam@beobal.com>
Authored: Tue May 12 11:49:03 2015 +0100
Committer: Sam Tunnicliffe <sam@beobal.com>
Committed: Tue May 19 09:39:56 2015 +0100

----------------------------------------------------------------------
 .../org/apache/cassandra/triggers/ITrigger.java |  4 +--
 .../cassandra/triggers/TriggerExecutor.java     | 32 ++++++++++++++++++++
 2 files changed, 34 insertions(+), 2 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cassandra/blob/37d81b9d/src/java/org/apache/cassandra/triggers/ITrigger.java
----------------------------------------------------------------------
diff --git a/src/java/org/apache/cassandra/triggers/ITrigger.java b/src/java/org/apache/cassandra/triggers/ITrigger.java
index 15ed7ba..fe2a9e6 100644
--- a/src/java/org/apache/cassandra/triggers/ITrigger.java
+++ b/src/java/org/apache/cassandra/triggers/ITrigger.java
@@ -36,7 +36,7 @@ import org.apache.cassandra.db.RowMutation;
  * 2) ITrigger implementation can be instantiated multiple times during the server life time.
  *      (Depends on the number of times trigger folder is updated.)<br>
  * 3) ITrigger implementation should be state-less (avoid dependency on instance variables).<br>
- * 
+ *
  * <br><b>The API is still beta and can change.</b>
  */
 public interface ITrigger
@@ -46,7 +46,7 @@ public interface ITrigger
      *
      * @param key - Row Key for the update.
      * @param update - Update received for the CF
-     * @return modifications to be applied, null if no action to be performed.
+     * @return additional modifications to be applied along with the supplied update
      */
     public Collection<RowMutation> augment(ByteBuffer key, ColumnFamily update);
 }

http://git-wip-us.apache.org/repos/asf/cassandra/blob/37d81b9d/src/java/org/apache/cassandra/triggers/TriggerExecutor.java
----------------------------------------------------------------------
diff --git a/src/java/org/apache/cassandra/triggers/TriggerExecutor.java b/src/java/org/apache/cassandra/triggers/TriggerExecutor.java
index 988c6a7..bae0da6 100644
--- a/src/java/org/apache/cassandra/triggers/TriggerExecutor.java
+++ b/src/java/org/apache/cassandra/triggers/TriggerExecutor.java
@@ -64,6 +64,23 @@ public class TriggerExecutor
         cachedTriggers.clear();
     }
 
+    /**
+     * Augment a partition update by executing triggers to generate an intermediate
+     * set of mutations, then merging the ColumnFamily from each mutation with those
+     * supplied. This is called from @{link org.apache.cassandra.service.StorageProxy#cas}
+     * which is scoped for a single partition. For that reason, any mutations generated
+     * by triggers are checked to ensure that they are for the same table and partition
+     * key as the primary update; if not, InvalidRequestException is thrown. If no
+     * additional mutations are generated, the original updates are returned unmodified.
+     *
+     * @param key partition key for the update
+     * @param updates partition update to be applied, contains the merge of the original
+     *                update and any generated mutations
+     * @return the final update to be applied, the original update merged with any
+     * additional  mutations generated by configured triggers
+     * @throws InvalidRequestException if any mutation generated by a trigger does not
+     * apply to the exact same partition as the initial update
+     */
     public ColumnFamily execute(ByteBuffer key, ColumnFamily updates) throws InvalidRequestException
     {
         List<RowMutation> intermediate = executeInternal(key, updates);
@@ -79,6 +96,21 @@ public class TriggerExecutor
         return updates;
     }
 
+    /**
+     * Takes a collection of mutations and possibly augments it by adding extra mutations
+     * generated by configured triggers. If no additional mutations are created
+     * this returns null, signalling to the caller that only the initial set of
+     * mutations should be applied. If additional mutations <i>are</i> generated,
+     * the total set (i.e. the original plus the additional mutations) are applied
+     * together in a logged batch. Should this not be possible because the initial
+     * mutations contain counter updates, InvalidRequestException is thrown.
+     *
+     * @param mutations initial collection of mutations
+     * @return augmented mutations. Either the union of the initial and additional
+     * mutations or null if no additional mutations were generated
+     * @throws InvalidRequestException if additional mutations were generated, but
+     * the initial mutations contains counter updates
+     */
     public Collection<RowMutation> execute(Collection<? extends IMutation> mutations) throws InvalidRequestException
     {
         boolean hasCounters = false;