# # 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