fireruby 0.3.1-i586-linux → 0.3.2-i586-linux

data/doc/README

@@ -1,69 +1,42 @@
-== FireRuby Version 0.3.0
+== FireRuby Version 0.3.2
 FireRuby is an extension to the Ruby language that provides access to the C API
 functionality of the Firebird relational database management system.
 
-This release extends the functionality of the Row object to allow it to be used
-as a read only Hash object and adds new funcionality relating to the Firebird
-RDBMS service manager.
+This release expands upon the functionality provided by the Database and
+Connection classes to provide extended support for connection options and, in
+particular, database character sets.
 
 Once again I would like to thank Ken Kunz for his support and input to the
 FireRuby project. Ken performs the unit testing and creates the gem file for the
-Linux version of the FireRuby library.
+Linux version of the FireRuby library. Thanks also to Art Fedorov for input on
+handling and testing character sets.
 
 == Enhancements & Alterations
 
-The Row class has been extended to include equivalents for all Hash methods that
-do would not alter the contents of the Hash. This effectively allows an instance
-of the Row class to be used as a Hash anywhere that a Hash object can be used
-without the need to change it's contents.
-
-A ServiceManager class and a collection of task related classes have been added
-for this release. The ServiceManager class represents a connection to a Firebird
-service manager instance. Task classes have been provided that allow for the
-backing up and restoration of databases as well as the addition or removal of
-database users.
-
-The Statement and ResultSet classes under went a major rewrite. This was done
-to eliminate a dependency between these two classes (the Statement class was
-using the ResultSet class to execute SQL regardless of whether the statement
-being executed was a query). This was an illogical and ill-consider set up and
-has now been eliminated. An effort was made to minimize changes to the interface
-but there have been some (primarily the constructor for the ResultSet class).
-The ResultSet class has now been restricted for use with queries only and will
-generate and exception if a non-query statement is specified. Queries can still
-be run through the Statement class but, if you know you're executing a query
-statement, it is more efficient to go straight to a ResultSet object.
+The Database class has been expanded to incorporate the concept of character
+sets. The Connection class has been extended to allow for the specification of
+a set of connection options. Both of these classes have also been altered to
+support the accessing of databases using the system user details (on POSIX
+systems).
 
 == Bug Fixes
 
-The only currently outstanding bug relates to accessing methods on the ResultSet
-class objects that have been created with a non-query SQL statement. This class
-has been fundamentally re-written and no longer allows the use of non-query SQL
-statements. This bug is therefore closed.
+There are no outstanding project bugs.
 
 == Issues
 
 Nothing is perfect so this section outlines those issues that are known to
 exist as of this release.
 
-- The big new issue for this release (0.3.0) relates to the fact the service
-  manager functionality does not appear to work on the Mac OS X platform. I
-  don't believe that this is a problem in the FireRuby code as I have tested the
-  Firebird gbak utility with the -service option and it gives the same result.
-  If anyone knows this to be untrue or of a work around let me know.
+- The service manager functionality does not appear to work on the Mac OS X
+  platform. I don't believe that this is a problem in the FireRuby code as I
+  have tested the Firebird gbak utility with the -service option and it gives
+  the same result. If anyone knows this to be untrue or of a work around let me
+  know.
 
 - The library currently does not support array columns. This may be implemented
   for a later release depending on demand.
   
-- There is an issue with the use of anonymous transactions inside of a block
-  for the Database#connect method. An attempt is made to close the connection
-  when the block exits. If, within the block, there is a call to the
-  Connection#execute_immediate method that generates a result set and,
-  subsequently, an exception is raised the anonymous transaction used in the
-  execute_immediate will be unavailable for closure. This will, in turn,
-  make it impossible to close the connection, resulting in an exception. As
-  a work around, don't use anonymous transactions for queries.
-
 == Installation & Usage
 
 The library is provided as a gem and built for use with Ruby 1.8+. Testing

data/lib/src.rb

@@ -55,7 +55,8 @@ module FireRuby
    
    
    #
-   # This class represents an existing database that can be connected to.
+   # This class represents an existing database that can be connected to. It
+   # also provides functionality to allow for the creation of new databases.
    #
    class Database
       #
@@ -64,8 +65,10 @@ module FireRuby
       # ==== Parameters
       # file::      A string containing the database file specifier. This can
       #             include details for a remote server if needed.
+      # set::       A string containing the name of the character set to be
+      #             used with the database. Defaults to nil.
       #
-      def initialize(file)
+      def initialize(file, set=nil)
       end
       
       
@@ -84,14 +87,21 @@ module FireRuby
       # 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.
+      # user::      The user name to be used in making the connection. This
+      #             defaults to nil.
+      # password::  The password to be used in making the connection. This
+      #             defaults to nil.
+      # options::   A Hash of connection options. This should be made up of
+      #             key/setting pairs where the keys are from the list that
+      #             is defined within the Connection class. The settings are
+      #             particular to the key, see the documentation for the
+      #             Connection class for more details.
       #
       # ==== Exceptions
       # Exception::  Thrown whenever a problem occurs connecting with the
       #              database.
       #
-      def connect(user, password)
+      def connect(user=nil, password=nil, options=nil)
          yield(connection)
       end
       
@@ -126,7 +136,9 @@ module FireRuby
       # size::      The page size setting to be used with the new database file.
       #             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. Defaults to nil.
+      #             new database file. If this parameter is specifed then the
+      #             Database object created by the call will use it to whenever
+      #             a connection request is made. Defaults to nil.
       #
       # ==== Exceptions
       # Exception::  Generated whenever an invalid parameter is specified or a
@@ -134,6 +146,29 @@ module FireRuby
       #
       def Database.create(file, user, password, size=1024, set=nil)
       end
+
+
+      #
+      # This method fetches the name of the character set currently assigned
+      # to a Database object. This can return nil to indicate that a explicit
+      # character set has not been assigned.
+      #
+      def character_set
+      end
+
+
+      #
+      # This method allows the specification of a database character set that
+      # will be used when creating connections to a database. The value set by
+      # this method can be overridden by providing an alternative in the connect
+      # call. To remove a character set specification from a Database object
+      # pass nil to this method.
+      #
+      # ==== Parameters
+      # set::  A string containing the name of the database character set.
+      #
+      def character_set=(set)
+      end
    end
    
    
@@ -141,22 +176,72 @@ module FireRuby
    # This class represents a connection with a Firebird database.
    #
    class Connection
+      # A definition for a connection option. This option should be given a
+      # setting of either true or false.
+      MARK_DATABASE_DAMAGED       = 17
+
+
+      # A definition for a connection option. This option should be given a
+      # setting of Connection::WRITE_ASYNCHRONOUS or
+      # Connection::WRITE_SYNCHRONOUS
+      WRITE_POLICY                = 24
+
+
+      # A definition for a connection option. This option should be given a
+      # string setting which should be the name of the character set to be
+      # used by the connection.
+      CHARACTER_SET               = 48
+
+
+      # A definition for a connection option. This option should be given a
+      # string setting which should be the name of the message file to be used
+      # by the connection.
+      MESSAGE_FILE                = 47
+
+
+      # A definition for a connection option. This option should be given a
+      # an integer setting. Values between 1 and 255 are valid, with 75 being
+      # the default.
+      NUMBER_OF_CACHE_BUFFERS     = 5
+
+
+      # A definition for a connection option. This option should be given a
+      # string value which should be the database DBA user name.
+      DBA_USER_NAME               = 19
+
+
+      # A definition for a possible setting to accompany the WRITE_POLICY
+      # connection setting.
+      WRITE_ASYNCHONOUS           = 0
+
+
+      # A definition for a possible setting to accompany the WRITE_POLICY
+      # connection setting.
+      WRITE_SYNCHONOUS            = 1
+      
+      
       #
       # 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.
+      #             database connection. Defaults to nil.
       # password::  A reference to the user password to be used in making the
-      #             connection.
+      #             connection. Defaults to nil.
+      # options::   A Hash containing the options to be applied to the new
+      #             connection. The hash will contain key/setting values, with
+      #             the keys being based on the option constants defined within
+      #             the Connection class. Individual options have differing
+      #             value requirements. See the option documentation entries
+      #             for further details. Defaults to nil.
       #
       # ==== 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)
+      def initialize(database, user, password, options)
       end
       
       

data/test/CharacterSetTest.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+
+require 'TestSetup'
+require 'test/unit'
+require 'rubygems'
+require_gem 'fireruby'
+
+include FireRuby
+
+class CharacterSetTest < Test::Unit::TestCase
+   CURDIR   = "#{Dir.getwd}"
+   DB_FILE  = "#{CURDIR}#{File::SEPARATOR}cxnarset_unit_test.fdb"
+   CHAR_SET = 'WIN1251'
+   
+   def setup
+      if File::exist?(DB_FILE)
+         Database.new(DB_FILE).drop(DB_USER_NAME, DB_PASSWORD)
+      end
+
+      @database = Database.create(DB_FILE, DB_USER_NAME, DB_PASSWORD, 1024,
+                                  CHAR_SET)
+   end
+   
+   def teardown
+      if File::exist?(DB_FILE)
+         Database.new(DB_FILE).drop(DB_USER_NAME, DB_PASSWORD)
+      end
+   end
+
+   def test01
+      db = Database.new(DB_FILE, CHAR_SET)
+
+      assert(db.character_set = CHAR_SET)
+
+      db.character_set = 'ASCII'
+      assert(db.character_set == 'ASCII')
+   end
+
+   def test02
+      text = "�?����"
+      db   = Database.new(DB_FILE, CHAR_SET)
+
+      begin
+         db.connect("SYSDBA", "masterkey") do |cxn|
+            cxn.start_transaction do |tr|
+               cxn.execute("CREATE TABLE SAMPLE_TABLE(SAMPLE_FIELD VARCHAR(100))",tr)
+            end  
+            cxn.start_transaction do |tr|
+               cxn.execute("INSERT INTO SAMPLE_TABLE VALUES ('#{win1251_str}')",tr)
+               cxn.execute("SELECT * FROM SAMPLE_TABLE WHERE SAMPLE_FIELD = '#{win1251_str}'",tr) do |row|
+                  # here we have an exception:
+                  some_var = row['SAMPLE_FIELD']
+               end
+            end
+         end
+      rescue => error
+         assert("Character set unit test failure.", false)
+      end
+   end
+end

data/test/ConnectionTest.rb

@@ -95,11 +95,15 @@ class ConnectionTest < Test::Unit::TestCase
 
       tx1 = connection.start_transaction
       tx2 = connection.start_transaction
+      tx3 = connection.start_transaction
+
+      tx2.rollback
+      assert(tx2.active? == false)
 
       connection.close
 
       assert(connection.closed?)
       assert(tx1.active? == false)
-      assert(tx2.active? == false)
+      assert(tx3.active? == false)
    end
 end

data/test/UnitTest.rb

@@ -11,6 +11,7 @@ require 'GeneratorTest'
 require 'DDLTest'
 require 'SQLTest'
 require 'ServiceManagerTest'
+require 'CharacterSetTest'
 if PLATFORM.include?('powerpc-darwin') == false
    require 'BackupRestoreTest'
    require 'AddRemoveUserTest'

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.10
 specification_version: 1
 name: fireruby
 version: !ruby/object:Gem::Version 
-  version: 0.3.1
-date: 2005-06-07
+  version: 0.3.2
+date: 2005-06-13
 summary: Ruby interface library for the Firebird database.
 require_paths: 
   - lib
@@ -37,6 +37,7 @@ files:
   - test/ConnectionTest.rb
   - test/ServiceManagerTest.rb
   - test/TransactionTest.rb
+  - test/CharacterSetTest.rb
   - test/TestSetup.rb
   - test/BackupRestoreTest.rb
   - test/RowCountTest.rb