fireruby 0.2.2-i586-linux

data/lib/src.rb

@@ -0,0 +1,879 @@
+#
+# This file is a stand-in that allows for the generation of rdoc documentation
+# for the FireRuby extension for the Ruby programming language. The extension
+# is coded in C and documented with Doxygen comments, so this file is used to
+# generate the native Ruby documentation instead.
+#
+
+#
+# This module contains all of the classes and definitions relating to the
+# FireRuby extension for the Ruby language.
+#
+module FireRuby
+   #
+   # This class provides the exception type used by the FireRuby library.
+   #
+   class FireRubyException
+      #
+      # This is the constructor for the FireRubyError class.
+      #
+      # ==== Parameters
+      # message::  A string containing the error message for the object.
+      #
+      def initialize(message)
+      end
+      
+      
+      #
+      #  This is the accessor for the error message attribute
+      #
+      def message
+      end
+      
+      
+      #
+      # This is the accessor for the SQL code attribute.
+      #
+      def sql_code
+      end
+      
+      
+      #
+      # This is the accessor for the database code attribute.
+      #
+      def db_code
+      end
+      
+      
+      #
+      # This function generates a simple description string for a FireRubyError
+      # object.
+      #
+      def to_s
+      end
+   end
+   
+   
+   #
+   # This class represents an existing database that can be connected to.
+   #
+   class Database
+      #
+      # This is the constructor for the Database class.
+      #
+      # ==== Parameters
+      # file::      A string containing the database file specifier. This can
+      #             include details for a remote server if needed.
+      #
+      def initialize(file)
+      end
+      
+      
+      #
+      # This is the accessor for the database file specification attribute.
+      #
+      def file
+      end
+      
+      
+      #
+      # This method attempts to establish a connection to a database. If
+      # successful then a Connection instance is returned. If a block is
+      # provided to the method then the connection is closed after the
+      # block completes. If a block is specified the connection is provided
+      # as a parameter to the block.
+      #
+      # ==== Parameters
+      # user::      The user name to be used in making the connection.
+      # password::  The password to be used in making the connection.
+      #
+      # ==== Exceptions
+      # Exception::  Thrown whenever a problem occurs connecting with the
+      #              database.
+      #
+      def connect(user, password)
+         yield(connection)
+      end
+      
+      
+      #
+      # This method attempts to drop the database referred to by the details
+      # in a Database object.
+      #
+      # ==== Parameters
+      # user::      The user name to be used in dropping the database.
+      # password::  The password to be used in dropping the database.
+      #
+      # ==== Exceptions
+      # FireRubyError::  Thrown whenever a problem occurs dropping the database
+      #                  instance.
+      #
+      def drop(user, password)
+      end
+      
+      
+      #
+      # This method can be used to programmatically created a database file.
+      # If successful this method returns a Database object.
+      #
+      # ==== Parameters
+      # file::      A string containing the path and name of the database file
+      #             to be created.
+      # user::      A string containing the user name that will be used in
+      #             creating the file.
+      # password::  A string containing the user password that will be used in
+      #             creating the file.
+      # size::      The page size setting to be used with the new database file.
+      #             This should be 1024, 2048, 4096 or 8192.
+      # set::       The name of the default character set to be assigned to the
+      #             new database file.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever an invalid parameter is specified or a
+      #              problem occurs creating the database file.
+      #
+      def Database.create(file, user, password, size, set)
+      end
+   end
+   
+   
+   #
+   # This class represents a connection with a Firebird database.
+   #
+   class Connection
+      #
+      # This is the constructor for the Connection class.
+      #
+      # ==== Parameters
+      # database::  A reference to the Database object to be connected to.
+      # user::      A reference to the user name to be used in making the
+      #             database connection.
+      # password::  A reference to the user password to be used in making the
+      #             connection.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever an invalid database is specified to
+      #              the method or an issue occurs establishing the database
+      #              connection.
+      #
+      def initialize(database, user, password)
+      end
+      
+      
+      #
+      # This method is used to determine whether a Connection object represents
+      # an active database connection.
+      #
+      def open?
+      end
+      
+      
+      #
+      # This method is used to determine whether a Connection object represents
+      # an inactive database connection.
+      #
+      def closed?
+      end
+      
+      
+      #
+      # This method detaches a Connection object from a database. The object
+      # may not be used for database functionality following a successful call
+      # to this method. The close method will fail if there are outstanding
+      # transactions for a connection.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever the connection has at least one open
+      #              transaction or an error occurs closing the connection.
+      #
+      def close
+      end
+      
+      
+      #
+      # This is the accessor method for the database attribute.
+      #
+      def database
+      end
+      
+      
+      #
+      # This method retrieves the user name that was used in creating a
+      # Connection object.
+      #
+      def user
+      end
+      
+      
+      #
+      # This method generates a simple descriptive string for a Connection
+      # object.
+      #
+      def to_s
+      end
+      
+      
+      #
+      # This method starts a new transaction against a connection. A successful
+      # call to this method returns a Transaction object. The transaction that
+      # is started relates to the Connection it was called upon only. To start
+      # a transaction that covers multiple connections use the Transaction
+      # class. This method accepts a block, taking a single parameter which
+      # will be the transaction created. This transaction is committed if the
+      # block completes normally or rolls back if an exception is thrown from
+      # the block.
+      #
+      # ==== Exceptions
+      # Exception::  Thrown whenever a problem occurs starting the transaction.
+      #
+      def start_transaction
+         yield transaction
+      end
+      
+      
+      #
+      # This function executes a SQL statement against a connection. If the
+      # statement represented a SQL query then a result set is returned. If
+      # the statement wasn't a query then nil is returned. The method also
+      # accepts a block that takes a single parameter. This block will be
+      # executed once for each row in any result set generated.
+      #
+      # ==== Parameters
+      # sql::          The SQL statement to be executed.
+      # transaction::  The transaction to execute the SQL statement within.
+      #
+      # ==== Exceptions
+      # Exception::  Generated if an error occurs executing the SQL statement.
+      #
+      def execute(sql, transaction)
+         yield(row)
+      end
+      
+      
+      #
+      # This function executes a SQL statement against a connection. This 
+      # differs from the execute method in that an anonymous transaction is
+      # used in executing the statement. The output from this method is the
+      # same as for the execute method. The method also accepts a block that
+      # takes a single parameter. This block will be executed once for each
+      # row in any result set generated.
+      #
+      # ==== Parameters
+      # sql::  The SQL statement to be executed.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever a problem occurs executing the SQL
+      #              statement.
+      #
+      def execute_immediate(sql)
+         yield(row)
+      end
+   end
+   
+   
+   #
+   # This class represents a Firebird database transaction. There may be
+   # multiple transaction outstanding against a connection at any one time.
+   #
+   class Transaction
+      TPB_VERSION_1          = 1
+      TPB_VERSION_3          = 3
+      TPB_CONSISTENCY        = 1
+      TPB_CONCURRENCY        = 2
+      TPB_SHARED             = 3
+      TPB_PROTECTED          = 4
+      TPB_EXCLUSIVE          = 5
+      TPB_WAIT               = 6
+      TPB_NO_WAIT            = 7
+      TPB_READ               = 8
+      TPB_WRITE              = 9
+      TPB_LOCK_READ          = 10
+      TPB_LOCK_WRITE         = 11
+      TPB_VERB_TIME          = 12
+      TPB_COMMIT_TIME        = 13
+      TPB_IGNORE_LIMBO       = 14
+      TPB_READ_COMMITTED     = 15
+      TPB_AUTO_COMMIT        = 16
+      TPB_REC_VERSION        = 17
+      TPB_NO_REC_VERSION     = 18
+      TPB_RESTART_REQUESTS   = 19
+      # Transaction parameter buffer value constants.
+      TPB_NO_AUTO_UNDO       = 20
+
+      
+      #
+      # This is the constructor for the Transaction class.
+      #
+      # ==== Parameters
+      # connections::  Either a single instance of the Connection class or
+      #                an array of Connection instances to specify a
+      #                multi-database transaction.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever the method is passed an invalid
+      #              parameter or a problem occurs creating the transaction.
+      #
+      def initialize(connections)
+      end
+      
+      
+      #
+      # This method is used to determine whether a Transaction object is still
+      # valid for use (i.e. commit or rollback has not been called for the
+      # Transaction).
+      #
+      def active?
+      end
+      
+      
+      #
+      # This is the accessor for the connections attribute. This method returns
+      # an array of the connections that the transaction applies to.
+      #
+      def connections
+      end
+      
+      
+      #
+      # This method is used to determine whether a given Transaction applies to
+      # a specified Connection.
+      #
+      # ==== Parameters
+      # connection::  A reference to the Connection object to perform the test
+      #               for.
+      #
+      def for_connection?(connection)
+      end
+
+      
+      #
+      # This method commits the details outstanding against a Transaction
+      # object. The Transaction object may not be reused after a successful
+      # call to this method.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever a problem occurs committing the details
+      #              of the transaction.
+      #
+      def commit
+      end
+
+      
+      #
+      # This method rolls back the details outstanding against a Transaction
+      # object. The Transaction object may not be reused after a successful
+      # call to this method.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever a problem occurs rolling back the
+      #              details of the transaction.
+      #
+      def rollback
+      end
+      
+      
+      #
+      # This method executes a SQL statement using a Transaction object. This
+      # method will only work whenever a Transaction object applies to a
+      # single Connection as it would otherwise be impossible to determine
+      # which connection to execute against. If the statement executed was a
+      # SQL query then the method returns a ResultSet object, otherwise it
+      # returns nil. The method also accepts a block that takes a single
+      # parameter. If the SQL statement was a query the block will be invoked
+      # and passed each row retrieved.
+      #
+      # ==== Parameters
+      # sql::  A string containing the SQL statement to be executed.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever the Transaction object represents more
+      #              than one connection or a problem occurs executing the SQL
+      #              statement.
+      #
+      def execute(sql)
+         yield(row)
+      end
+      
+      
+      #
+      # This method allows for the creation of a Transaction object with
+      # non-standard settings.
+      #
+      # ==== Parameters
+      # connections::  Either a single Connection object or an array of
+      #                Connection objects that the new Transaction will
+      #                be associated with.
+      # parameters::   An array of the parameters to be used in creating
+      #                the new constants. Populate this from the TPB
+      #                constants defined within the class.
+      #
+      # ==== Exceptions
+      # FireRubyError::  Generated whenever a problem occurs creating the
+      #                  transaction.
+      #
+      def Transaction.create(connections, parameters)
+      end
+   end
+   
+   
+   #
+   # This class  represents a prepared SQL statement that may be executed more
+   # than once.
+   #
+   class Statement
+      #
+      # This is the constructor for the Statement class.
+      #
+      # ==== Parameters
+      # connection::   The Connection object that the SQL statement will be
+      #                executed through.
+      # transaction::  The Transaction object that the SQL statement will be
+      #                executed under.
+      # sql::          The SQL statement to be prepared for execution.
+      # dialect::      The Firebird dialect to be used in preparing the SQL
+      #                statement.
+      #
+      def initialize(connection, transaction, sql, dialect)
+      end
+      
+      
+      #
+      # This is the accessor for the connection attribute.
+      #
+      def connection
+      end
+      
+      
+      #
+      # This is the accessor for the transaction attribute.
+      #
+      def transaction
+      end
+      
+      
+      #
+      # This is the accessor for the SQL statement attribute.
+      #
+      def sql
+      end
+      
+      
+      #
+      # This is the accessor for the dialect attribute.
+      #
+      def dialect
+      end
+      
+      
+      #
+      # This method is used to determine whether a Statement object represents
+      # a SQL query.
+      #
+      def is_query?
+      end
+      
+      
+      #
+      # This method fetches a count of the number of dynamic parameters for
+      # a statement object (i.e. the number of parameters that must be provided
+      # with values before the SQL statement can be executed).
+      #
+      def parameter_count
+      end
+      
+      
+      #
+      # This method executes the SQL statement within a Statement object. This
+      # method returns a ResultSet object if the statement executed was a SQL
+      # query, otherwise it returns nil. This method accepts a block taking a
+      # single parameter. If this block is provided and the statement is a
+      # query then the rows returned by the query will be passed, one at a
+      # time, to the block.
+      #
+      # ==== Exception
+      # Exception::  Generated if the Statement object actual requires some
+      #              parameters or a problem occurs executing the SQL statement.
+      #
+      def execute
+         yield row
+      end
+      
+      
+      #
+      # This method executes the SQL statement within a Statement object and
+      # passes it a set of parameters. Parameterized statements use question
+      # marks as place holders for values that may change between calls to
+      # execute the statement. This method returns a ResultSet object if the
+      # statement executed was a SQL query, otherwise it returns nil. This
+      # method accepts a block taking a single parameter. If this block is
+      # provided and the statement is a query then the rows returned by the
+      # query will be passed, one at a time, to the block.
+      #
+      # ==== Parameters
+      # parameters::  An array of the parameters for the statement. An effort
+      #               will be made to convert the values passed in to the
+      #               appropriate types but no guarantees are made (especially
+      #               in the case of text fields, which will simply use to_s
+      #               if the object passed is not a String).
+      #
+      # ==== Exception
+      # Exception::  Generated whenever a problem occurs translating one of the
+      #              input parameters or executing the SQL statement.
+      #
+      def execute_for(parameters)
+         yield row
+      end
+      
+      
+      #
+      # This method releases the database resources associated with a Statement
+      # object and should be explicitly called when a Statement object is of
+      # no further use.
+      #
+      # ==== Exceptions
+      # FireRubyError::  Generated whenever a problem occurs closing the
+      #                  statement object.
+      #
+      def close
+      end
+   end
+   
+   
+   #
+   # This class represents the results of a SQL query executed against a
+   # database.
+   #
+   class ResultSet
+      #
+      # This is the constructor for the ResultSet object.
+      #
+      # ==== Parameters
+      # statement::  A reference to the Statement object that the ResultSet
+      #              will be based on.
+      #
+      def initialize(statement)
+      end
+      
+      
+      #
+      # This is the accessor for the statement attribute.
+      #
+      def statement
+      end
+      
+      
+      #
+      # This method fetches a count of the number of columns in a row of data
+      # that the ResultSet can fetch.
+      #
+      def column_count
+      end
+      
+      
+      #
+      # This method fetches the name associated with a specified column for a
+      # ResultSet object.
+      #
+      # ==== Parameters
+      # column::  A reference to the column number to fetch the details for.
+      #           Column numbers start at zero.
+      #
+      def column_name(column)
+      end
+      
+      
+      #
+      # This method fetches the alias associated with a specified column for a
+      # ResultSet object.
+      #
+      # ==== Parameters
+      # column::  A reference to the column number to fetch the details for.
+      #           Column numbers start at zero.
+      #
+      def column_alias(column)
+      end
+      
+      
+      #
+      # This method fetches the table name associated with a specified column
+      # for a ResultSet object.
+      #
+      # ==== Parameters
+      # column::  A reference to the column number to fetch the details for.
+      #           Column numbers start at zero.
+      #
+      def column_table(column)
+      end
+      
+      
+      #
+      # This method fetches a single rows worth of data from the ResultSet
+      # object. If the set contains more rows then an array containing the
+      # row data will be retrieved. If the ResultSet is exhausted (i.e. all
+      # rows have been fetched) then nil is returned. Translation of the row
+      # data into an appropriate Ruby type is performed on the row data that
+      # is extracted.
+      #
+      def fetch
+      end
+      
+      
+      #
+      # This method is used to determine if all of the rows have been retrieved
+      # from a ResultSet object. This method will always return false until
+      # the fetch method has been called at least once so it cannot be used to
+      # detect a result set that returns no rows.
+      #
+      def exhausted?
+      end
+      
+      
+      #
+      # This method fetches a count of the total number of rows retrieved
+      # from a result set.
+      #
+      def row_count
+      end
+      
+      
+      #
+      # This method provides an iterator for the (remaining) rows contained in
+      # a ResultSet object.
+      #
+      # ==== Parameters
+      # block::  A block that takes a single parameter. This will be called for
+      #          and passed each remaining row (as per the fetch method) from
+      #          the ResultSet.
+      #
+      def each(&block)
+      end
+      
+      
+      #
+      # This method releases the database resources associated with a ResultSet
+      # object and should be explicitly called when a ResultSet object is of
+      # no further use. The method is implicitly called if the rows available
+      # from a ResultSet are exhausted but calling this method at that time
+      # will not cause an error.
+      #
+      # ==== Exceptions
+      # FireRubyError::  Generated whenever a problem occurs closing the result
+      #                  set object.
+      #
+      def close
+      end
+   end
+   
+   
+   #
+   # This class models a row of data fetched as part of a SQL query.
+   #
+   class Row
+      #
+      # This is the constructor for the Row class. This method shouldn't really
+      # be used as Row objects are automatically created by ResultSets.
+      #
+      # ==== Parameters
+      # results::  The ResultSet object that the row relates to.
+      # data::     An array containing the row data values.
+      # number::   The row number for the new row.
+      #
+      def initialize(results, data, number)
+      end
+      
+      #
+      # This is the accessor for the row number attribute. This will generally
+      # reflect the order the row was fetched from the result set in, with 1
+      # being the first row retrieved.
+      #
+      def number
+      end
+      
+      
+      #
+      # This method fetches a count of the number of columns of data that are
+      # available from a row.
+      #
+      def column_count
+      end
+      
+      
+      #
+      # This method fetches the name of a column within a row of data.
+      #
+      # ==== Parameters
+      # index::  The index of the column to fetch the name for. The first
+      #          column in the row is at offset zero.
+      #
+      def column_name(index)
+      end
+      
+      
+      #
+      # This method fetches the alias of a column within a row of data.
+      #
+      # ==== Parameters
+      # index::  The index of the column to fetch the alias for. The first
+      #          column in the row is at offset zero.
+      #
+      def column_alias(index)
+      end
+      
+      
+      #
+      # This method fetches the value associated with a column within a Row
+      # object.
+      #
+      # ==== Parameters
+      # index::  Either the offset of the column to retrieve the value of or
+      #          the name of the column to retrieve the value of (column name
+      #          comparisons are case sensitive).
+      #
+      def [](index)
+      end
+   end
+   
+   #
+   # This class represents Blob data fetched from the database. The class defers
+   # the actual loading of the blob until requested. The class is somewhat basic
+   # and maybe expanded upon in later releases.
+   #
+   class Blob
+      #
+      # This is the constructor for the Blob class. This shouldn't really be
+      # used outside of the FireRuby library.
+      #
+      def initialize
+      end
+      
+      
+      #
+      # This method loads the entire data set for a blob as a string.
+      #
+      def to_s
+      end
+      
+      
+      #
+      # This method closes a blob, freeing any resources associated with it.
+      #
+      def close
+      end
+      
+      
+      #
+      # This method loads the segments of a blob one after another. The blob
+      # segments are passed as strings to the block passed to the method.
+      #
+      def each
+         yield segment
+      end
+   end
+   
+   
+   #
+   # This class represents a Firebird generator entity.
+   #
+   class Generator
+      #
+      # This is the constructor for the Generator class. Note, this method
+      # assumes that the named generator already exists. If it doesn't then
+      # the object will be constructed but will fail during use.
+      #
+      # ==== Parameters
+      # name::        A string containing the generator name.
+      # connection::  A reference to the Connection object that will be used
+      #               to access the generator.
+      #
+      def initialize(name, connection)
+      end
+      
+      
+      #
+      # This is the accessor for the name attribute.
+      #
+      def name
+      end
+      
+      
+      #
+      # This is the accessor for the connection attribute.
+      #
+      def connection
+      end
+      
+      
+      #
+      # This method fetches the last value generator from a generator.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever a problem occurs accessing the
+      #              database generator.
+      #
+      def last
+      end
+      
+      
+      #
+      # This method drops a generator from the database. After a successful
+      # call to this method the Generator object may not be used to obtain
+      # values unless it is recreated.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever a problem occurs dropping the generator
+      #              from the database.
+      #
+      def drop
+      end
+      
+      
+      #
+      # This method fetches the next value, depending on a specified increment,
+      # from a generator.
+      #
+      # ==== Parameters
+      # step::  The step interval to be applied to the generator to obtain the
+      #         next value.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever a problem occurs accessing the
+      #              database generator.
+      #
+      def next(step)
+      end
+      
+      
+      #
+      # This method is used to determine whether a named generator exists
+      # within a database.
+      #
+      # ==== Parameters
+      # name::        A string containing the generator name to check for.
+      # connection::  A reference to the Connection object to be used in
+      #               performing the check.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever a problem occurs determining the
+      #              existence of the generator.
+      #
+      def Generator.exists?(name, connection)
+      end
+      
+      
+      #
+      # This method creates a new generator within a database. This method
+      # returns a Generator object is successful.
+      #
+      # ==== Parameters
+      # name::        A string containing the name for the new generator.
+      # connection::  A reference to the Connection object that will be used to
+      #               create the generator.
+      #
+      # ==== Exceptions
+      # Exception::  Generated whenever a problem occurs creating the new
+      #              generator in the database.
+      #
+      def Generator.create(name, connection)
+      end
+   end
+end