iotaz 0.1.0

data/doc/PERSISTENT

@@ -0,0 +1,137 @@
+= The Iotaz::Persistent Class
+
+Due to the nature and usage of the Iotaz::Persistent module it is difficult to
+get rdoc to generate appropriate documentation for the methods that it adds to
+classes that include it. To bypass this problem I have come up with this file
+that will act as a stand-in thats used to generate documentation. The Persistent
+module is documented separately in the API documentation but this documentation
+is aimed at those who will be using the module.
+
+== Class Methods
+
+Including the Iotaz::Persistent module incorporates the following class level
+methods into a class definition...
+
+==== Persistent::iotaz_meta_data
+
+This method simply returns the class instance variable @@iotaz_meta_data that
+is also defined whenever a class includes the Persistent module.
+
+==== Persistent#persistent_attr(name, column=nil, readonly=false)
+
+This method is used to define a new persistent attribute within a class. The
+method creates the attribute in the class definition and populates the meta-data
+object with the details of the attribute.
+
+===== Parameters
+name::      Either a String or a Symbol defining the name of the attribute to
+            be added to the class.
+column::    A string containing the name of the database column that the
+            attribute maps to. Defaults to nil to indicate that the attribute
+            name and column name are the same.
+readonly::  As Iotaz requires both a getter and a setter for a persistent
+            attribute this parameter allows you to specify that you want
+            to make the setter private. Defaults to false.
+            
+==== Persistent#sequence_attr(name, column=nil, key=true, source=nil, readonly=true, create=true, update=false)
+
+This method is used to define a new persistent generated attribute within a
+class. The method defines an attribute that expects to get its value from a
+sequence within the database.
+
+===== Parameters
+name::      Either a String or a Symbol defining the name of the attribute to
+            be added to the class.
+column::    A string containing the name of the database column that the
+            attribute maps to. Defaults to nil to indicate that the attribute
+            name and column name are the same.
+key::       A boolean indicating whether the sequence value is part of the
+            primary key for the class/table. Defaults to true.
+source::    A string containing the name of the sequence in the database that
+            will be used to generate value for the attribute. This defaults to
+            nil to indicate a default name that uses the class name suffixed
+            with 'ID_SQ'.
+readonly::  As Iotaz requires both a getter and a setter for a persistent
+            attribute this parameter allows you to specify that you want
+            to make the setter private. Defaults to true.
+create::    A boolean to indicate whether the sequence value should be generated
+            on insert. Defaults to true.
+update::    A boolean to indicate whether the sequence value should be generated
+            on updates. Defaults to false.
+            
+==== Persistent#date_attr(name, column=nil, create=true, update=false, value='TODAY', readonly=true)
+
+This method is used to define a new persistent generated attribute within a
+class. The method defines an attribute that expects to be stored in a column of
+SQL type DATE.
+
+===== Parameters
+
+name::      Either a String or a Symbol defining the name of the attribute to
+            be added to the class.
+column::    A string containing the name of the database column that the
+            attribute maps to. Defaults to nil to indicate that the attribute
+            name and column name are the same.
+create::    A boolean to indicate whether the date value should be generated
+            on insert. Defaults to true.
+update::    A boolean to indicate whether the date value should be generated
+            on updates. Defaults to false.
+value::     A string containing the default value to be assigned to the date
+            column whenever it needs to be generated. This defaults to 'TODAY'
+            although 'YESTERDAY' and 'TOMORROW' are also valid.
+readonly::  As Iotaz requires both a getter and a setter for a persistent
+            attribute this parameter allows you to specify that you want
+            to make the setter private. Defaults to true.
+
+==== Persistent#time_attr(name, column=nil, create=true, update=false, readonly=true)
+
+This method is used to define a new persistent generated attribute within a
+class. The method defines an attribute that expects to be stored in a column of
+SQL type TIME.
+
+===== Parameters
+
+name::      Either a String or a Symbol defining the name of the attribute to
+            be added to the class.
+column::    A string containing the name of the database column that the
+            attribute maps to. Defaults to nil to indicate that the attribute
+            name and column name are the same.
+create::    A boolean to indicate whether the time value should be generated
+            on insert. Defaults to true.
+update::    A boolean to indicate whether the time value should be generated
+            on updates. Defaults to false.
+readonly::  As Iotaz requires both a getter and a setter for a persistent
+            attribute this parameter allows you to specify that you want
+            to make the setter private. Defaults to true.
+
+==== Persistent#timestamp_attr(name, column=nil, create=true, update=false, readonly=true)
+
+This method is used to define a new persistent generated attribute within a
+class. The method defines an attribute that expects to be stored in a column of
+SQL type TIME.
+
+===== Parameters
+
+name::      Either a String or a Symbol defining the name of the attribute to
+            be added to the class.
+column::    A string containing the name of the database column that the
+            attribute maps to. Defaults to nil to indicate that the attribute
+            name and column name are the same.
+create::    A boolean to indicate whether the timestamp value should be
+            generated on insert. Defaults to true.
+update::    A boolean to indicate whether the timestamp value should be
+            generated on updates. Defaults to false.
+readonly::  As Iotaz requires both a getter and a setter for a persistent
+            attribute this parameter allows you to specify that you want
+            to make the setter private. Defaults to true.
+
+            
+==== Persistent#table_name(name)
+
+This method is used to update the table name associated with a persistent class
+definition. At the moment calling the method requires that self be used in the
+invocation (i.e. self.table_name = '...'). Not sure why this is and if it can be
+eliminated I will.
+
+===== Parameters
+name::  A string containing the new table name for the class.

data/doc/README

@@ -0,0 +1,470 @@
+== Iotaz
+
+The Iotaz library provides object-relational mapping functionality for the Ruby
+programming language. Initially the library only supports the mapping of objects
+to the Firebird open source RDBMS but this may be extended in future.
+
+== Requirements
+
+As was stated previously, the Iotaz library provides mapping facilities to the
+Firebird database system. The FireRuby library is employed to provide the
+interface functionality to the database system. This library is free and can be
+obtained from the Ruby Forge web site at...
+
+   http://rubyforge.org/projects/fireruby/
+   
+Like the Iotaz library, FireRuby is available as a gem installation. This gem
+should be installed before the Iotaz library gem can be used.
+
+== What Is It?
+
+The Iotaz library provides functionality to map between the attribute of a Ruby
+object and a table in the database. The mapping between the object instance and
+the database table allows for record creation, update and deletion. A query
+interface is also provided. The library is aimed at reducing the time it takes
+to develop a set of classes that can be persisted and maintained within the
+context of a relational database system.
+
+== Why Was It Created?
+
+Iotaz is not the first object-relational mapping software. In fact, several
+already exist for Ruby alone. That being the case, why was there a need to
+develop another library. There are several reasons for doing this.
+
+- Iotaz works with the FireRuby library to interact with the Firebird database.
+  At the time of creation no other mapping software was available that used
+  this library. Other libraries did translate the object-relational paradigm
+  on to Firebird through older libraries for Interbase. The older libraries
+  for Firebird offer a less extensive set of functionality than the FireRuby
+  library and Iotaz was written to take advantage of the additional feature
+  set.
+   
+- Object-relational mapping software varies from the completely automatic to
+  the deeply manual. Automatic libraries determine a lot of the information
+  for the mapping from the existing code base, making a lot of choices based
+  on a predefined set of rules. Manual libraries frequently require that the
+  code follow specific practices. I felt that neither end of the scale was
+  completely satisfactory, so Iotaz is an attempt to find a happy medium that
+  allows for a degree of automation but manual control when it is needed.
+   
+- The author of Iotaz also authored the FireRuby library, so there is a degree
+  of self interest in the matter.
+  
+== So What Does It Hope To Achieve?
+
+There were a number of goals that I hope to achieve in writing this library. The
+following is a list of the ones I consider the most important ones...
+
+- To simplify the process of creating classes which can be stored in a database.
+  By this I mean, the amount of code that needs to be written to achieve this
+  goal should be an absolute minimum.
+  
+- To automate tasks as much as possible but not to preclude manual intervention
+  if there is even the potential that it will be needed or wanted.
+  
+- To keep the complexity of the library itself to an absolute minimum. Theres
+  no point in creating software to simplify a task if the learning curved
+  associated with it is mountainous.
+  
+- To provide an add-on to the FireRuby library. Not everyone wants to or can
+  work at the SQL level.
+  
+- To provide a foundation for later development work. The FireRuby and Iotaz
+  libraries are infrastructure in a slightly grander plan.
+  
+Development work of a substantial nature frequently involves a degree of
+compromise so I can't guarantee that I have stuck absolutely to these goals but
+they do provide a point of reference for those times when an issue arises.
+   
+== So How Does It work?
+
+One of the primary goals of the Iotaz library was to make the passage from a
+plain Ruby object to an object that has database backed persistence capabilities
+a relative quick and painless one. Perhaps the best way to illustrate this is
+through an example.
+
+=== A First Example
+
+For the purposes of the example, lets assume that we have developed a class that
+is to be used to hold information about a customer account. This object holds
+details of the account number, the customer name, the date/time the account was
+created and the last date/time that the account details were updated. Given this
+object we decide that we are going to create a database table that will be used
+to store this information that will be created with a SQL statement that looks
+something like...
+
+   CREATE TABLE ACCOUNT
+   (
+      ID       INTEGER NOT NULL PRIMARY KEY,
+      NUMBER   VARCHAR(30) NOT NULL,
+      CUSTOMER VARCHAR(100),
+      CREATED  TIMESTAMP NOT NULL,
+      UPDATED  TIMESTAMP
+   )
+
+First thing to note here is that we have made the decision to use a surrogate
+key, in the form of the ACCOUNTID field. A surrogate key is basically a unique
+identifier for a database record that fulfills no other purpose than being the
+record key. This is generally regarded as a good practice in database design.
+We could, alternatively, have used the ACCOUNTNO field as our primary key for
+the table but for the purposes of this example the surrogate key is more
+illustrative.
+
+Given the database table definition will draw up a Ruby Account class that
+looks as follows...
+
+   require 'rubygems'
+   require_gem 'iotaz'
+   
+   include Iotaz
+
+   class Account
+      attr_accessor :id, :number, :customer, :created, :updated
+      
+      def initialize(number, customer)
+         @number   = number
+         @customer = customer
+      end
+      
+      protected :id=, :created=, :updated=
+   end
+
+To start with we have added the commands to make the functionality of the Iotaz
+library. Iotaz is provided as a gem package and the requires and include line at
+the beginning loads the functionality into the current context for use.
+
+The next thing to note are that we do not provide values to the constructor for
+three attributes within the object - id, created and updated. The reason for
+this is that we expect these values to be generated by the database server. The
+id value can be generated off a database sequence, guaranteeing that it will
+have a unique value for each Account object stored. The created and update
+values are timestamps and we'd like to use the database server date/time
+capabilities to eliminate the difference between client clock settings. As
+these attributes are going to be automatically generated we will provide
+accessors for them. To facilitate the Iotaz library we must also provide the
+mutators for them but to lessen the possibility of these methods being abused
+or misused we can make them private or protected, as we have done above.
+
+Alright, starting from this point, how do we get to the point were we can save
+objects of this class into our database. All we need to do, in fact, is define
+one extra method, such that the class becomes...
+
+   class Account
+      attr_accessor :id, :number, :customer, :created, :updated
+      
+      def initialize(number, customer)
+         @number   = number
+         @customer = customer
+      end
+      
+      def Account.iotaz_meta_data
+         IotazMetaData.scan(Account)
+      end
+      
+      protected :id=, :created=, :updated=
+   end
+
+Thats it, we now have the capability to save this class to the database. You're
+probably thinking that the extra method doesn't do an awful lot so how can it
+possibly store our account data to the database. Well, you're right, there is a
+little more to it before we can actually have our objects saved into the
+database table.
+
+The Iotaz library handles all interactions with the database through an object
+of the Session class. Session objects are, funnily enough, created using the
+SessionFactory object. You create a SessionFactory by calling it's new method
+and specifying a set of configuration parameters as a Hash object. At it's
+simplist this can look like...
+
+   factory = SessionFactory.new({"iotaz.database"=> "firebird",
+                                 "iotaz.firebird.user" => "sysdba",
+                                 "iotaz.firebird.password" => "masterkey"
+                                 "iotaz.firebird.database" => "accounts.fdb"})
+                                  
+This creates a factory that will attach to a local database file called
+account.fdb using the user name sysdba and the password masterkey (the defaults
+for the Firebird database). There are other settings that can be used here but
+in this case they are allowed to default. Once you have an instance of the
+SessionFactory class, obtaining a session is as simple as...
+
+   session = factory.start
+
+So we've created a session factory and used that to manufacture a session. So
+what do we need to do with it to push the details of our account to the
+database? Well before we can do that theres one step we must do in the database
+first. Earlier we mentioned that we'd like to have the id field for our Account
+objects automatically generated from a database sequence. We need to create that
+sequence. For reasons that will be explained later the sequence we will create
+will be called ACCOUNT_ID_SQ. For Firebird we create a sequence using a command
+such as the following...
+
+   CREATE GENERATOR ACCOUNT_ID_SQ;
+
+Finally, we're ready to save the account object to the database. We do that by
+getting the session object to do all the work, like this...
+
+   session.save(account)
+
+That really is it. Assuming the database is up and running, the user name and
+password are correct then the account record should now be saved into the
+ACCOUNT table in the database. Not only that but the values of the id and
+created attributes for our account object will have been automatically updated
+with the values they were assigned by the database, saving the need to
+explicitly recover them.
+
+=== Revisiting The Example
+
+In the previous section we created a simple Account class in the manner that
+we normally create them for Ruby. This section will revisit the code and attempt
+to expanded on what was done and why it was done.
+
+The first step we took towards making our Account class persistable was the
+addition of the following class method to the Account class...
+
+   def Account.iotaz_meta_data
+      IotazMetaData.scan(Account)
+   end                                 
+   
+This function makes a call to the class function IotazMetaData#scan. What is it
+that this method does? Well, this function is part of the automation facilities
+for the Iotaz library. The function scans the class passed to it for attributes
+and uses them to automatically generate the meta-data that will be used when
+moving the data for class objects to or from the database. The method follows a
+simple set of rules...
+
+- If the class possesses a method that ends with '=' and it possesses a method
+  with the same name minus the '=' then these are taken to be the mutator and
+  accessor for an attribute that should be persisted.
+
+- If the class possesses an attribute accessor for an attribute called id then
+  this is taken to be the key value for the class. It will be interpreted as
+  being a generated attribute (i.e. it's value will be created by the database)
+  using a sequence name of <class name>_ID_SQ.
+  
+- If the class possesses attributes called created or updated these will be
+  assumed to be timestamp values for the class that are automatically generated
+  by the database. The created attribute will be assigned a value whenever the
+  object is first inserted into the database and the updated attribute will be
+  assigned a value whenever the objects database record is altered.
+  
+The IotazMetaData class contains data detailing the attributes of a class from
+the perspective of storing them in a database table. The IotazMetaData#scan
+method is a convenient mechanism for automatically generating an instance of
+this class from the details of a Ruby class but the meta-data generated by this
+method may occasionally be insufficient. For example, if an attribute has a name
+that clashes with a SQL reserved word or if you have a naming scheme for your
+database tables or fields that differs from the expected column names generated
+by the method. In this case it is possible to manually generate the meta-data
+to suit your needs and this will be detailed next.
+
+An IotazMetaData object basically has three elements to it. The first is the
+name of the database table that the meta-data object will refer to. The second
+is a list of strings that contain the names of the key fields for object mapped
+onto the table. This list will contain the names of the attributes the values
+of which can be used to uniquely identify a row in the table. The final aspect
+of an IotazMetaData object is the definitions for the attributes themselves.
+
+An IotazMetaData object may hold multiple Attribute objects. An Attribute object
+contains the information on how to get and set an attribute value from a class
+instance as well as details on the database table field that the attribute maps
+to and, optionally, the type of value that the field can hold. Attributes come
+in two types, normal attributes and generated attributes. A generated attribute
+
+All of these objects can be created manually. So, for example, to manually
+create the IotazMetaData object that was automatically created for the example
+detailed above the code would be...
+
+   metadata = IotazMetaData.new(Account)
+   metadata.add_attribute(GeneratedAttribute.new('id', 'SEQUENCE', 'INSERT', 'USER_ID_SQ'))
+   metadata.add_attribute(Attribute.new('name'))
+   metadata.add_attribute(Attribute.new('number'))
+   metadata.add_attribute(GeneratedAttribute.new('created', 'TIMESTAMP', 'INSERT', 'NOW'))
+   metadata.add_attribute(GeneratedAttribute.new('updated', 'TIMESTAMP', 'UPDATE', 'NOW'))
+
+As can be seen, this is a lot more verbose than the automatic option but it also
+gives a greater deal of control. It is possible, using this method, to specify
+the use of non-default table, column or sequence names. Of course, its alway
+possible to use a hybrid between the automatic and manual methods. A default
+meta-data object could be generated automatically and then edited manually to
+customise the elements that don't adhere to the standard expectations. So, for
+example, if you wanted all your table to be prefix with 'MY_' and your sequences
+to end in '_GEN', this could be achieved as follows...
+
+   metadata         = IotazMetaData.scan(Account)
+   metadata.table   = "MY_#{metadata.table}"
+   attribute        = metadata.get_attribute('id')
+   attribute.source = attribute.source.gsub(/_SQ/, '_GEN')
+
+For more information of the Iotaz and Attribute classes consult the Iotaz API
+documentation. The next aspect of the example covered the use of sessions for
+interactions with the database and this will be expanded upo next.
+
+A session, in logical terms, represents a conduit for interations with the
+database. The first step in using a session is to obtain an instance of the
+SessionFactory class. The SessionFactory class provides a centralised location
+for the manufacture of Session objects for a given database. In creating a
+SessionFactory you need to specify everything that is needed for the factory
+to interact with the database - the type of database that will be used and the
+details that will be used to connect with the database. These details are
+provided to the SessionFactory constructor as a Hash mapping specific strings
+to the values for use in interacting with the database. See the API
+documentation for more information of the names and uses of the parameters that
+are accepted.
+
+Once a SessionFactory object has been created it can be used to obtain Session
+objects. It should be noted that the SessionFactory class is considered thread
+safe but the Session class is not. A Session object provides a set of functions
+to allow for the maintenance of the persistent details associated with objects.
+A Session object also provides the facilities to start, commit or roll back
+transactions.
+
+Under normal circumstances, if you make a method call on a Session object the
+database interaction takes place immediately. So if, for example, you request
+that a session save an object, it will be immediately saved to the database.
+When you start a transaction on a session things behave differently. If you
+execute a save on a session on which a transaction has been initiated then the
+objects details are not immediately pushed to the database. In fact the objects
+details won't be pushed to the database until you call for a commit of the
+outstanding transaction. This delayed application of the object data has some
+side effects that are not immediately obvious.
+
+If you save an object as part of a session transaction generated field values
+that will be provided by the database server will not get filled out until the
+transaction is committed. Field values generated as for sequences are fetched
+immediately and aren't effected by this side effect. Generated date, time and
+timestamp fields, however, are affected and a value for these fields will not
+be available from their respective object until after the session transaction
+has been committed. This is something that you may need to be wary of.
+
+=== So I've Save My Object, How Do I Get It Back?
+
+Alright, we've saved the account, whats required to get it back from the
+database when I need it. Well, thankfully, it requires no more code. To fetch
+the account back we need to interact with the database therefore we must use a
+Session object. To fetch an object back we must provide values for each of its
+key attributes. The meta-data keys provide the set of attributes that are
+required to uniquely identify an object instance. In our case we only have one
+key attribute, the id attribute. If an Account we had created earlier had a key
+value of 23 then we could retrieve it as follows...
+
+   account = Session.load(Account, 23)
+   
+This will fetch the details for the account we had created from the database and
+return an Account object populated with those details.
+
+=== I've Made Changes To My Object, How Do I Get Them Into The Database?
+
+This couldn't be easier and it requires no extra code in the Account class. You
+simply pass your updated object to the Session#save method again. The save
+method performs a check to see whether any of the generated elements of the
+objects keys are nil. If they are then it tries to create a new table record. If
+they are all non-nil then it will attempt an update of an existing database
+record.
+
+=== How Do I Remove Database Records For Objects?
+
+This is done using the Session#delete method. This method takes a single
+parameter, which should be the object to be deleted. The session will formulate
+the appropriate SQL to eliminate the database record for the object.
+
+== A Second Example
+
+In the previous example we took the shortest and easiest route to get to the
+point where we could persist our objects to the database. This appraoch is fine
+for quick work but suffers from the fact that each time the
+Account#iotaz_meta_data method is invoked (which could, potentially, be quite a
+frequent occurence) the class is scanned to determine its details. This isn't
+exactly efficient.
+
+Its possible that we could declare the metadata object as a class attribute and
+create it only once. This approach suffers from the fact that it raises issues
+if you want the tweak the default values. We could, always just create and tweak
+it once inside the method that fetches it and then simply return it for all
+subsequent calls. This would work but it's really starting to interfere with the
+code and raises potentially issues for uses in a multithread environment.
+
+Well, luckily, the Iotaz library offers another alternative. We can rewrite the
+Account class as follows...
+
+   class Account
+      include Iotaz::Persistent
+      
+      sequence_attr   :id
+      persistent_attr :number
+      persistent_attr :customer
+      timestamp_attr  :created
+      timestamp_attr  :updated, nil, false, true
+      
+      def initialize(number, customer)
+         @number   = number
+         @customer = customer
+      end
+   end
+   
+This has completely changed the definition of the class from what we previously
+devised. We've dropped the explicit attribute definitions, the iotaz_meta_data
+class method and the alterations to the accessibility of attributes that we
+wanted to make read only. Despite this, we have a class that possesses exactly
+the same functionality.
+
+The first thing to notice is that we have include the Persistent module from
+the Iotaz library into our class. This has a number of results. Firstly it
+defines and initializes a class variable called @@iotaz_meta_data. Next it
+provides the class with an iotaz_meta_data method which simply returns the
+@@iotaz_meta_data object. Finally it inserts a number of singleton methods into
+the Account class. These are used in the lines following the inclusion of the
+Persistent module to define the class attributes.
+
+The first line following the include declares and attribute for the Account
+class called id. As the sequence_attr method was used to create it this will
+be added to the classes meta-data as a generated attribute that employs a
+sequence generated value.
+
+The next two lines declare to standard attributes that we want to be included
+in the data we're going to store in the database. Using the persistent_attr
+method not only declares the attribute but updates the class meta-data with
+their details. The final two lines declare two timestamp based generated
+attributes, again storing their details in the class meta-data. The updated
+attribute is a little different because there are a number of value specified
+after the attribute itself. These are extra parameters they are used to
+configure the details for the attribute.
+
+The first extra parameter would be the database column name that the attribute
+would use. By specifying nil here we are saying that we're sticking with the
+default. The next two fields control when the values for the attribute get
+generated. The first represents generation on insertion and the second
+represents generation on update. In this case we are specifying that the
+attribute gets generated for updates but not for inserts.
+
+The remainder of the code is the same constructor method that we supplied for
+the previous incarnation of this class. By using this method we have effectively
+eliminated the problems we highlighted with our previous approach and yet we
+have the same functionality for no extra code. Most of the method provided by
+the Persistent class takes extra parameters for things like database column
+names. Consult the API documentation for more information. For details of what
+the Iotaz::Persistent module adds to an including class select the link for
+doc/PERSISTENT in the files section of the API documentation.
+
+== Pro's an Con's
+
+The Iotaz library is geared at storing all of the data for a class instance in
+a single database table (sometimes referred to as the active record pattern).
+If the details for an object must be stored across multiple tables or if the
+class acts as an aggregation point for other persistent values then care must
+be taken in the class code to handle this.
+
+The library, in it's current incarnation, also makes no representation towards
+inter-class and, therefore, inter-table relationships. A later release of the
+library may offer some capabilities in this line but not at the moment. Working
+with such relationships introduces concepts such as persistence by reachability
+and object graphs and this will have to wait for now.
+
+== Acknowledgements
+
+The design and implementation of the Iotaz library has been heavily influenced
+by the Hibernate library for Java. Given that the relationship between Java and
+Ruby advocates seems a little bit of a hot topic at the moment I'm not sure that
+it will necessarily stand in my favour to admit this. Nevertheless, having used
+the Hibernate library, I consider it an excellent piece of software and an
+exemplary open source project.
+