fireruby 0.2.2-mswin32 → 0.3.0-mswin32

data/lib/src.rb

@@ -124,15 +124,15 @@ module FireRuby
       # 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.
+      #             This should be 1024, 2048, 4096 or 8192. Defaults to 1024.
       # set::       The name of the default character set to be assigned to the
-      #             new database file.
+      #             new database file. Defaults to nil.
       #
       # ==== 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)
+      def Database.create(file, user, password, size=1024, set=nil)
       end
    end
    
@@ -233,8 +233,10 @@ module FireRuby
       
       #
       # 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
+      # statement represented a SQL query then a ResultSet object is returned.
+      # If the statement was a non-query SQL statement then an Integer is
+      # returned indicating the number of rows affected by the statement. For
+      # all other types of statement the method returns nil. 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.
       #
@@ -377,10 +379,12 @@ module FireRuby
       # 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.
+      # SQL query then the method returns a ResultSet object. For non-query SQL
+      # statements (insert, update or delete) the method returns an Integer that
+      # contains the number of rows affected by the statement. For all other
+      # statements the method 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.
@@ -421,6 +425,48 @@ module FireRuby
    # than once.
    #
    class Statement
+      # A definition for a SQL statement type constant.
+      SELECT_STATEMENT            = 1
+      
+      # A definition for a SQL statement type constant.
+      INSERT_STATEMENT            = 2
+      
+      # A definition for a SQL statement type constant.
+      UPDATE_STATEMENT            = 3
+      
+      # A definition for a SQL statement type constant.
+      DELETE_STATEMENT            = 4
+      
+      # A definition for a SQL statement type constant.
+      DDL_STATEMENT               = 5
+      
+      # A definition for a SQL statement type constant.
+      GET_SEGMENT_STATEMENT       = 6
+      
+      # A definition for a SQL statement type constant.
+      PUT_SEGMENT_STATEMENT       = 7
+      
+      # A definition for a SQL statement type constant.
+      EXECUTE_PROCEDURE_STATEMENT = 8
+      
+      # A definition for a SQL statement type constant.
+      START_TRANSACTION_STATEMENT = 9
+      
+      # A definition for a SQL statement type constant.
+      COMMIT_STATEMENT            = 10
+      
+      # A definition for a SQL statement type constant.
+      ROLLBACK_STATEMENT          = 11
+      
+      # A definition for a SQL statement type constant.
+      SELECT_FOR_UPDATE_STATEMENT = 12
+      
+      # A definition for a SQL statement type constant.
+      SET_GENERATOR_STATEMENT     = 13
+      
+      # A definition for a SQL statement type constant.
+      SAVE_POINT_STATEMENT        = 14
+      
       #
       # This is the constructor for the Statement class.
       #
@@ -466,10 +512,10 @@ module FireRuby
       
       
       #
-      # This method is used to determine whether a Statement object represents
-      # a SQL query.
+      # This method is used to determine the type of a SQL statement. The method
+      # will return one of the constant SQL types defined within the class.
       #
-      def is_query?
+      def type
       end
       
       
@@ -485,10 +531,12 @@ module FireRuby
       #
       # 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.
+      # query. For non-query SQL statements (insert, update or delete) it
+      # returns an Integer indicating the number of affected rows. For all other
+      # statements the method 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
@@ -504,10 +552,12 @@ module FireRuby
       # 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.
+      # statement executed was a SQL query. If the statement was a non-query SQL
+      # statement (insert, update or delete) then the method returns a count of
+      # the number of rows affected. For all other types of statement the method
+      # 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
@@ -548,17 +598,50 @@ module FireRuby
       # This is the constructor for the ResultSet object.
       #
       # ==== Parameters
-      # statement::  A reference to the Statement object that the ResultSet
-      #              will be based on.
+      # connection::   A reference to the Connection object that will be used
+      #                to execute the SQL query.
+      # transaction::  A reference to the Transaction object that will be used
+      #                in executing the SQL query.
+      # sql::          A reference to a String containing the SQL query that
+      #                will be executed.
+      # dialect::      A reference to an integer containing the Firebird dialect
+      #                to be used in executing the SQL statement.
+      #
+      # ==== Exceptions
+      # FireRubyException::  Generated whenever a non-query SQL statement is
+      #                      specified, an invalid connection or transaction is
+      #                      provided or a problem occurs executing the SQL
+      #                      against the database.
+      #
+      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 attribute.
       #
-      def initialize(statement)
+      def sql
       end
       
       
       #
-      # This is the accessor for the statement attribute.
+      # This is the accessor for the dialect attribute.
       #
-      def statement
+      def dialect
       end
       
       
@@ -731,6 +814,139 @@ module FireRuby
       #
       def [](index)
       end
+      
+      
+      #
+      # This method iterates over the contents of a Row object. The block
+      # specified for the method should accept two parameters; one for the
+      # column name and one for the column value.
+      #
+      def each
+         yield column, vlaue
+      end
+      
+      
+      #
+      # This method iterates over the column names for a Row class.
+      #
+      def each_key
+         yield column
+      end
+      
+      
+      #
+      # This method iterators over the column values for a Row class.
+      #
+      def each_value
+         yield value
+      end
+      
+      
+      #
+      # An implementation of the Hash#fetch method for the Row class. The
+      # method accepts a block but this should not be specified if a value
+      # for the alternative parameter is specified.
+      #
+      # ==== Parameters
+      # key::          A string containing the column name to retrieve.
+      # alternative::  A reference to the alternative value to be returned if
+      #                the keyed value is not found. Defaults to nil.
+      #
+      def fetch(key, alternative=nil)
+         yield key
+      end
+      
+      
+      #
+      # This method is used to determine whether a Row object contains a given
+      # column name.
+      #
+      # ==== Parameters
+      # name::  A String containing the column name to check for.
+      #
+      def has_key?(name)
+      end
+      
+      
+      #
+      # This method is used to determine whether a Row object contains a given
+      # column alias.
+      #
+      # ==== Parameters
+      # name::  A String containing the column alias to check for.
+      #
+      def has_alias?(name)
+      end
+      
+      
+      #
+      # This method is used to determine whether a Row object contains a given
+      # column value.
+      #
+      # ==== Parameters
+      # value::  A reference to an object value to be checked for.
+      #
+      def has_value?(value)
+      end
+      
+      
+      #
+      # This method retrieves an array of column names for a Row object.
+      #
+      def keys
+      end
+      
+      
+      #
+      # This method retrieves an array of column aliases for a Row object.
+      #
+      def aliases
+      end
+      
+      
+      #
+      # This method retrieves an array of column values for a Row object.
+      #
+      def values
+      end
+      
+      
+      #
+      # This method returns an array of the Row elements for which the specified
+      # block returns true.
+      #
+      def select
+         yield column, value
+      end
+      
+      
+      #
+      # This method retrieves an Array containing the values from a Row object.
+      # Each value is represented as an Array containing a column name and the
+      # associated column value.
+      #
+      def to_a
+      end
+      
+      
+      #
+      # This method retrieves a Hash created from a Row objects values. The Row
+      # objects column names will be used as a key on to the column values.
+      #
+      def to_hash
+      end
+      
+      
+      #
+      # This method returns an array of column values based on a list of column
+      # names.
+      #
+      # ==== Parameters
+      # names::  One or more Strings containing the names of the columns to
+      #          retrieve values for.
+      #
+      def values_at(*names)
+      end
    end
    
    #
@@ -876,4 +1092,570 @@ module FireRuby
       def Generator.create(name, connection)
       end
    end
+   
+   
+   #
+   # This class represents a connection to the service manager for a Firebird
+   # database server instance. NOTE: This class does not currently work on the
+   # Mac OS X platform.
+   #
+   class ServiceManager
+      #
+      # This is the constructor for the ServiceManager class.
+      #
+      # ==== Parameters
+      # host::  The name of the host supporting the service manager to be
+      #         connected with.
+      #
+      def initialize(host)
+      end
+      
+      
+      #
+      # This method attaches a ServiceManager object to its host service. The
+      # user name used to connect with can affect which services can be accessed
+      # on the server.
+      #
+      # ==== Parameters
+      # user::      A string containing the user name to connect with.
+      # password::  A string containing the user password to connect with.
+      #
+      def connect(user, password)
+      end
+      
+      
+      #
+      # This method disconnects a previously connected ServiceManager object.
+      #
+      def disconnect
+      end
+      
+      
+      #
+      # This method is used to determine whether a ServiceManager object has
+      # been connected.
+      #
+      def connected?
+      end
+      
+      
+      #
+      # This method is used to batch execute a collection of task objects.
+      #
+      # ==== Parameters
+      # tasks::  One or more task objects to be executed by the service manager.
+      #
+      # ==== Exceptions
+      # FireRubyException::  Generated whenever this method is called on a
+      #                      disconnected service manager or is a problem
+      #                      occurs executing one of the tasks.
+      #
+      def execute(*tasks)
+      end
+   end
+   
+   
+   #
+   # This class represents a service manager task to add a new user to a
+   # database instance. NOTE: This class does not currently work on the
+   # Mac OS X platform.
+   #
+   class AddUser
+      # Attribute accessor.
+      attr_reader :user_name, :password, :first_name, :middle_name, :last_name
+      
+      # Attribute mutator.
+      attr_writer :user_name, :password, :first_name, :middle_name, :last_name
+      
+      #
+      # This is a constructor for the AddUser class.
+      #
+      # ==== Parameters
+      # user_name::    A String containing the user name to be assigned to the
+      #                new user.
+      # password::     A String containing the password to be assigned to the
+      #                new user.
+      # first_name::   A String containing the first name to be associated with
+      #                the new user. Defaults to nil.
+      # middle_name::  A String containing the middle name to be associated
+      #                with the new user. Defaults to nil.
+      # last_name::    A String containing the last name to be associated with
+      #                the new user. Defaults to nil.
+      #
+      def initialize(user_name, password, firsts_name=nil, middle_name=nil,
+                     last_name=nil)
+      end
+      
+      
+      #
+      # This method executes the add user task against a service manager.
+      #
+      # ==== Parameters
+      # manager::  A reference to the ServiceManager object to execute the task
+      #            on.
+      #
+      # ==== Exceptions
+      # FireRubyException::  Generated whenever a disconnected service manager
+      #                      is specified or an error occurs executing the
+      #                      task.
+      #
+      def execute(manager)
+      end
+   end
+   
+   
+   #
+   # This class represents a service manager task to remove an existing user
+   # from a database instance. NOTE: This class does not currently work on the
+   # Mac OS X platform.
+   #
+   class RemoveUser
+      # Attribute accessor.
+      attr_reader :user_name
+      
+      # Attribute mutator.
+      attr_writer :user_name
+      
+      #
+      # This is a constructor for the RemoveUser class.
+      #
+      # ==== Parameters
+      # user_name::    A String containing the user name to be assigned to the
+      #                new user.
+      #
+      def initialize(user_name)
+      end
+      
+      
+      #
+      # This method executes the remove user task against a service manager.
+      #
+      # ==== Parameters
+      # manager::  A reference to the ServiceManager object to execute the task
+      #            on.
+      #
+      # ==== Exceptions
+      # FireRubyException::  Generated whenever a disconnected service manager
+      #                      is specified or an error occurs executing the
+      #                      task.
+      #
+      def execute(manager)
+      end
+   end
+   
+   
+   #
+   # This class represents a service manager task to backup an existing database
+   # on the Firebird server. NOTE: This class does not currently work on the
+   # Mac OS X platform.
+   #
+   class Backup
+      # Attribute accessor.
+      attr_reader :backup_file, :database
+      
+      # Attribute mutator.
+      attr_writer :backup_file, :database
+      
+      #
+      # This is the constructor for the Backup class.
+      #
+      # ==== Parameters
+      # database::  A String or File giving the path and name (relative to the
+      #             database server) of the main database file for the database
+      #             to be backed up.
+      # file::      A String or File giving the path and name (relative to the
+      #             database server) of the back up file to be generated.
+      #
+      def initialize(database, file)
+      end
+      
+      
+      #
+      # This method fetches the blocking factor to be used in generating the
+      # back up. This will return nil until it has been explicitly set.
+      #
+      def blocking_factor
+      end
+      
+      
+      #
+      # This method sets the blocking factor to be used in generating the
+      # back up.
+      #
+      # ==== Parameters
+      # size::  A reference to an integer containing the new back up blocking
+      #         factor setting.
+      #
+      def blocking_factor=(size)
+      end
+      
+      
+      #
+      # This method fetches the ignore checksums setting for a Backup object.
+      #
+      def ignore_checksums
+      end
+      
+      
+      #
+      # This method is used to set the indicator for whether checksum values
+      # should be ignored in performing a backup.
+      #
+      # ==== Parameters
+      # setting::  True to ignore checksums, false otherwise.
+      #
+      def ignore_checksums=(setting)
+      end
+      
+      
+      #
+      # This method fetches the ignore limbo setting for a Backup object.
+      #
+      def ignore_limbo
+      end
+      
+      
+      #
+      # This method is used to set the indicator for whether limbo transactions
+      # should be ignored in performing a backup.
+      #
+      # ==== Parameters
+      # setting::  True to ignore limbo transactions, false otherwise.
+      #
+      def ignore_limbo=(setting)
+      end
+      
+      
+      #
+      # This method fetches the metadata only setting for a Backup object.
+      #
+      def metadata_only
+      end
+      
+      
+      #
+      # This method is used to set the indicator for whether a backup stores
+      # only the database metadata.
+      #
+      # ==== Parameters
+      # setting::  True to store only metadata, false otherwise.
+      #
+      def metadata_only=(setting)
+      end
+      
+      
+      #
+      # This method fetches the garbage collect setting for a Backup object.
+      #
+      def garbage_collect
+      end
+      
+      
+      #
+      # This method is used to set the indicator for whether the backup will
+      # undertake garbage collection.
+      #
+      # ==== Parameters
+      # setting::  True to perform garbage collection, false otherwise.
+      #
+      def garbage_collect=(setting)
+      end
+      
+      
+      #
+      # This method fetches the non-transportable setting for a Backup object.
+      #
+      def non_transportable
+      end
+      
+      
+      #
+      # This method is used to set the indicator for whether backup generated
+      # by the task will be platform specific.
+      #
+      # ==== Parameters
+      # setting::  True to generate a platform specific backup, false otherwise.
+      #
+      def non_transportable=(setting)
+      end
+      
+      
+      #
+      # This method fetches the convert tables setting for a Backup object.
+      #
+      def convert_tables
+      end
+      
+      
+      #
+      # This method is used to set the indicator for whether external tables
+      # will be converted to internal tables as part of the backup.
+      #
+      # ==== Parameters
+      # setting::  True to convert external tables, false otherwise.
+      #
+      def convert_tables=(setting)
+      end
+      
+      
+      #
+      # This method is used to execute a backup task against a service manager.
+      #
+      # ==== Parameters
+      # manager::  A reference to the service manager to execute the backup
+      #            task against.
+      #
+      # ==== Exceptions
+      # FireRubyException::  Generated whenever a disconnected service manager
+      #                      is specified or a problem occurs executing the
+      #                      task.
+      #
+      def execute(manager)
+      end
+      
+      
+      #
+      # This method fetches the log value for a Backup task. This value will
+      # always be nil until the task has been executed. After a successful
+      # execution the log value should contain output from the backup task
+      # generated on the server.
+      #
+      def log
+      end
+   end
+   
+   
+   #
+   # This class represents a service manager task to restore a previously
+   # created database backup on the Firebird server. NOTE: This class does not
+   # currently work on the Mac OS X platform.
+   #
+   class Restore
+      # Attribute accessor.
+      attr_reader :backup_file, :database
+      
+      # Attribute mutator.
+      attr_writer :backup_file, :database
+      
+      # Access mode constant definition.
+      ACCESS_READ_ONLY       = 39
+      
+      # Access mode constant definition.
+      ACCESS_READ_WRITE      = 40
+      
+      # Restore mode constant definition.
+      MODE_CREATE            = 0x1000
+      
+      # Restore mode constant definition.
+      MODE_REPLACE           = 0x2000
+      
+      #
+      # This is the constructor for the Restore class.
+      #
+      # ==== Parameters
+      # file::      A String or File containing the path and name (relative to
+      #             the server) of the backup file to be used in the restore.
+      # database::  A String or File containing the path and name (relative to
+      #             the server) of the database file to be restored.
+      #
+      def initialize(file, database)
+      end
+      
+      
+      #
+      # This method retrieves the cache buffers setting for a Restore object.
+      # This will be nil until a value is actual set.
+      #
+      def cache_buffers
+      end
+      
+      
+      #
+      # This method updates the cache buffers setting for a Restore object.
+      #
+      # ==== Parameters
+      # setting::  The new value for the object setting. Should be an integer.
+      #
+      def cache_buffers=(setting)
+      end
+      
+      
+      #
+      # This method retrieves the page size setting for a Restore object.
+      # This will be nil until a value is actual set.
+      #
+      def page_size
+      end
+      
+      
+      #
+      # This method updates the page size setting for a Restore object.
+      #
+      # ==== Parameters
+      # setting::  The new value for the object setting. Should be an integer.
+      #
+      def page_size=(setting)
+      end
+      
+      
+      #
+      # This method retrieves the access mode setting for a Restore object.
+      # This will be nil until a value is actual set.
+      #
+      def access_mode
+      end
+      
+      
+      #
+      # This method updates the access mode setting for a Restore object.
+      #
+      # ==== Parameters
+      # setting::  The new value for the object setting. This should be one
+      #            of Restore::ACCESS_READ_ONLY or Restore::ACCESS_READ_WRITE.
+      #
+      def access_mode=(setting)
+      end
+      
+      
+      #
+      # This method retrieves the build indices setting for a Restore object.
+      #
+      def build_indices
+      end
+      
+      
+      #
+      # This method updates the build indices setting for a Restore object.
+      # This value affects whether the various indexes for a database are
+      # restored with the restore task.
+      #
+      # ==== Parameters
+      # setting::  True to rebuild the database indices, false otherwise.
+      #
+      def build_indices=(setting)
+      end
+      
+      
+      #
+      # This method retrieves the no shadows setting for a Restore object.
+      #
+      def no_shadows
+      end
+      
+      
+      #
+      # This method updates the no shadows setting for a Restore object.
+      # This value affects whether shadow databases are recreated as part of a
+      # restore.
+      #
+      # ==== Parameters
+      # setting::  True to recreate shadow files, false otherwise.
+      #
+      def no_shadows=(setting)
+      end
+      
+      
+      #
+      # This method retrieves the validity checks setting for a Restore object.
+      #
+      def check_validity
+      end
+      
+      
+      #
+      # This method updates the validity checks setting for a Restore object.
+      # This value affects whether the restore performs validity checks on the
+      # database as it is restored.
+      #
+      # ==== Parameters
+      # setting::  True to perform validity checks, false otherwise.
+      #
+      def check_validity=(setting)
+      end
+      
+      
+      #
+      # This method retrieves the commit tables setting for a Restore object.
+      #
+      def commit_tables
+      end
+      
+      
+      #
+      # This method updates the commit tables setting for a Restore object.
+      # This value affects whether the restore commits tables as they are
+      # restored.
+      #
+      # ==== Parameters
+      # setting::  True to commit tables as they are restored, false otherwise.
+      #
+      def commit_tables=(setting)
+      end
+      
+      
+      #
+      # This method retrieves the restore mode setting for a Restore object.
+      #
+      def restore_mode
+      end
+      
+      
+      #
+      # This method updates the restore mode setting for a Restore object.
+      # This value affects whether the restore will overwrite an existing
+      # database.
+      #
+      # ==== Parameters
+      # setting::  Either Restore::MODE_CREATE (default) or
+      #            Restore::MODE_REPLACE.
+      #
+      def restore_mode=(setting)
+      end
+      
+      
+      #
+      # This method retrieves the use all space setting for a Restore object.
+      #
+      def use_all_space
+      end
+      
+      
+      #
+      # This method updates the use all space setting for a Restore object.
+      # This value affects whether restore leaves space within the database
+      # file for expansion. This can be switched on for read only databases.
+      #
+      # ==== Parameters
+      # setting::  True leave no default expansion space within the restored
+      #            database file, false otherwise.
+      #
+      def use_all_space=(setting)
+      end
+      
+      
+      #
+      # This method is used to execute a restore task against a service manager.
+      #
+      # ==== Parameters
+      # manager::  A reference to the service manager to execute the restore
+      #            task against.
+      #
+      # ==== Exceptions
+      # FireRubyException::  Generated whenever a disconnected service manager
+      #                      is specified or a problem occurs executing the
+      #                      task.
+      #
+      def execute(manager)
+      end
+      
+      
+      #
+      # This method fetches the log value for a Restore task. This value will
+      # always be nil until the task has been executed. After a successful
+      # execution the log value should contain output from the restore task
+      # generated on the server.
+      #
+      def log
+      end
+   end
 end