changed documented method from get/setDistributionKey to get/setPartitionKey

+ some extra docs on the area
updated docs by removing som async stuff


ndb/include/ndbapi/NdbTransaction.hpp:
  mostly reformatting but also some more explicit references to objects and methods

6 files changed, 96 insertions, 74 deletions

diff --git a/ndb/include/ndbapi/Ndb.hpp b/ndb/include/ndbapi/Ndb.hpp
index 666a3597fba..dcde0a66872 100644
--- a/ndb/include/ndbapi/Ndb.hpp
+++ b/ndb/include/ndbapi/Ndb.hpp
@@ -328,12 +328,13 @@
    - Scan subset of table using @ref NdbIndexScanOperation::setBound()
    - Ordering result set ascending or descending, 
      @ref NdbIndexScanOperation::readTuples()
-   - When using NdbIndexScanOperation::BoundEQ on distribution key 
-     only fragment containing rows will be scanned.
+   - When using NdbIndexScanOperation::BoundEQ on partition key 
+     only fragments containing rows will be scanned.
    
    Rows are returned unordered unless sorted is set to true.
 
-   @note When performing sorted scan, parameter parallelism to readTuples will
+   @note When performing sorted scan, parameter parallelism to 
+   NdbIndexScanOperation::readTuples() will
    be ignored and max parallelism will be used instead. 
 
    @subsection secScanLocks Lock handling with scans
@@ -343,10 +344,10 @@
 
    But Ndb will only lock a batch of rows per fragment at a time.
    How many rows will be locked per fragment is controlled by the 
-   batch parameter to @ref NdbScanOperation::readTuples.
+   batch parameter to NdbScanOperation::readTuples().
 
    To let the application handle how locks are released 
-   @ref NdbScanOperation::nextResult() have a parameter fetch_allow.
+   NdbScanOperation::nextResult() have a parameter fetch_allow.
    If NdbScanOperation::nextResult() is called with fetch_allow = false, no
    locks may be released as result of the function call. Otherwise the locks
    for the current batch may be released.
@@ -380,11 +381,12 @@
 
    One recommended way to handle a transaction failure 
    (i.e. an error is reported) is to:
-   -# Rollback transaction (NdbTransaction::execute with a special parameter)
+   -# Rollback transaction (NdbTransaction::execute() with a special parameter)
    -# Close transaction
    -# Restart transaction (if the error was temporary)
 
-   @note Transaction are not automatically closed when an error occur.
+   @note Transactions are not automatically closed when an error occur. Call
+   Ndb::closeTransaction() to close.
 
    Several errors can occur when a transaction holds multiple 
    operations which are simultaneously executed.
@@ -392,9 +394,9 @@
    objects and query for their NdbError objects to find out what really
    happened.
 
-   NdbTransaction::getNdbErrorOperation returns a reference to the 
+   NdbTransaction::getNdbErrorOperation() returns a reference to the 
    operation causing the latest error.
-   NdbTransaction::getNdbErrorLine delivers the method number of the 
+   NdbTransaction::getNdbErrorLine() delivers the method number of the 
    erroneous method in the operation.
 
    @code
@@ -417,14 +419,14 @@
    Getting errorLine == 0 means that the error occurred when executing the 
    operations.
    Here errorOperation will be a pointer to the theOperation object.
-   NdbTransaction::getNdbError will return the NdbError object 
+   NdbTransaction::getNdbError() will return the NdbError object 
    including holding information about the error.
 
    Since errors could have occurred even when a commit was reported,
-   there is also a special method, NdbTransaction::commitStatus,
+   there is also a special method, NdbTransaction::commitStatus(),
    to check the commit status of the transaction.
 
-*******************************************************************************/
+******************************************************************************/
 
 /**
  * @page ndbapi_simple.cpp ndbapi_simple.cpp
@@ -458,32 +460,14 @@
    @page secAdapt  Adaptive Send Algorithm
 
    At the time of "sending" the transaction 
-   (using NdbTransaction::execute), the transactions 
+   (using NdbTransaction::execute()), the transactions 
    are in reality <em>not</em> immediately transfered to the NDB Kernel.  
    Instead, the "sent" transactions are only kept in a 
    special send list (buffer) in the Ndb object to which they belong.
    The adaptive send algorithm decides when transactions should
    be transfered to the NDB kernel.
   
-   For each of these "sent" transactions, there are three 
-   possible states:
-   -# Waiting to be transferred to NDB Kernel.
-   -# Has been transferred to the NDB Kernel and is currently 
-      being processed.
-   -# Has been transferred to the NDB Kernel and has 
-      finished processing.
-      Now it is waiting for a call to a poll method.  
-      (When the poll method is invoked, 
-      then the transaction callback method will be executed.)
-      
-   The poll method invoked (either Ndb::pollNdb or Ndb::sendPollNdb)
-   will return when:
-   -# at least 'minNoOfEventsToWakeup' of the transactions
-      in the send list have transitioned to state 3 as described above, and 
-   -# all of these transactions have executed their callback methods.
-  
-  
-   Since the NDB API is designed as a multi-threaded interface, 
+   The NDB API is designed as a multi-threaded interface and
    it is desirable to transfer database operations from more than 
    one thread at a time. 
    The NDB API keeps track of which Ndb objects are active in transfering
@@ -514,14 +498,36 @@
       later releases of NDB Cluster.
       However, to support faster than 10 ms checks, 
       there has to be support from the operating system.
-   -# When calling NdbTransaction::execute synchronously or calling any 
-      of the poll-methods, there is a force parameter that overrides the 
-      adaptive algorithm and forces the send to all nodes.
+   -# When methods that are affected by the adaptive send alorithm,
+      e.g. NdbTransaction::execute(), there is a force parameter 
+      that overrides it forces the send to all nodes.
 
-   @note The times mentioned above are examples.  These might 
+   @note The reasons mentioned above are examples.  These might 
          change in later releases of NDB Cluster.
 */
 
+#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
+/**
+
+   For each of these "sent" transactions, there are three 
+   possible states:
+   -# Waiting to be transferred to NDB Kernel.
+   -# Has been transferred to the NDB Kernel and is currently 
+      being processed.
+   -# Has been transferred to the NDB Kernel and has 
+      finished processing.
+      Now it is waiting for a call to a poll method.  
+      (When the poll method is invoked, 
+      then the transaction callback method will be executed.)
+      
+   The poll method invoked (either Ndb::pollNdb() or Ndb::sendPollNdb())
+   will return when:
+   -# at least 'minNoOfEventsToWakeup' of the transactions
+      in the send list have transitioned to state 3 as described above, and 
+   -# all of these transactions have executed their callback methods.
+*/
+#endif
+
 /**
    @page secConcepts  NDB Cluster Concepts
 
@@ -563,14 +569,17 @@
    
    The application programmer can however hint the NDB API which 
    transaction coordinator to use
-   by providing a <em>distribution key</em> (usually the primary key).
-   By using the primary key as distribution key, 
+   by providing a <em>partition key</em> (usually the primary key).
+   By using the primary key as partition key, 
    the transaction will be placed on the node where the primary replica
    of that record resides.
    Note that this is only a hint, the system can be 
    reconfigured and then the NDB API will choose a transaction
    coordinator without using the hint.
-   For more information, see NdbDictionary::Column::setDistributionKey.
+   For more information, see NdbDictionary::Column::getPartitionKey(),
+   Ndb::startTransaction().  The application programmer can specify
+   the partition key from SQL by using the construct, 
+   "CREATE TABLE ... ENGINE=NDB PARTITION BY KEY (<attribute list>)".
 
 
    @section secRecordStruct          Record Structure 
@@ -639,7 +648,7 @@
    A simple example is an application that uses many simple updates where
    a transaction needs to update one record. 
    This record has a 32 bit primary key, 
-   which is also the distribution key. 
+   which is also the partition key. 
    Then the keyData will be the address of the integer 
    of the primary key and keyLen will be 4.
 */
diff --git a/ndb/include/ndbapi/NdbDictionary.hpp b/ndb/include/ndbapi/NdbDictionary.hpp
index 75232a3cee5..f25b3a7fbfa 100644
--- a/ndb/include/ndbapi/NdbDictionary.hpp
+++ b/ndb/include/ndbapi/NdbDictionary.hpp
@@ -286,14 +286,14 @@ public:
     int getSize() const;
 
     /** 
-     * Check if column is part of distribution key
+     * Check if column is part of partition key
      *
-     * A <em>distribution key</em> is a set of attributes which are used
+     * A <em>partition key</em> is a set of attributes which are used
      * to distribute the tuples onto the NDB nodes.
-     * The distribution key uses the NDB Cluster hashing function.
+     * The partition key uses the NDB Cluster hashing function.
      *
      * An example where this is useful is TPC-C where it might be
-     * good to use the warehouse id and district id as the distribution key. 
+     * good to use the warehouse id and district id as the partition key. 
      * This would place all data for a specific district and warehouse 
      * in the same database node.
      *
@@ -301,9 +301,12 @@ public:
      * will still be used with the hashing algorithm.
      *
      * @return  true then the column is part of 
-     *                 the distribution key.
+     *                 the partition key.
      */
-    bool getDistributionKey() const;
+    bool getPartitionKey() const;
+#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
+    inline bool getDistributionKey() const { return getPartitionKey(); };
+#endif
 
     /** @} *******************************************************************/
 
@@ -401,13 +404,17 @@ public:
     void setStripeSize(int size);
 
     /** 
-     * Set distribution key
-     * @see getDistributionKey
+     * Set partition key
+     * @see getPartitionKey
      *
      * @param  enable  If set to true, then the column will be part of 
-     *                 the distribution key.
+     *                 the partition key.
      */
-    void setDistributionKey(bool enable);
+    void setPartitionKey(bool enable);
+#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
+    inline void setDistributionKey(bool enable)
+    { setPartitionKey(enable); };
+#endif
 
     /** @} *******************************************************************/
 
diff --git a/ndb/include/ndbapi/NdbIndexScanOperation.hpp b/ndb/include/ndbapi/NdbIndexScanOperation.hpp
index 6fe4dc3df84..e1a646fa413 100644
--- a/ndb/include/ndbapi/NdbIndexScanOperation.hpp
+++ b/ndb/include/ndbapi/NdbIndexScanOperation.hpp
@@ -73,7 +73,7 @@ public:
    *
    * For equality, it is better to use BoundEQ instead of the equivalent
    * pair of BoundLE and BoundGE.  This is especially true when table
-   * distribution key is an initial part of the index key.
+   * partition key is an initial part of the index key.
    *
    * The sets of lower and upper bounds must be on initial sequences of
    * index keys.  All but possibly the last bound must be non-strict.
diff --git a/ndb/include/ndbapi/NdbOperation.hpp b/ndb/include/ndbapi/NdbOperation.hpp
index ce556fb5b7a..58ecb57ded3 100644
--- a/ndb/include/ndbapi/NdbOperation.hpp
+++ b/ndb/include/ndbapi/NdbOperation.hpp
@@ -731,7 +731,7 @@ public:
   void setAbortOption(Int8 ao) { m_abortOption = ao; }
   
   /**
-   * Set/get distribution/partition key
+   * Set/get partition key
    */
   void setPartitionId(Uint32 id);
   void setPartitionHash(Uint32 key);
diff --git a/ndb/include/ndbapi/NdbTransaction.hpp b/ndb/include/ndbapi/NdbTransaction.hpp
index 16effcaf05f..56d87d4b6c0 100644
--- a/ndb/include/ndbapi/NdbTransaction.hpp
+++ b/ndb/include/ndbapi/NdbTransaction.hpp
@@ -52,7 +52,7 @@ enum AbortOption {
   TryCommit = 0,                ///< <i>Missing explanation</i>
 #endif
   AbortOnError = 0,             ///< Abort transaction on failed operation
-  AO_IgnoreError = 2               ///< Transaction continues on failed operation
+  AO_IgnoreError = 2            ///< Transaction continues on failed operation
 };
   
 typedef AbortOption CommitType;
@@ -76,33 +76,35 @@ enum ExecType {
  * @brief Represents a transaction.
  *
  * A transaction (represented by an NdbTransaction object) 
- * belongs to an Ndb object and is typically created using 
- * Ndb::startTransaction.
+ * belongs to an Ndb object and is created using 
+ * Ndb::startTransaction().
  * A transaction consists of a list of operations 
- * (represented by NdbOperation objects). 
+ * (represented by NdbOperation, NdbScanOperation, NdbIndexOperation,
+ *  and NdbIndexScanOperation objects). 
  * Each operation access exactly one table.
  *
  * After getting the NdbTransaction object, 
- * the first step is to get (allocate) an operation given the table name. 
+ * the first step is to get (allocate) an operation given the table name using
+ * one of the methods getNdbOperation(), getNdbScanOperation(),
+ * getNdbIndexOperation(), or getNdbIndexScanOperation().
  * Then the operation is defined. 
- * Several operations can be defined in parallel on the same 
- * NdbTransaction object. 
- * When all operations are defined, the NdbTransaction::execute
- * method sends them to the NDB kernel for execution. 
+ * Several operations can be defined on the same 
+ * NdbTransaction object, they will in that case be executed in parallell.
+ * When all operations are defined, the execute()
+ * method sends them to the NDB kernel for execution.
  *
- * The NdbTransaction::execute method returns when the NDB kernel has 
+ * The execute() method returns when the NDB kernel has 
  * completed execution of all operations defined before the call to 
- * NdbTransaction::execute. 
- * All allocated operations should be properly defined 
- * before calling NdbTransaction::execute.
+ * execute(). All allocated operations should be properly defined 
+ * before calling execute().
  *
- * A call to NdbTransaction::execute uses one out of three types of execution:
+ * A call to execute() uses one out of three types of execution:
  *  -# ExecType::NoCommit  Executes operations without committing them.
  *  -# ExecType::Commit	   Executes remaining operation and commits the 
  *        	           complete transaction
  *  -# ExecType::Rollback  Rollbacks the entire transaction.
  *
- * NdbTransaction::execute is equipped with an extra error handling parameter 
+ * execute() is equipped with an extra error handling parameter. 
  * There are two alternatives:
  * -# AbortOption::AbortOnError (default).
  *    The transaction is aborted if there are any error during the
@@ -345,6 +347,8 @@ public:
 
   /**
    * Close transaction
+   *
+   * @note Equivalent to to calling Ndb::closeTransaction()
    */
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   /**
@@ -415,10 +419,7 @@ public:
   Uint64	getTransactionId();
 
   /**
-   * Returns the commit status of the transaction.
-   *
-   * @return  The commit status of the transaction, i.e. one of
-   *          { NotStarted, Started, TimeOut, Committed, Aborted, NeedAbort } 
+   * The commit status of the transaction.
    */
   enum CommitStatusType { 
     NotStarted,                   ///< Transaction not yet started
@@ -428,6 +429,11 @@ public:
     NeedAbort                     ///< <i>Missing explanation</i>
   };
 
+  /**
+   * Get the commit status of the transaction.
+   *
+   * @return  The commit status of the transaction
+   */
   CommitStatusType commitStatus();
 
   /** @} *********************************************************************/
@@ -449,7 +455,7 @@ public:
    * This method is used on the NdbTransaction object to find the
    * NdbOperation causing an error.  
    * To find more information about the
-   * actual error, use method NdbOperation::getNdbError 
+   * actual error, use method NdbOperation::getNdbError()
    * on the returned NdbOperation object.
    *
    * @return The NdbOperation causing the latest error.
diff --git a/ndb/src/ndbapi/NdbDictionary.cpp b/ndb/src/ndbapi/NdbDictionary.cpp
index fe9b0681772..b7a4419a491 100644
--- a/ndb/src/ndbapi/NdbDictionary.cpp
+++ b/ndb/src/ndbapi/NdbDictionary.cpp
@@ -177,12 +177,12 @@ NdbDictionary::Column::getPrimaryKey() const {
 }
 
 void 
-NdbDictionary::Column::setDistributionKey(bool val){
+NdbDictionary::Column::setPartitionKey(bool val){
   m_impl.m_distributionKey = val;
 }
 
 bool 
-NdbDictionary::Column::getDistributionKey() const{
+NdbDictionary::Column::getPartitionKey() const{
   return m_impl.m_distributionKey;
 }