Author: jstephens
Date: 2006-05-23 16:10:55 +0200 (Tue, 23 May 2006)
New Revision: 2166
Log:
Basic class format with Ndb class description, UML diagram, slots for examples.
Simplified some more section identifiers.
Added:
trunk/ndbapi/images/
trunk/ndbapi/images/Ndb-class.png
Modified:
trunk/ndbapi/errors.xml
trunk/ndbapi/ndb-classes.xml
trunk/ndbapi/overview.xml
Modified: trunk/ndbapi/errors.xml
===================================================================
--- trunk/ndbapi/errors.xml 2006-05-23 02:27:27 UTC (rev 2165)
+++ trunk/ndbapi/errors.xml 2006-05-23 14:10:55 UTC (rev 2166)
@@ -18,7 +18,7 @@
</abstract>
- <section id="errors-ndberror-struct">
+ <section id="struct-ndberror">
<title>The <literal>NdbError</literal> Structure</title>
@@ -33,7 +33,7 @@
</section>
- <section id="errors-ndb-error-messages">
+ <section id="ndb-error-messages">
<title>NDB Error Messages</title>
Added: trunk/ndbapi/images/Ndb-class.png
===================================================================
(Binary files differ)
Property changes on: trunk/ndbapi/images/Ndb-class.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: trunk/ndbapi/ndb-classes.xml
===================================================================
--- trunk/ndbapi/ndb-classes.xml 2006-05-23 02:27:27 UTC (rev 2165)
+++ trunk/ndbapi/ndb-classes.xml 2006-05-23 14:10:55 UTC (rev 2166)
@@ -22,21 +22,20 @@
<listitem>
<para>
- Description of the class' purpose in the API
+ Description of the purpose of the class in the API.
</para>
</listitem>
<listitem>
<para>
Listing of all members, including descriptions of all method
- parameters and enumerated class constants
+ parameters and enumerated class constants.
</para>
</listitem>
<listitem>
<para>
- One or more brief examples, showing the use of the most
- important class members
+ Brief examples, showing the use of class members.
</para>
</listitem>
@@ -57,7 +56,7 @@
<abstract>
<para>
- This class represents the NDB kernel; it is the main class of
+ This class represents the NDB kernel; it is the primary class of
the NDB API.
</para>
@@ -154,7 +153,7 @@
</row>
<row>
<entry><literal>closeTransaction()</literal></entry>
- <entry>Closes a transaction. (See <xref linkend="class-ndbtransaction"/>.)</entry>
+ <entry>Closes a transaction.</entry>
</row>
<row>
<entry><literal>createEventOperation()</literal></entry>
@@ -171,15 +170,32 @@
</row>
<row>
<entry><literal>getNdbError()</literal></entry>
- <entry>Retrieves an error. (See <xref linkend="errors-ndberror-struct"/>.)</entry>
+ <entry>Retrieves an error. (See <xref linkend="struct-ndberror"/>.)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
+
+ <para>
+ This UML diagram provides the signatures of all the available
+ methods of the <literal>Ndb</literal> class:
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ndb-class.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase lang="en">
+ UML Diagram showing methods and signatures of the
+ <literal>Ndb</literal> class.
+ </phrase>
+ </textobject>
+ </mediaobject>
<para>
- The sections that follow provide descriptions, signatures, and
- examples of use for each of these methods.
+ The sections that follow provide more detailed descriptions,
+ signatures, and examples of use for each of these methods.
</para>
<section id="class-ndb-constructor">
@@ -211,31 +227,70 @@
Ndb
(
Ndb_cluster_connection *<replaceable>ndb_cluster_connection</replaceable>,
- const char *<replaceable>catalogName</replaceable>="",
- const char *<replaceable>schemaName</replaceable>="def"
+ const char *<replaceable>catalogName</replaceable> = "",
+ const char *<replaceable>schemaName</replaceable> = "def"
)
</programlisting>
</para>
</formalpara>
- <para>
- The <literal>Ndb</literal> class constructor can take up to 3
- arguments, of which only the first — an instance of
- <literal>Ndb_cluster_connection</literal>, which represents a
- cluster connectstring — is required. (See
- <xref linkend="class-ndb-cluster-connection"/>.) In addition,
- you may specify either a catalogue name
- (<replaceable>catalogName</replaceable>), a schema name
- (<replaceable>schemaName</replaceable>), or both. The
- <replaceable>catalogName</replaceable> provides a namespace for
- the tables and indexes created in any connection from the
- <literal>Ndb</literal> object. The
- <replaceable>schemaName</replaceable> provides an additional
- namespace for the tables and indexes created in a given catalog.
- </para>
-
<formalpara>
+ <title>Parameters</title>
+
+ <para>
+ The <literal>Ndb</literal> class constructor can take up to 3
+ parameters, of which only the first is required:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <replaceable>ndb_cluster_connection</replaceable> is an
+ instance of <literal>Ndb_cluster_connection</literal>,
+ which represents a cluster connectstring. (See
+ <xref linkend="class-ndb-cluster-connection"/>.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <replaceable>catalogName</replaceable> is an optional
+ parameter providing a namespace for the tables and
+ indexes created in any connection from the
+ <literal>Ndb</literal> object.
+ </para>
+
+ <para>
+ The default value for this parameter is an empty string.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The optional <replaceable>schemaName</replaceable>
+ provides an additional namespace for the tables and
+ indexes created in a given catalog.
+ </para>
+
+ <para>
+ The default value for this parameter is the string
+ <quote>def</quote>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ An <literal>Ndb</literal> object.
+ </para>
+ </formalpara>
+
+
+ <formalpara>
<title>Example</title>
@@ -273,24 +328,77 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method is used to initialise an <literal>Ndb</literal>
+ object.
+ </para>
</formalpara>
-
+
<formalpara>
<title>Signature</title>
<para>
<programlisting>
-
+int init
+ (
+ int <replaceable>maxNoOfTransactions</replaceable> = 4
+ )
</programlisting>
</para>
</formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ The <literal>init()</literal> method takes a single parameter
+ <replaceable>maxNoOfTransactions</replaceable> of type
+ integer. This parameter specifies the maximum number of
+ parallel <literal>NdbTransaction</literal> objects that can be
+ handled by this instance of <literal>Ndb</literal>. The
+ maximum permitted value for
+ <replaceable>maxNoOfTransactions</replaceable> is 1024; if not
+ specified, it defaults to 4.
+ </para>
+ </formalpara>
+
+ <note>
+ <para>
+ Each scan or index operation uses an extra
+ <literal>NdbTransaction</literal> object. See
+ <xref linkend="class-ndbtransaction"/>.
+ </para>
+ </note>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ This method returns an <literal>int</literal>, which can be
+ either of two values:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">0</emphasis>: indicates that the
+ <literal>Ndb</literal> object was initialised
+ successfuly.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">-1</emphasis>: indicates failure.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </para>
+ </formalpara>
- <para></para>
-
<formalpara>
<title>Example</title>
@@ -316,7 +424,10 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method can be used to obtain the name of the current
+ database.
+ </para>
</formalpara>
@@ -326,14 +437,31 @@
<para>
<programlisting>
-
+const char* getDatabaseName
+ (
+ void
+ )
</programlisting>
</para>
</formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ None.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ The name of the current database.
+ </para>
+ </formalpara>
- <para></para>
-
<formalpara>
<title>Example</title>
@@ -360,7 +488,9 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method is used to set the name of the current database.
+ </para>
</formalpara>
@@ -370,14 +500,33 @@
<para>
<programlisting>
-
+void setDatabaseName
+ (
+ const char *<replaceable>databaseName</replaceable>
+ )
</programlisting>
</para>
</formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ <literal>setDatabaseName()</literal> takes a single, required
+ parameter, the name of the new database to be set as the
+ current database.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ N/A.
+ </para>
+ </formalpara>
- <para></para>
-
<formalpara>
<title>Example</title>
@@ -404,7 +553,10 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method can be used to obatin the current database schema
+ name.
+ </para>
</formalpara>
@@ -414,14 +566,31 @@
<para>
<programlisting>
-
+const char* getDatabaseSchemaName
+ (
+ void
+ )
</programlisting>
</para>
</formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ None.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ The name of the current database schema.
+ </para>
+ </formalpara>
- <para></para>
-
<formalpara>
<title>Example</title>
@@ -448,7 +617,10 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method allows you to set the name of the current database
+ schema.
+ </para>
</formalpara>
@@ -458,14 +630,31 @@
<para>
<programlisting>
-
+void setDatabaseSchemaName
+ (
+ const char *<replaceable>databaseSchemaName</replaceable>
+ )
</programlisting>
</para>
</formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ The name of the database schema.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ N/A.
+ </para>
+ </formalpara>
- <para></para>
-
<formalpara>
<title>Example</title>
@@ -492,9 +681,30 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method is used to begin a new transaction.
+ </para>
</formalpara>
+
+ <important>
+ <para>
+ When the transaction is completed it must be closed using
+ <literal>NdbTransaction::close()</literal> or
+ <literal>Ndb::closeTransaction()</literal>. This must be done
+ regardless of the transaction's final outcome, even if fials
+ due to an an error.
+ </para>
+
+ <para>
+ See <xref linkend="class-ndb-closetransaction"/>, and
+ <xref linkend="class-ndbtransaction"/>.
+ <remark role="todo">
+ [js] Update the previous link to point directly to the
+ method once the section for it has been created.
+ </remark>
+ </para>
+ </important>
<formalpara>
@@ -502,14 +712,62 @@
<para>
<programlisting>
-
+NdbTransaction* startTransaction
+ (
+ const NdbDictionary::Table *<replaceable>table</replaceable> = 0,
+ const char *<replaceable>keyData</replaceable> = 0,
+ Uint32 *<replaceable>keyLen</replaceable> = 0
+ )
</programlisting>
</para>
</formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ This method takes three parameters, as follows:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <replaceable>table</replaceable>: A pointer to a
+ <literal>Table</literal> object. (See
+ <xref linkend="class-table"/>.) This is used to
+ determine on which node the Transaction Co-Ordinator
+ should run.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <replaceable>keyData</replaceable>: A pointer to a
+ partition key corresponding to
+ <replaceable>table</replaceable>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <replaceable>keyLen</replaceable>: The length of the
+ partition key, expressed in bytes.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ An <literal>NdbTransaction</literal> object. See
+ <xref linkend="class-ndbtransaction"/>.
+ </para>
+ </formalpara>
- <para></para>
-
<formalpara>
<title>Example</title>
@@ -536,7 +794,18 @@
<title>Description</title>
- <para></para>
+ <para>
+ This is one of two NDB API methods provided for closing a
+ transaction (the other being
+ <literal>NdbTransaction::close()</literal> — see
+ <xref linkend="class-ndbtransaction"/>). You must call one of
+ these two methods to close the transaction once it has been
+ completed, whether or not the transaction succeeded.
+ <remark role="todo">
+ [js] Update the previous link to point directly to the
+ method once the section for it has been created.
+ </remark>
+ </para>
</formalpara>
@@ -546,14 +815,32 @@
<para>
<programlisting>
-
+void closeTransaction
+ (
+ NdbTransaction *<replaceable>transaction</replaceable>
+ )
</programlisting>
</para>
</formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ This method takes a single argument, a pointer to the
+ <literal>NdbTransaction</literal> to be closed.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ N/A.
+ </para>
+ </formalpara>
- <para></para>
-
<formalpara>
<title>Example</title>
@@ -580,7 +867,9 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method creates a subscription to a datbase event.
+ </para>
</formalpara>
@@ -590,14 +879,35 @@
<para>
<programlisting>
-
+NdbEventOperation* createEventOperation
+ (
+ const char *<replaceable>eventName</replaceable>
+ )
</programlisting>
</para>
</formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ This method takes a single argument, the unique
+ <replaceable>eventName</replaceable> identifying the event to
+ which you wish to subscribe.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ A pointer to an <literal>NdbEventOperation</literal> object
+ (or <literal>NULL</literal>, in the event of failure). See
+ <xref linkend="class-ndbeventoperation"/>.
+ </para>
+ </formalpara>
- <para></para>
-
<formalpara>
<title>Example</title>
@@ -624,7 +934,10 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method drops a subscription to a database event
+ represented by an <literal>NdbEventOperation</literal> object.
+ </para>
</formalpara>
@@ -634,14 +947,33 @@
<para>
<programlisting>
-
+int dropEventOperation
+ (
+ NdbEventOperation *<replaceable>eventOp</replaceable>
+ )
</programlisting>
</para>
</formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ This method requires a single input parameter, a pointer to an
+ instance of <literal>NdbEventOperation</literal>.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ <emphasis role="bold">0</emphasis> on success; any other
+ result indicates failure.
+ </para>
+ </formalpara>
- <para></para>
-
<formalpara>
<title>Example</title>
@@ -668,7 +1000,13 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method waits for an event to occur, and returns as soon
+ as an event is detected in any existing subscription
+ belonging to the <literal>Ndb</literal> object for which the
+ method is invoked. It is used to determine whether any events
+ are available in the subscription queue.
+ </para>
</formalpara>
@@ -678,21 +1016,154 @@
<para>
<programlisting>
+int pollEvents
+ (
+ int <replaceable>maxTimeToWait</replaceable>,
+ Uint64 *<replaceable>latestGCI</replaceable> = 0
+ )
+</programlisting>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ This method takes two parameters, as shown here:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ The maxmimum time to wait, in milliseconds, before
+ <quote>giving up</quote> and reporting that no events
+ were available (that is, before the methyod
+ automatically returns
+ <emphasis role="bold">0</emphasis>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The index of the most recent global checkpoint.
+ Normally, this may safely be permitted to assume its
+ default value, which is
+ <emphasis role="bold">0</emphasis>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ <literal>pollEvents()</literal> returns a value of type
+ <literal>int</literal>, which may be interpreted as follows:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">> 0</emphasis>: There are
+ events avaialable in the queue.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">0</emphasis>: There are no events
+ available.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis role="bold">< 0</emphasis>: Indicates
+ failure (possible error).
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </para>
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+ This example shows how the <literal>pollEvents()</literal>
+ method is used to determine that there are database events
+ waiting in a given subscription queue:
+
+<programlisting>
+[<emphasis>To be written...</emphasis>]
</programlisting>
</para>
</formalpara>
- <para></para>
+ </section>
+ <section id="class-ndb-nextevent">
+
+ <title><literal>Ndb::nextEvent()</literal></title>
+
<formalpara>
+ <title>Description</title>
+
+ <para>
+ Returns the next event operation having data from a
+ subscription queue.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+NdbEventOperation *nextEvent
+ (
+ void
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ None.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ This method returns an <literal>NdbEventOperation</literal>
+ object representing the next event in a subscription queue, if
+ there is such an event. If there is no event in the queue, it
+ returns <literal>NULL</literal> instead. (See
+ <xref linkend="class-ndbeventoperation"/>.)
+ </para>
+ </formalpara>
+
+ <formalpara>
+
<title>Example</title>
<para>
- This example shows how the <literal>pollEvents()</literal>
- method is used to wait until a database event occurs:
+ This example shows how to use <literal>nextEvent()</literal>
+ to obtain the next event in a series of database events:
<programlisting>
[<emphasis>To be written...</emphasis>]
@@ -711,7 +1182,12 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method provides you with two different ways to obtain an
+ <literal>NdbError</literal> object representing an error
+ condition. For more detailed information about error handling
+ in the NDB API, see <xref linkend="errors"/>.
+ </para>
</formalpara>
@@ -720,26 +1196,73 @@
<title>Signature</title>
<para>
+ The <literal>getNdbError()</literal> method actually has two
+ variants. The first of these sinply gets the most recent error
+ to have occured:
<programlisting>
-
+const NdbError &getNdbError
+ (
+ void
+ )
</programlisting>
+ The second variant returns the error corresponding to a given
+ error code:
+<programlisting>
+const NdbError &getNdbError
+ (
+ int <replaceable>errorCode</replaceable>
+ )
+</programlisting>
+ Regardless of which version of the method is used, the
+ <literal>NdbError</literal> object returned persists until the
+ next NDB API method is invoked.
</para>
</formalpara>
+
+ <formalpara>
+ <title>Parameters</title>
+
+ <para>
+ To obtain the most recent error, simply call
+ <literal>getNdbError()</literal> without any parameters. To
+ obtain the error matching a specific
+ <replaceable>errorCode</replaceable>, invoke the method
+ passing the code (an <literal>int</literal>) to it as a
+ parameter. For a listing of NDB API error codes and
+ corresponding error messages, see
+ <xref linkend="ndb-error-messages"/>.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Returns</title>
+
+ <para>
+ An <literal>NdbError</literal> object containing information
+ about the error, including its type and, where applicable,
+ contextual information as to how the error arose. See
+ <xref linkend="struct-ndberror"/>, for details.
+ </para>
+ </formalpara>
- <para></para>
-
<formalpara>
<title>Example</title>
<para>
This example shows how to use <literal>getNdbError()</literal>
- to retrieve one or more NDPAPI errors:
+ to retrieve the most recent NDB API error:
<programlisting>
[<emphasis>To be written...</emphasis>]
</programlisting>
+ The next example shows how to retrieve an
+ <literal>NdbError</literal> object using
+ <literal>getNdbError()</literal>, given a numeric error code:
+<programlisting>
+[<emphasis>To be written...</emphasis>]
+</programlisting>
</para>
</formalpara>
Modified: trunk/ndbapi/overview.xml
===================================================================
--- trunk/ndbapi/overview.xml 2006-05-23 02:27:27 UTC (rev 2165)
+++ trunk/ndbapi/overview.xml 2006-05-23 14:10:55 UTC (rev 2166)
@@ -87,8 +87,8 @@
transactions, and operations. These classes and their subclasses
are listed in <xref linkend="ndb-classes"/>. Error conditions in
the NDB API are handled using <literal>NdbError</literal>, a
- structure which is described in
- <xref linkend="errors-ndberror-struct"/>.
+ structure which is described in
+ <xref linkend="struct-ndberror"/>.
</para>
</section>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2166 - in trunk/ndbapi: . images | jon | 23 May |
