partly rewritten the Diciotnary docs to reflect the integration with MySQL

ndb/include/ndbapi/NdbDictionary.hpp

@@ -14,18 +14,6 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-/*****************************************************************************
- * Name:          NdbDictionary.hpp
- * Include:
- * Link:
- * Author:        Jonas Oreland
- * Date:          2003-05-14
- * Version:       0.1
- * Description:   Data dictionary support
- * Documentation:
- * Adjust:  2003-05-14  Jonas Oreland   First version.
- ****************************************************************************/
-
 #ifndef NdbDictionary_H
 #define NdbDictionary_H
 
@@ -39,11 +27,15 @@ typedef struct charset_info_st CHARSET_INFO;
  * @class NdbDictionary
  * @brief Data dictionary class
  * 
- * This class supports all schema data definition and enquiry such as:
- * -# Creating tables (Dictionary::createTable) and table columns
- * -# Dropping tables (Dictionary::dropTable)
- * -# Creating secondary indexes (Dictionary::createIndex)
- * -# Dropping secondary indexes (Dictionary::dropIndex)
+ * The preferred and supported way to create tables and indexes
+ * in ndb is through the 
+ * MySQL Server (see MySQL reference Manual, section MySQL Cluster).
+ *
+ * Tables and indexes that are created directly through the 
+ * NdbDictionary class
+ * can not be viewed from the MySQL Server.
+ * 
+ * This class supports schema data enquiries such as:
  * -# Enquiries about tables
  *    (Dictionary::getTable, Table::getNoOfColumns, 
  *    Table::getPrimaryKey, and Table::getNoOfPrimaryKeys)
@@ -51,11 +43,17 @@ typedef struct charset_info_st CHARSET_INFO;
  *    (Dictionary::getIndex, Index::getNoOfColumns, 
  *    and Index::getColumn)
  *
- * NdbDictionary has several help (inner) classes:
+ * This class supports schema data definition such as:
+ * -# Creating tables (Dictionary::createTable) and table columns
+ * -# Dropping tables (Dictionary::dropTable)
+ * -# Creating secondary indexes (Dictionary::createIndex)
+ * -# Dropping secondary indexes (Dictionary::dropIndex)
+ *
+ * NdbDictionary has several help (inner) classes to support this:
  * -# NdbDictionary::Table for creating tables
  * -# NdbDictionary::Column for creating table columns
  * -# NdbDictionary::Index for creating secondary indexes
- * 
+ *
  * See @ref ndbapi_example4.cpp for details of usage.
  */
 class NdbDictionary {
@@ -195,45 +193,18 @@ public:
      * @name General 
      * @{
      */
-    /**
-     * Constructor
-     * @param   name   Name of column
-     */
-    Column(const char * name = "");
-    /**
-     * Copy constructor
-     * @param  column  Column to be copied
-     */
-    Column(const Column& column); 
-    ~Column();
     
-    /**
-     * Set name of column
-     * @param  name  Name of the column
-     */
-    void setName(const char * name);
-
     /**
      * Get name of column
      * @return  Name of the column
      */
     const char* getName() const;
 
-    /**
-     * Set whether column is nullable or not
-     */
-    void setNullable(bool);
-
     /**
      * Get if the column is nullable or not
      */
     bool getNullable() const;
     
-    /**
-     * Set that column is part of primary key
-     */
-    void setPrimaryKey(bool);
-
     /**
      * Check if column is part of primary key
      */
@@ -251,57 +222,30 @@ public:
      */
     bool equal(const Column& column) const;
 
+
     /** @} *******************************************************************/
     /** 
-     * @name Type Specifiers
+     * @name Get Type Specifiers
      * @{
      */
 
-    /**
-     * Set type of column
-     * @param  type  Type of column
-     *
-     * @note setType resets <em>all</em> column attributes
-     *       to (type dependent) defaults and should be the first
-     *       method to call.  Default type is Unsigned.
-     */
-    void setType(Type type);
-
     /**
      * Get type of column
      */
     Type getType() const;
 
-    /**
-     * Set precision of column.
-     * @note Only applicable for builtin type Decimal
-     */
-    void setPrecision(int);
-
     /**
      * Get precision of column.
      * @note Only applicable for builtin type Decimal
      */
     int getPrecision() const;
 
-    /**
-     * Set scale of column.
-     * @note Only applicable for builtin type Decimal
-     */
-    void setScale(int);
-
     /**
      * Get scale of column.
      * @note Only applicable for builtin type Decimal
      */
     int getScale() const;
 
-    /**
-     * Set length for column
-     * Array length for column or max length for variable length arrays.
-     */
-    void setLength(int length);
-
     /**
      * Get length for column
      * Array length for column or max length for variable length arrays.
@@ -309,34 +253,31 @@ public:
     int getLength() const;
 
     /**
-     * For Char or Varchar or Text, set or get MySQL CHARSET_INFO.  This
+     * For Char or Varchar or Text, get MySQL CHARSET_INFO.  This
      * specifies both character set and collation.  See get_charset()
      * etc in MySQL.  (The cs is not "const" in MySQL).
      */
-    void setCharset(CHARSET_INFO* cs);
     CHARSET_INFO* getCharset() const;
 
+
     /**
-     * For blob, set or get "inline size" i.e. number of initial bytes
+     * For blob, get "inline size" i.e. number of initial bytes
      * to store in table's blob attribute.  This part is normally in
      * main memory and can be indexed and interpreted.
      */
-    void setInlineSize(int size);
     int getInlineSize() const;
 
     /**
-     * For blob, set or get "part size" i.e. number of bytes to store in
+     * For blob, get "part size" i.e. number of bytes to store in
      * each tuple of the "blob table".  Can be set to zero to omit parts
      * and to allow only inline bytes ("tinyblob").
      */
-    void setPartSize(int size);
     int getPartSize() const;
 
     /**
      * For blob, set or get "stripe size" i.e. number of consecutive
      * <em>parts</em> to store in each node group.
      */
-    void setStripeSize(int size);
     int getStripeSize() const;
 
     /**
@@ -345,7 +286,7 @@ public:
     int getSize() const;
 
     /** 
-     * Set distribution key
+     * Check if column is part of distribution key
      *
      * A <em>distribution key</em> is a set of attributes which are used
      * to distribute the tuples onto the NDB nodes.
@@ -359,16 +300,115 @@ public:
      * Locally in the fragments the full primary key 
      * will still be used with the hashing algorithm.
      *
-     * @param  enable  If set to true, then the column will be part of 
+     * @return  true then the column is part of 
      *                 the distribution key.
      */
-    void setDistributionKey(bool enable);
+    bool getDistributionKey() const;
+
+    /** @} *******************************************************************/
+
+
+    /** 
+     * @name Column creation
+     * @{
+     *
+     * These operations should normally not be performed in an NbdApi program
+     * as results will not be visable in the MySQL Server
+     * 
+     */
 
     /**
-     * Check if column is part of distribution key
-     * @see setDistributionKey
+     * Constructor
+     * @param   name   Name of column
      */
-    bool getDistributionKey() const;
+    Column(const char * name = "");
+    /**
+     * Copy constructor
+     * @param  column  Column to be copied
+     */
+    Column(const Column& column); 
+    ~Column();
+
+    /**
+     * Set name of column
+     * @param  name  Name of the column
+     */
+    void setName(const char * name);
+
+    /**
+     * Set whether column is nullable or not
+     */
+    void setNullable(bool);
+
+    /**
+     * Set that column is part of primary key
+     */
+    void setPrimaryKey(bool);
+
+    /**
+     * Set type of column
+     * @param  type  Type of column
+     *
+     * @note setType resets <em>all</em> column attributes
+     *       to (type dependent) defaults and should be the first
+     *       method to call.  Default type is Unsigned.
+     */
+    void setType(Type type);
+
+    /**
+     * Set precision of column.
+     * @note Only applicable for builtin type Decimal
+     */
+    void setPrecision(int);
+
+    /**
+     * Set scale of column.
+     * @note Only applicable for builtin type Decimal
+     */
+    void setScale(int);
+
+    /**
+     * Set length for column
+     * Array length for column or max length for variable length arrays.
+     */
+    void setLength(int length);
+
+    /**
+     * For Char or Varchar or Text, get MySQL CHARSET_INFO.  This
+     * specifies both character set and collation.  See get_charset()
+     * etc in MySQL.  (The cs is not "const" in MySQL).
+     */
+    void setCharset(CHARSET_INFO* cs);
+
+    /**
+     * For blob, get "inline size" i.e. number of initial bytes
+     * to store in table's blob attribute.  This part is normally in
+     * main memory and can be indexed and interpreted.
+     */
+    void setInlineSize(int size);
+
+    /**
+     * For blob, get "part size" i.e. number of bytes to store in
+     * each tuple of the "blob table".  Can be set to zero to omit parts
+     * and to allow only inline bytes ("tinyblob").
+     */
+    void setPartSize(int size);
+
+    /**
+     * For blob, get "stripe size" i.e. number of consecutive
+     * <em>parts</em> to store in each node group.
+     */
+    void setStripeSize(int size);
+
+    /** 
+     * Set distribution key
+     * @see getDistributionKey
+     *
+     * @param  enable  If set to true, then the column will be part of 
+     *                 the distribution key.
+     */
+    void setDistributionKey(bool enable);
+
     /** @} *******************************************************************/
 
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
@@ -429,30 +469,6 @@ public:
      * @name General
      * @{
      */
-    /**
-     * Constructor
-     * @param  name   Name of table
-     */
-    Table(const char * name = "");
-
-    /** 
-     * Copy constructor 
-     * @param  table  Table to be copied
-     */
-    Table(const Table& table); 
-    virtual ~Table();
-    
-    /**
-     * Assignment operator, deep copy
-     * @param  table  Table to be copied
-     */
-    Table& operator=(const Table&);
-
-    /**
-     * Name of table
-     * @param  name  Name of table
-     */
-    void setName(const char * name);
 
     /**
      * Get table name
@@ -464,12 +480,6 @@ public:
      */ 
     int getTableId() const;
     
-    /**
-     * Add a column definition to a table
-     * @note creates a copy
-     */
-    void addColumn(const Column &);
-    
     /**
      * Get column definition via name.
      * @return null if none existing name
@@ -511,30 +521,13 @@ public:
      * The default value is true and indicates a normal table 
      * with full checkpointing and logging activated.
      */
-    void setLogging(bool); 
-
-    /**
-     * @see NdbDictionary::Table::setLogging.
-     */
     bool getLogging() const;
-   
-    /**
-     * Set fragmentation type
-     */
-    void setFragmentType(FragmentType);
 
     /**
      * Get fragmentation type
      */
     FragmentType getFragmentType() const;
     
-    /**
-     * Set KValue (Hash parameter.)
-     * Only allowed value is 6.
-     * Later implementations might add flexibility in this parameter.
-     */
-    void setKValue(int kValue);
-    
     /**
      * Get KValue (Hash parameter.)
      * Only allowed value is 6.
@@ -542,15 +535,6 @@ public:
      */
     int getKValue() const;
 
-    /**
-     * Set MinLoadFactor  (Hash parameter.)
-     * This value specifies the load factor when starting to shrink 
-     * the hash table. 
-     * It must be smaller than MaxLoadFactor.
-     * Both these factors are given in percentage.
-     */
-    void setMinLoadFactor(int);
-
     /**
      * Get MinLoadFactor  (Hash parameter.)
      * This value specifies the load factor when starting to shrink 
@@ -560,16 +544,6 @@ public:
      */
     int getMinLoadFactor() const;
 
-    /**
-     * Set MaxLoadFactor  (Hash parameter.)
-     * This value specifies the load factor when starting to split 
-     * the containers in the local hash tables. 
-     * 100 is the maximum which will optimize memory usage.
-     * A lower figure will store less information in each container and thus
-     * find the key faster but consume more memory.
-     */
-    void setMaxLoadFactor(int);
-
     /**
      * Get MaxLoadFactor  (Hash parameter.)
      * This value specifies the load factor when starting to split 
@@ -612,20 +586,88 @@ public:
     const void* getFrmData() const;
     Uint32 getFrmLength() const;
 
-    /**
-     * Set frm file to store with this table
-     */ 
-    void setFrm(const void* data, Uint32 len);
+    /** @} *******************************************************************/
 
-    /**
-     * Set table object type
+    /** 
+     * @name Table creation
+     * @{
+     *
+     * These methods should normally not be used in an application as
+     * the result is not accessible from the MySQL Server
+     *
      */
-    void setObjectType(Object::Type type);
 
     /**
-     * Get table object type
+     * Constructor
+     * @param  name   Name of table
      */
-    Object::Type getObjectType() const;
+    Table(const char * name = "");
+
+    /** 
+     * Copy constructor 
+     * @param  table  Table to be copied
+     */
+    Table(const Table& table); 
+    virtual ~Table();
+    
+    /**
+     * Assignment operator, deep copy
+     * @param  table  Table to be copied
+     */
+    Table& operator=(const Table&);
+
+    /**
+     * Name of table
+     * @param  name  Name of table
+     */
+    void setName(const char * name);
+
+    /**
+     * Add a column definition to a table
+     * @note creates a copy
+     */
+    void addColumn(const Column &);
+    
+    /**
+     * @see NdbDictionary::Table::getLogging.
+     */
+    void setLogging(bool); 
+   
+    /**
+     * Set fragmentation type
+     */
+    void setFragmentType(FragmentType);
+
+    /**
+     * Set KValue (Hash parameter.)
+     * Only allowed value is 6.
+     * Later implementations might add flexibility in this parameter.
+     */
+    void setKValue(int kValue);
+    
+    /**
+     * Set MinLoadFactor  (Hash parameter.)
+     * This value specifies the load factor when starting to shrink 
+     * the hash table. 
+     * It must be smaller than MaxLoadFactor.
+     * Both these factors are given in percentage.
+     */
+    void setMinLoadFactor(int);
+
+    /**
+     * Set MaxLoadFactor  (Hash parameter.)
+     * This value specifies the load factor when starting to split 
+     * the containers in the local hash tables. 
+     * 100 is the maximum which will optimize memory usage.
+     * A lower figure will store less information in each container and thus
+     * find the key faster but consume more memory.
+     */
+    void setMaxLoadFactor(int);
+
+    /**
+     * Get table object type
+     */
+    Object::Type getObjectType() const;
 
     /**
      * Get object status
@@ -637,6 +679,16 @@ public:
      */
     virtual int getObjectVersion() const;
 
+    /**
+     * Set frm file to store with this table
+     */ 
+    void setFrm(const void* data, Uint32 len);
+
+    /**
+     * Set table object type
+     */
+    void setObjectType(Object::Type type);
+
     /** @} *******************************************************************/
 
 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
@@ -661,28 +713,17 @@ public:
    */
   class Index : public Object {
   public:
-    /**
-     *  Constructor
-     *  @param  name  Name of index
+    
+    /** 
+     * @name Getting Index properties
+     * @{
      */
-    Index(const char * name = "");
-    virtual ~Index();
 
-    /**
-     * Set the name of an index
-     */
-    void setName(const char * name);
-    
     /**
      * Get the name of an index
      */
     const char * getName() const;
     
-    /**
-     * Define the name of the table to be indexed
-     */
-    void setTable(const char * name);
-
     /**
      * Get the name of the table being indexed
      */
@@ -714,6 +755,69 @@ public:
     const char * getIndexColumn(int no) const ;
 #endif
 
+    /**
+     * Represents type of index
+     */
+    enum Type {
+      Undefined = 0,          ///< Undefined object type (initial value)
+      UniqueHashIndex = 3,    ///< Unique un-ordered hash index 
+                              ///< (only one currently supported)
+      OrderedIndex = 6        ///< Non-unique ordered index
+    };
+
+    /**
+     * Get index type of the index
+     */
+    Type getType() const;
+    
+    /**
+     * Check if index is set to be stored on disk
+     *
+     * @return if true then logging id enabled
+     *
+     * @note Non-logged indexes are rebuilt at system restart.
+     * @note Ordered index does not currently support logging.
+     */
+    bool getLogging() const;
+
+    /**
+     * Get object status
+     */
+    virtual Object::Status getObjectStatus() const;
+
+    /**
+     * Get object version
+     */
+    virtual int getObjectVersion() const;
+
+    /** @} *******************************************************************/
+
+    /** 
+     * @name Index creation
+     * @{
+     *
+     * These methods should normally not be used in an application as
+     * the result will not be visible from the MySQL Server
+     *
+     */
+
+    /**
+     *  Constructor
+     *  @param  name  Name of index
+     */
+    Index(const char * name = "");
+    virtual ~Index();
+
+    /**
+     * Set the name of an index
+     */
+    void setName(const char * name);
+
+    /**
+     * Define the name of the table to be indexed
+     */
+    void setTable(const char * name);
+
     /**
      * Add a column to the index definition
      * Note that the order of columns will be in
@@ -755,59 +859,26 @@ public:
     void addIndexColumns(int noOfNames, const char ** names);
 #endif
 
-    /**
-     * Represents type of index
-     */
-    enum Type {
-      Undefined = 0,          ///< Undefined object type (initial value)
-      UniqueHashIndex = 3,    ///< Unique un-ordered hash index 
-                              ///< (only one currently supported)
-      OrderedIndex = 6        ///< Non-unique ordered index
-    };
-
     /**
      * Set index type of the index
      */
     void setType(Type type);
 
-    /**
-     * Get index type of the index
-     */
-    Type getType() const;
-    
     /**
      * Enable/Disable index storage on disk
      *
      * @param enable  If enable is set to true, then logging becomes enabled
      *
-     * @see NdbDictionary::Table::setLogging
-     *
-     * @note Non-logged indexes are rebuilt at system restart.
-     * @note Ordered index does not currently support logging.
+     * @see NdbDictionary::Index::getLogging
      */
     void setLogging(bool enable); 
 
-    /**
-     * Check if index is set to be stored on disk
-     *
-     * @see NdbDictionary::Index::setLogging
-     */
-    bool getLogging() const;
-
 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
     void setStoredIndex(bool x) { setLogging(x); }
     bool getStoredIndex() const { return getLogging(); }
 #endif
     
-    /**
-     * Get object status
-     */
-    virtual Object::Status getObjectStatus() const;
-
-    /**
-     * Get object version
-     */
-    virtual int getObjectVersion() const;
+    /** @} *******************************************************************/
 
   private:
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
@@ -941,11 +1012,73 @@ public:
     const struct NdbError & getNdbError() const;
 
     /** @} *******************************************************************/
+
     /** 
-     * @name Tables
+     * @name Retrieving references to Tables and Indexes
      * @{
      */
 
+    /**
+     * Get table with given name, NULL if undefined
+     * @param name   Name of table to get
+     * @return table if successful otherwise NULL.
+     */
+    const Table * getTable(const char * name);
+
+    /**
+     * Get index with given name, NULL if undefined
+     * @param indexName  Name of index to get.
+     * @param tableName  Name of table that index belongs to.
+     * @return  index if successful, otherwise 0.
+     */
+    const Index * getIndex(const char * indexName,
+			   const char * tableName);
+
+    /**
+     * Fetch list of indexes of given table.
+     * @param list  Reference to list where to store the listed indexes
+     * @param tableName  Name of table that index belongs to.
+     * @return  0 if successful, otherwise -1
+     */
+    int listIndexes(List & list, const char * tableName);
+
+    /** @} *******************************************************************/
+    /** 
+     * @name Events
+     * @{
+     */
+    
+    /**
+     * Create event given defined Event instance
+     * @param Event to create
+     * @return 0 if successful otherwise -1.
+     */
+    int createEvent(const Event &);
+
+    /**
+     * Drop event with given name
+     * @param eventName  Name of event to drop.
+     * @return 0 if successful otherwise -1.
+     */
+    int dropEvent(const char * eventName);
+    
+    /**
+     * Get event with given name.
+     * @param eventName  Name of event to get.
+     * @return an Event if successful, otherwise NULL.
+     */
+    const Event * getEvent(const char * eventName);
+
+    /** @} *******************************************************************/
+
+    /** 
+     * @name Table creation
+     * @{
+     *
+     * These methods should normally not be used in an application as
+     * the result will not be visible from the MySQL Server
+     */
+
     /**
      * Create defined table given defined Table instance
      * @param Table Table to create
@@ -976,13 +1109,6 @@ public:
      */
     int alterTable(const Table &);
 
-    /**
-     * Get table with given name, NULL if undefined
-     * @param name   Name of table to get
-     * @return table if successful otherwise NULL.
-     */
-    const Table * getTable(const char * name);
-
     /**
      * Get table with given name for alteration.
      * @param name   Name of table to alter
@@ -1007,8 +1133,12 @@ public:
     
     /** @} *******************************************************************/
     /** 
-     * @name Indexes
+     * @name Index creation
      * @{
+     *
+     * These methods should normally not be used in an application as
+     * the result will not be visible from the MySQL Server
+     *
      */
     
     /**
@@ -1027,15 +1157,6 @@ public:
     int dropIndex(const char * indexName,
 		  const char * tableName);
     
-    /**
-     * Get index with given name, NULL if undefined
-     * @param indexName  Name of index to get.
-     * @param tableName  Name of table that index belongs to.
-     * @return  index if successful, otherwise 0.
-     */
-    const Index * getIndex(const char * indexName,
-			   const char * tableName);
-
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
     /**
      * Invalidate cached index object
@@ -1044,43 +1165,8 @@ public:
                          const char * tableName);
 #endif
 
-    /**
-     * Fetch list of indexes of given table.
-     * @param list  Reference to list where to store the listed indexes
-     * @param tableName  Name of table that index belongs to.
-     * @return  0 if successful, otherwise -1
-     */
-    int listIndexes(List & list, const char * tableName);
-
     /** @} *******************************************************************/
-    /** 
-     * @name Events
-     * @{
-     */
-    
-    /**
-     * Create event given defined Event instance
-     * @param Event to create
-     * @return 0 if successful otherwise -1.
-     */
-    int createEvent(const Event &);
-
-    /**
-     * Drop event with given name
-     * @param eventName  Name of event to drop.
-     * @return 0 if successful otherwise -1.
-     */
-    int dropEvent(const char * eventName);
-    
-    /**
-     * Get event with given name.
-     * @param eventName  Name of event to get.
-     * @return an Event if successful, otherwise NULL.
-     */
-    const Event * getEvent(const char * eventName);
 
-    /** @} *******************************************************************/
-    
   protected:
     Dictionary(Ndb & ndb);
     ~Dictionary();