fireruby 0.2.2-powerpc-darwin → 0.3.0-powerpc-darwin

Sign up to get free protection for your applications and to get access to all the features.
Files changed (53) hide show
  1. data/doc/CVS/Entries +2 -3
  2. data/doc/CVS/Entries.Log +2 -0
  3. data/doc/README +149 -53
  4. data/doc/classes/CVS/Entries +1 -0
  5. data/doc/classes/CVS/Entries.Log +1 -0
  6. data/doc/classes/CVS/Repository +1 -0
  7. data/doc/classes/CVS/Root +1 -0
  8. data/doc/classes/FireRuby/CVS/Entries +1 -0
  9. data/doc/classes/FireRuby/CVS/Entries.Log +7 -0
  10. data/doc/classes/FireRuby/CVS/Repository +1 -0
  11. data/doc/classes/FireRuby/CVS/Root +1 -0
  12. data/doc/classes/FireRuby/Connection.src/CVS/Entries +1 -0
  13. data/doc/classes/FireRuby/Connection.src/CVS/Repository +1 -0
  14. data/doc/classes/FireRuby/Connection.src/CVS/Root +1 -0
  15. data/doc/classes/FireRuby/Database.src/CVS/Entries +1 -0
  16. data/doc/classes/FireRuby/Database.src/CVS/Repository +1 -0
  17. data/doc/classes/FireRuby/Database.src/CVS/Root +1 -0
  18. data/doc/classes/FireRuby/FireRubyError.src/CVS/Entries +1 -0
  19. data/doc/classes/FireRuby/FireRubyError.src/CVS/Repository +1 -0
  20. data/doc/classes/FireRuby/FireRubyError.src/CVS/Root +1 -0
  21. data/doc/classes/FireRuby/Generator.src/CVS/Entries +1 -0
  22. data/doc/classes/FireRuby/Generator.src/CVS/Repository +1 -0
  23. data/doc/classes/FireRuby/Generator.src/CVS/Root +1 -0
  24. data/doc/classes/FireRuby/ResultSet.src/CVS/Entries +1 -0
  25. data/doc/classes/FireRuby/ResultSet.src/CVS/Repository +1 -0
  26. data/doc/classes/FireRuby/ResultSet.src/CVS/Root +1 -0
  27. data/doc/classes/FireRuby/Statement.src/CVS/Entries +1 -0
  28. data/doc/classes/FireRuby/Statement.src/CVS/Repository +1 -0
  29. data/doc/classes/FireRuby/Statement.src/CVS/Root +1 -0
  30. data/doc/classes/FireRuby/Transaction.src/CVS/Entries +1 -0
  31. data/doc/classes/FireRuby/Transaction.src/CVS/Repository +1 -0
  32. data/doc/classes/FireRuby/Transaction.src/CVS/Root +1 -0
  33. data/doc/files/CVS/Entries +1 -0
  34. data/doc/files/CVS/Repository +1 -0
  35. data/doc/files/CVS/Root +1 -0
  36. data/lib/CVS/Entries +1 -1
  37. data/lib/fireruby.bundle +0 -0
  38. data/lib/src.rb +807 -25
  39. data/test/AddRemoveUserTest.rb +50 -0
  40. data/test/BackupRestoreTest.rb +97 -0
  41. data/test/CVS/Entries +13 -9
  42. data/test/ConnectionTest.rb +1 -1
  43. data/test/DDLTest.rb +10 -8
  44. data/test/GeneratorTest.rb +2 -2
  45. data/test/ResultSetTest.rb +42 -8
  46. data/test/RowCountTest.rb +63 -0
  47. data/test/RowTest.rb +93 -5
  48. data/test/SQLTest.rb +16 -8
  49. data/test/ServiceManagerTest.rb +21 -0
  50. data/test/StatementTest.rb +3 -3
  51. data/test/TransactionTest.rb +6 -5
  52. data/test/UnitTest.rb +6 -0
  53. metadata +59 -2
data/doc/CVS/Entries CHANGED
@@ -1,4 +1,3 @@
1
- /README/1.3/Thu Mar 31 08:31:42 2005//
1
+ /README/1.5/Mon May 9 09:16:38 2005//
2
2
  /license.txt/1.1/Tue Mar 15 13:40:26 2005//
3
- D/classes////
4
- D/files////
3
+ D
@@ -0,0 +1,2 @@
1
+ A D/classes////
2
+ A D/files////
data/doc/README CHANGED
@@ -1,31 +1,57 @@
1
- == FireRuby Version 0.2.2
1
+ == FireRuby Version 0.3.0
2
2
  FireRuby is an extension to the Ruby language that provides access to the C API
3
3
  functionality of the Firebird relational database management system.
4
4
 
5
- This release is primarily about providing a Linux build of the FireRuby library.
6
- Thanks go to Ken Kunz for his help in providing the build machine and generating
7
- the actual build on Linux. Ken noted that the make file generated from the
8
- extconf.rb script had a CFLAGS entry of 'march=pentium4'. He altered this to
9
- 'mcpu=i586' which, he informs me, should be compatible across i386
10
- architectures.
5
+ This release extends the functionality of the Row object to allow it to be used
6
+ as a read only Hash object and adds new funcionality relating to the Firebird
7
+ RDBMS service manager.
11
8
 
12
- Some of the source controlled files and scripts for the library have been
13
- updated as part of getting the Linux build working. All updates have been
14
- checked into CVS on Ruby Forge.
9
+ Once again I would like to thank Ken Kunz for his support and input to the
10
+ FireRuby project. Ken performs the unit testing and creates the gem file for the
11
+ Linux version of the FireRuby library.
15
12
 
16
13
  == Enhancements & Alterations
17
14
 
18
- A gem of the FireRuby library for Linux was added to the release files.
15
+ The Row class has been extended to include equivalents for all Hash methods that
16
+ do would not alter the contents of the Hash. This effectively allows an instance
17
+ of the Row class to be used as a Hash anywhere that a Hash object can be used
18
+ without the need to change it's contents.
19
+
20
+ A ServiceManager class and a collection of task related classes have been added
21
+ for this release. The ServiceManager class represents a connection to a Firebird
22
+ service manager instance. Task classes have been provided that allow for the
23
+ backing up and restoration of databases as well as the addition or removal of
24
+ database users.
25
+
26
+ The Statement and ResultSet classes under went a major rewrite. This was done
27
+ to eliminate a dependency between these two classes (the Statement class was
28
+ using the ResultSet class to execute SQL regardless of whether the statement
29
+ being executed was a query). This was an illogical and ill-consider set up and
30
+ has now been eliminated. An effort was made to minimize changes to the interface
31
+ but there have been some (primarily the constructor for the ResultSet class).
32
+ The ResultSet class has now been restricted for use with queries only and will
33
+ generate and exception if a non-query statement is specified. Queries can still
34
+ be run through the Statement class but, if you know you're executing a query
35
+ statement, it is more efficient to go straight to a ResultSet object.
19
36
 
20
37
  == Bug Fixes
21
38
 
22
- No bugs were fixed for this release.
39
+ The only currently outstanding bug relates to accessing methods on the ResultSet
40
+ class objects that have been created with a non-query SQL statement. This class
41
+ has been fundamentally re-written and no longer allows the use of non-query SQL
42
+ statements. This bug is therefore closed.
23
43
 
24
44
  == Issues
25
45
 
26
46
  Nothing is perfect so this section outlines those issues that are known to
27
47
  exist as of this release.
28
48
 
49
+ - The big new issue for this release (0.3.0) relates to the fact the service
50
+ manager functionality does not appear to work on the Mac OS X platform. I
51
+ don't believe that this is a problem in the FireRuby code as I have tested the
52
+ Firebird gbak utility with the -service option and it gives the same result.
53
+ If anyone knows this to be untrue or of a work around let me know.
54
+
29
55
  - The library currently does not support array columns. This may be implemented
30
56
  for a later release depending on demand.
31
57
 
@@ -46,13 +72,13 @@ the Ruby Gems package to be installed. Assuming that these installation criteria
46
72
  have been met the library can be installed on Windows by executing a command
47
73
  such as the following...
48
74
 
49
- gem install fireruby-0.2.2-mswin32.gem
75
+ gem install fireruby-0.3.0-mswin32.gem
50
76
 
51
77
  On the Mac OS X platform you may require super user privilege if your Ruby is
52
78
  installed to the default location (i.e. /usr/local/lib). In this case you can
53
79
  use the sudo command to make the installation like this...
54
80
 
55
- sudo gem install fireruby-0.2.2-powerpc-darwin.gem
81
+ sudo gem install fireruby-0.3.0-powerpc-darwin.gem
56
82
 
57
83
  Once the gem installation is complete the FireRuby functionality can be accessed
58
84
  in code with the usual gem style requires...
@@ -63,15 +89,15 @@ in code with the usual gem style requires...
63
89
  == Build Details
64
90
 
65
91
  The FireRuby library is an extension of the Ruby language written in C. For Mac
66
- OS X the library was built against Firebird installed as a framework, version
67
- 1.5.1, and with Ruby version 1.8.2. For the Windows platform the library was
68
- built against a Ruby installation created using the one-click installer, version
69
- 1.8.2. The Windows build was created using the freely available Microsoft
70
- compilers and SDKs and built against a standard installation of Firebird,
71
- version 1.5.2. On Linux the library (I believe) has been linked against the
72
- Firebird shared object. This being the case then your LD_LIBRARY_PATH
73
- environment variable will have to be set to include the Firebird lib directory
74
- if you want to use it.
92
+ OS X the library is built on version 10.3 of the OS and against Firebird
93
+ installed as a framework, version 1.5.1, and with Ruby version 1.8.2. For the
94
+ Windows platform the library is built on Windows XP and against a Ruby
95
+ installation created using the one-click installer, version 1.8.2. The Windows
96
+ build was created using the freely available Microsoft compilers and SDKs and
97
+ built against a standard installation of Firebird, version 1.5.2. On Linux the
98
+ library (I believe) has been linked against the Firebird shared object. This
99
+ being the case then your LD_LIBRARY_PATH environment variable will have to be
100
+ set to include the Firebird lib directory if you want to use it.
75
101
 
76
102
  == So How Do I Use It?
77
103
 
@@ -199,17 +225,10 @@ this is and you're only using Firebird it's probably safe to use a value of
199
225
  3 here. Other values are for backward compatibility. Consult the Firebird and
200
226
  Interbase documentation for more details.
201
227
 
202
- Anyway, now that we have our Statement how do we use it. Well, there are two
203
- approaches to using the Statement object. For statements like the one used
204
- above, queries that take no parameters, you can use the Statement object to
205
- build a ResultSet object, like so...
206
-
207
- r = ResultSet.new(s)
208
-
209
- The ResultSet class will be covered in a little more detail below. The other
210
- means by which a Statement can be used is to call one of it's execute methods.
211
- The one to be called depends on whether the Statement requires parameters or
212
- not. What are parameters you ask? Well, look at the following...
228
+ Anyway, now that we have our Statement how do we use it? Well, the answer is
229
+ that we call once of the Statement objects execute methods. The one to be called
230
+ depends on whether the Statement requires parameters or not. What are parameters
231
+ you ask? Well, look at the following...
213
232
 
214
233
  s = Statement.new(cxn, tx, 'SELECT * FROM MY_TABLE WHERE MYID = ?', 3)
215
234
 
@@ -219,25 +238,34 @@ that wraps such a piece of SQL must be provided with the necessary parameters
219
238
  to execute properly. Where a Statement object represents SQL that requires a
220
239
  parameter then the execute_for method must be called, like this...
221
240
 
222
- r = s.execute_for([25])
241
+ s.execute_for([25])
223
242
 
224
243
  This code executes the SQL substituting the parameters from the array of data
225
244
  passed to the function call. If a Statement object represents SQL that does not
226
245
  require parameter values a call to the execute method will suffice, such as the
227
246
  following...
228
247
 
229
- r = s.execute
248
+ s.execute
230
249
 
231
250
  The execute methods for the Statement class, as with all of the execute methods
232
- for the FireRuby library, have two potential return values. They will either
233
- return nil or they will return a ResultSet object. A ResultSet object will only
234
- be returned for SQL statements that constitute a query, irrespective of whether
235
- that query returns any data. For all other SQL statements the various execute
236
- method will return nil.
251
+ for the FireRuby library, have three potential return values. They will either
252
+ return an Integer, a ResultSet object or nil. A ResultSet object will only be
253
+ returned for SQL statements that constitute a query, irrespective of whether
254
+ that query returns any data. For all other SQL statements (inserts, updates and
255
+ deletes) the execute method will return a count of the number of rows affected
256
+ by the statement execution. For any other SQL statements the various execute
257
+ methods will return nil.
237
258
 
238
259
  A ResultSet object represents a handle by which the data retrieved for a SQL
239
- query can be accessed. To fetch a row of data from a ResultSet object you call
240
- the fetch method, like the following...
260
+ query can be accessed. While it's possible to obtain a ResultSet from one of the
261
+ execute methods on the Connection, Transaction or Statement classes it is more
262
+ efficient to create one directly. The constructor for the ResultSet class
263
+ accepts the same arguments as the constructor for the Statement class but will
264
+ throw an exception if the SQL statement specified is not a query.
265
+
266
+ Once we have obtained a ResultSet we can extract the rows of data for a query
267
+ from it. To fetch a row of data from a ResultSet object you call the fetch
268
+ method, like the following...
241
269
 
242
270
  row = r.fetch
243
271
 
@@ -261,8 +289,9 @@ columns of data within the row like this...
261
289
  value = row[1]
262
290
 
263
291
  The index specified to the array dereference operator specifies the column that
264
- you want the data for. Column indices start at 0. Alternatively you can use the
265
- column name to access the data, like this...
292
+ you want the data for. Column indices start at 0. Alternatively you can treat
293
+ the Row object like a read only Hash object and use the column name to access
294
+ the data, like this...
266
295
 
267
296
  value = row['MYID']
268
297
 
@@ -270,9 +299,8 @@ This is beneficial as it frees you from the constraint of knowing the ordering
270
299
  of the columns within the row. For more information of the Row class please
271
300
  consult the API documentation.
272
301
 
273
- Well that covers the bulk of the classes provided by the FireRuby library. The
274
- three which haven't been touched upon are the Generator class, the Blob class
275
- and the FireRubyException class.
302
+ That covers the bulk of the SQL classes provided by the FireRuby library. The
303
+ two which haven't been touched upon are the Generator class and the Blob class.
276
304
 
277
305
  The Generator class is a wrapper around the Firebird generator facility. A
278
306
  generator, also known as a sequence, provides a means of creating a list of
@@ -285,8 +313,76 @@ The Blob class is returned as part of the Row object data obtained from a
285
313
  ResultSet. The class wraps the concept of a binary large object stored in the
286
314
  database. Consult the API documentation for further information.
287
315
 
288
- The FireRubyException class is the error class used by the FireRuby library
289
- whenever it hits trouble. If an exception is raised by the FireRuby code then
290
- its extremely likely that it will be an instance of this class. The class
291
- provides a means of finding out a little more about what exactly has gone
292
- wrong. Again, consult the API documentation for more details.
316
+ === Errors
317
+
318
+ Whenever a problem occurs within a FireRuby library class then it is likely that
319
+ a FireRubyException will be thrown. The FireRubyException class is the error
320
+ class used by the FireRuby library whenever it hits trouble. The class provides
321
+ a means of finding out a little more about what exactly has gone wrong. Again,
322
+ consult the API documentation for more details.
323
+
324
+ === Firebird Service Manager
325
+
326
+ The FireRuby library provides a set of class that provide for an interaction
327
+ with the Firebird service manager. This interaction allows for the execution of
328
+ tasks, such as the backing up of a database, on the database server. To execute
329
+ such tasks against the service manager for a Firebird instance you first need
330
+ to obtain a ServiceManager class instance. This can be done as follows...
331
+
332
+ sm = ServiceManager.new('localhost')
333
+
334
+ The constructor for the ServiceManager class takes a single parameter that is
335
+ the host name of the server running the Firebird instance. In the example above
336
+ this would be a local machine but could be any machine that can be reached over
337
+ the network (NOTE: although Firebird supports a number of underlying transport
338
+ protocols in accessing a service manager currently only TCP/IP is supported for
339
+ the FireRuby library).
340
+
341
+ The next step in executing service manager tasks involves connecting your
342
+ ServiceManager object to the service manager for a Firebird instance. To do this
343
+ you must supply a user name and password. The user name and password used must
344
+ be a user that exists on the Firebird instance. The user you connect as can
345
+ affect the access to services that you receive. For example, to connect as the
346
+ database administrator you might do the following...
347
+
348
+ sm.connect('sysdba', 'masterkey')
349
+
350
+ Assuming that this succeeds you are now ready to execute tasks through your
351
+ ServiceManager object. Within the FireRuby library individual task are broken
352
+ out into separate classes. For this release (0.3.0) there are four task classes
353
+ provided in the library - Backup, Restore, AddUser and RemoveUser. I think the
354
+ class names are relatively self explanatory but if you want more information
355
+ consult the API documentation for a class.
356
+
357
+ To use the task classes you construct a class instance, configure it as you may
358
+ need and then execute it. Here's an example of going through this procedure to
359
+ create a database backup...
360
+
361
+ b = Backup.new('c:\database\work.fdb', 'c:\temp\work.bak')
362
+ b.metadata_only = true
363
+ b.execute(sm)
364
+
365
+ The first list creates the new Backup object. The first parameter passed to this
366
+ call is the path and name of the primary file of the database to be backed up
367
+ (NOTE: All paths are relative to the database server). The second parameter is
368
+ the path and name of the database backup file to be created. The second line
369
+ sets an attribute on the class to indicate that only the metadata (i.e. it's
370
+ schema but not it's data) for the specified database should be included in the
371
+ backup. The final line begins the execution of the backup task on the database
372
+ server. This will block until completion.
373
+
374
+ Its also possible to execute a batch of tasks against a service manager. To do
375
+ this you would accumulate the tasks to be executed and then pass them all at the
376
+ same time to the ServiceManager#execute method, like so...
377
+
378
+ t = Array.new
379
+ t.push(Backup.new('c:\database\work.fdb', 'c:\temp\work.bak'))
380
+ ...
381
+ # Create more tasks here and add them to the array.
382
+
383
+ sm.execute(*t)
384
+
385
+ The tasks will be executed in the order they are specified to the ServiceManager
386
+ object. For the example above this would mean in the order they were added to
387
+ the array. For more details on the ServiceManager class and the various task
388
+ classes please consult the API documentation.
@@ -0,0 +1 @@
1
+ D
@@ -0,0 +1 @@
1
+ A D/FireRuby////
@@ -0,0 +1 @@
1
+ /var/cvs/fireruby/fireruby/doc/classes
@@ -0,0 +1 @@
1
+ :ext:paw220470@rubyforge.org:/var/cvs/fireruby
@@ -0,0 +1 @@
1
+ D
@@ -0,0 +1,7 @@
1
+ A D/Connection.src////
2
+ A D/Database.src////
3
+ A D/FireRubyError.src////
4
+ A D/Generator.src////
5
+ A D/ResultSet.src////
6
+ A D/Statement.src////
7
+ A D/Transaction.src////
@@ -0,0 +1 @@
1
+ /var/cvs/fireruby/fireruby/doc/classes/FireRuby
@@ -0,0 +1 @@
1
+ :ext:paw220470@rubyforge.org:/var/cvs/fireruby
@@ -0,0 +1 @@
1
+ /var/cvs/fireruby/fireruby/doc/classes/FireRuby/Connection.src
@@ -0,0 +1 @@
1
+ :ext:paw220470@rubyforge.org:/var/cvs/fireruby
@@ -0,0 +1 @@
1
+ /var/cvs/fireruby/fireruby/doc/classes/FireRuby/Database.src
@@ -0,0 +1 @@
1
+ :ext:paw220470@rubyforge.org:/var/cvs/fireruby
@@ -0,0 +1 @@
1
+ /var/cvs/fireruby/fireruby/doc/classes/FireRuby/FireRubyError.src
@@ -0,0 +1 @@
1
+ :ext:paw220470@rubyforge.org:/var/cvs/fireruby
@@ -0,0 +1 @@
1
+ /var/cvs/fireruby/fireruby/doc/classes/FireRuby/Generator.src
@@ -0,0 +1 @@
1
+ :ext:paw220470@rubyforge.org:/var/cvs/fireruby
@@ -0,0 +1 @@
1
+ /var/cvs/fireruby/fireruby/doc/classes/FireRuby/ResultSet.src
@@ -0,0 +1 @@
1
+ :ext:paw220470@rubyforge.org:/var/cvs/fireruby
@@ -0,0 +1 @@
1
+ /var/cvs/fireruby/fireruby/doc/classes/FireRuby/Statement.src
@@ -0,0 +1 @@
1
+ :ext:paw220470@rubyforge.org:/var/cvs/fireruby
@@ -0,0 +1 @@
1
+ /var/cvs/fireruby/fireruby/doc/classes/FireRuby/Transaction.src
@@ -0,0 +1 @@
1
+ :ext:paw220470@rubyforge.org:/var/cvs/fireruby
@@ -0,0 +1 @@
1
+ D
@@ -0,0 +1 @@
1
+ /var/cvs/fireruby/fireruby/doc/files
@@ -0,0 +1 @@
1
+ :ext:paw220470@rubyforge.org:/var/cvs/fireruby
data/lib/CVS/Entries CHANGED
@@ -1,4 +1,4 @@
1
1
  /fireruby.bundle/1.1.1.1/Tue Mar 15 10:36:28 2005//
2
2
  /mkdoc/1.2/Mon Mar 21 08:53:22 2005//
3
- /src.rb/1.2/Mon Mar 21 08:53:22 2005//
3
+ /src.rb/1.3/Mon May 9 09:16:06 2005//
4
4
  D
data/lib/fireruby.bundle CHANGED
Binary file