ramen 0.4.0

data/lib/ramen/metadata/table.rb

@@ -0,0 +1,202 @@
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+
+module Ramen::Metadata
+  # Table contains collections of Column, ForeignKey, Index, KeyConstraint, and
+  # PrimaryKey objects.  Attributes available for Table are database engine specific.  
+  # Ramen only requires the attributes table_name and table_id.  See
+  # RowDataGateway for more information.
+  #
+  # See Database for a description of how Table fits in the Ramen collection
+  # hierarchy.
+  #
+  # Links: readme.txt[link:files/readme_txt.html]; source[link:rcov/lib-ramen-table_rb.html]
+  #
+  class Table < Ramen::RowDataGateway
+    # :section: External Methods
+    # The following methods are intended for use by Ramen's clients.
+
+    # Comparison, returns -1,0,+1, compares table_name
+    def <=> other
+      Ramen::RowDataGateway.compare( table_name, other )
+    end
+    
+    # column() #=> RamenHash reference
+    #
+    # This attribute provides access to a RamenHash of all Column objects in the
+    # Table.  The hash is indexed by column_name and column_id.
+    #
+    # usage:
+    #   require 'lib/ramen'
+    #   db = Ramen.create( configuration )
+    #   schema = db.schema['Sales']  #=> #<Schema schema_name='Sales', schema_id='1234567' ...>
+    #   table = schema.table['Products'] #=> #<Table table_name='Products', table_id='1111111111'> 
+    #   column = table.column['Price'] #=> #<Column...>
+    #
+    def column
+      @columns
+    end
+        
+    # foreign_key() #=> RamenHash reference
+    # 
+    # fk() #=> RamenHash reference
+    #
+    # This attribute provides access to a RamenHash of all ForeignKey objects
+    # in the Table.  The hash is indexed by foreign_key_id and foreign_key_name.
+    #
+    # usage:
+    #   require 'lib/ramen'
+    #   db = Ramen.create( configuration )
+    #   schema = db.schema['Sales']
+    #   table = schema.table['Products']
+    #   fk = table.fk['FK_PRODUCTS_ORDERS'] #=> #<ForeignKey...>
+    #
+    def foreign_key
+      @foreign_keys
+    end
+    alias fk foreign_key
+    
+    # index() #=> RamenHash reference
+    #
+    # This attribute provides access to a RamenHash of all Index objects
+    # in the Table.  The hash is indexed by index_id and index_name.
+    #
+    # usage:
+    #   require 'lib/ramen'
+    #   db = Ramen.create( configuration )
+    #   schema = db.schema['Sales']
+    #   table = schema.table['Products']
+    #   index = table.index['PK_PRODUCTS_ID'] #=> #<Index...>
+    #
+    def index
+      @indexes
+    end
+    
+    # key_constraint() #=> RamenHash reference
+    #
+    # key () #=> RamenHash reference
+    #
+    # This attribute provides access to a RamenHash of all KeyConstraint objects
+    # in the Table.  The hash is indexed by key_constraint_id and 
+    # key_constraint_name.
+    #
+    # usage:
+    #   require 'lib/ramen'
+    #   db = Ramen.create( configuration )
+    #   schema = db.schema['Sales']
+    #   table = schema.table['Products']
+    #   key_constraint = table.key['UK_PRODUCTS_NAME'] #=> #<KeyConstraint...>
+    #
+=begin
+    def key_constraint
+      @key_constraints
+    end
+    alias key key_constraint
+=end
+    
+    # primary_key() #=> PrimaryKey reference
+    # 
+    # pk() #=> PrimaryKey reference
+    #
+    # This attribute provides access to a RamenHash of all ForeignKey objects
+    # in the Table.  The hash is indexed by foreign_key_id and foreign_key_name.
+    #
+    # usage:
+    #   require 'lib/ramen'
+    #   db = Ramen.create( configuration )
+    #   schema = db.schema['Sales']
+    #   table = schema.table['Products']
+    #   fk = table.fk['PK_PRODUCTS'] #=> #<PrimaryKey...>
+    #
+    def primary_key
+      @primary_key
+    end
+    alias pk primary_key
+    
+    # inspect() #=> string
+    #
+    # Returns a nice and brief output of the table and it's tables.  This
+    # was redefined since the default inspect would typically output many
+    # pages of details.
+    #
+    # Each table is listed by id:name.
+    #
+    # usage:
+    #   db = Ramen.create()
+    #   schema = db.schema['HumanResources']
+    #   table = schema.table['Employee']
+    #   table.inspect  #=> "#<Ramen::Table columns=[1:EmployeeID, 2:NationalIDNumber, ..."
+    #
+    def inspect
+      children = []
+      @columns.each_by_id do |id,col|
+        children << (id.to_s+':'+col.column_name)
+      end
+      to_s[0..-2]+' '+table_name+' columns=['+children.join(', ')+']>'
+    end
+    
+    # :section: Internal Methods
+    # The following methods are for Ramen's internal use.  They
+    # are not intended for clients of Ramen to use.
+    
+    def initialize( record, database )
+      super( record, database )
+      @columns         = Ramen::RamenHash.new( Column )
+      @foreign_keys    = Ramen::RamenHash.new( ForeignKey )
+      @indexes         = Ramen::RamenHash.new( Index )
+      @key_constraints = Ramen::RamenHash.new( KeyConstraint, 'key' )
+      @primary_key     = nil
+    end
+    
+    # add_to( database )
+    #
+    # Add self to the given database.  (Choosing Message; Double Dispatch pattern)
+    # (Kent Beck. Smalltalk Best Practices Patterns. Perntice Hall PTR, Upper Saddle River, NJ 1997)
+    def add_to( database )
+      database.schema[ self.table_schema ].add_table( self )
+    end
+
+    # add_column( obj ) #=> obj
+    #
+    # Adds the column to this table.  Throws a RamenError if the obj
+    # is not a Column.
+    def add_column( column )
+      @columns.add( column )
+    end
+    
+    # add_foreign_key( obj ) #=> obj
+    #
+    # Adds the foreign key to this table.  Throws a RamenError if the obj
+    # is not a ForeignKey.
+    def add_foreign_key( fk )
+      @foreign_keys.add( fk )
+    end
+    
+    # add_index( obj ) #=> obj
+    #
+    # Adds the index to this table.  Throws a RamenError if the obj
+    # is not a Index.
+    def add_index( index )
+      @indexes.add( index )
+    end
+    
+    # add_key_constraint( obj ) #=> obj
+    #
+    # Adds the key constraint to this table.  Throws a RamenError if the obj
+    # is not a KeyConstraint.
+=begin
+    def add_key_constraint( obj )
+      @key_constraints.add( obj )
+    end
+=end
+    
+    # set_primary_key( obj ) #=> obj
+    #
+    # Sets the primary key for this table.
+    def set_primary_key( key )
+      @primary_key = key
+    end
+  end
+end

data/lib/ramen/ramen_error.rb

@@ -0,0 +1,16 @@
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+
+module Ramen
+  # A class for all errors originating in Ramen code.  Subclass of StandardError.
+  # Errors throw by code which Ramen calls (DBI.execute for example) are not
+  # wrapped by RamenError, the original error is rethrown.  Only errors which
+  # Ramen creates are instances of this class.
+  #
+  # Links: readme.txt[link:files/readme_txt.html]; source[link:rcov/lib-ramen-ramen_error_rb.html]
+  #
+  class RamenError < StandardError 
+  end
+end

data/lib/ramen/ramen_hash.rb

@@ -0,0 +1,143 @@
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+module Ramen
+  
+  # A special hash that stores items of the same type.
+  # RamenHash indexes each item by its name and id.  By default, the
+  # name and id attributes are derived from the class name of the type
+  # RamenHash will collect.
+  #
+  # usage:
+  #   def SomeClass
+  #     attr_accessor :some_class_id, :some_class_name
+  #     def initialize( id, name )
+  #       @some_class_id = id
+  #       @some_class_name = name
+  #     end
+  #   end
+  #   hash = RamenHash.new( SomeClass )
+  #   hash.add( SomeClass.new(1,'One') )
+  #   hash['One'] #=> #<SomeClass @some_class_id=1 @some_class_name='One'>
+  #   hash[1]     #=> #<SomeClass @some_class_id=1 @some_class_name='One'>
+  #
+  # Links: readme.txt[link:files/readme_txt.html]; source[link:rcov/lib-ramen-ramen_hash_rb.html]
+  #
+  class RamenHash < Hash
+    include Enumerable
+    
+    # RamenHash#new(clazz, prefix) #=> ramen_hash
+    #
+    # Parameters:
+    # [clazz] the type which RamenHash will store.
+    # [prefix] (optional) the attribute prefix for indexing.
+    #
+    # RamenHash indexes each obj by *prefix*_id and *prefix*_name.  Where
+    # prefix defaults to the clazz's name converted by String#to_delimited_words.
+    #
+    # For example for Ramen.new( ForeignKey ), the hash is indexed by
+    # foreign_key_id and foreign_key_name.
+    #
+    # RamenHash makes []= private since assignment to an index is not allowed.
+    # Use add( obj ) instead.
+    #
+    def initialize( clazz, prefix = nil )
+      prefix ||= clazz.name.match( /[^:]*$/ )[0].to_delimited_words
+      @clazz = clazz
+      @id = "#{prefix}_id".to_sym
+      @name = "#{prefix}_name".to_sym
+      @ids = []
+      @names = [] # TODO Change to SortedArray
+    end
+  
+    # add( obj ) #=> obj
+    #
+    # Adds the object to the hash, ensuring it is stored
+    # based on name and id attributes.
+    #
+    # Throws a RamenError if the obj is not an instance of the class which
+    # RamenHash is collecting.
+    def add( obj )
+      unless obj.is_a? @clazz
+        raise RamenError, "can not add type to #RamenHash. type_added=#{obj.class}; type_allowed=#{@clazz}"
+      end
+    
+      if obj.respond_to?(@id) then
+        id = obj.send(@id)
+        id = id.downcase if id.respond_to?(:downcase)
+        @ids << id
+        self[id]=obj
+      end
+      
+      name = obj.send(@name)
+      name = name.downcase if name.respond_to?(:downcase)
+      @names << name
+      @names.sort! # TODO Change to SortedArray
+      self[name]=obj
+    end
+
+    # calls the block, passing the block objects stored in the hash (in name order)
+    #
+    def each()
+      @names.each do |name|
+        yield self[name]
+      end
+    end
+    
+    def each_by( keys )
+      keys.each do |key|
+        yield key, self[key]
+      end
+    end
+    private :each_by
+    
+    # calls the block, giving the block the item name and the item
+    #
+    # usage
+    #   hash.each_by_name do |name, obj|
+    #     puts name
+    #     puts obj.inspect
+    #   end
+    def each_by_name( &block )
+      each_by( @names, &block )
+      self
+    end
+    
+    # calls the block, giving the block the item id and the item
+    #
+    # usage
+    #   hash.each_by_id do |id, obj|
+    #     puts id
+    #     puts obj.inspect
+    #   end
+    def each_by_id( &block )
+      each_by( @ids, &block )
+      self
+    end
+    
+    def to_s
+      results = []
+      self.each_by_id do |key, value|
+        results << (key.to_s + ':' + self[key].send(@name) + '=>' + value.to_s)
+      end
+      results.join( ' ' )
+    end
+
+    def default( arg )
+      raise RamenError, "RamenHash(#{@clazz.name}) does not contain object for key. key=#{arg}. keys=#{keys.inspect}"
+    end
+    
+    def []( key )
+      key = key.downcase if key.respond_to?(:downcase)
+      super
+    end
+    
+    def []=( key, value )
+      key = key.downcase if key.respond_to?(:downcase)
+      super
+    end
+    private "[]=".to_sym
+    
+  end
+end

data/lib/ramen/ramen_module.rb

@@ -0,0 +1,52 @@
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+require 'dbi'
+
+=begin rdoc
+Ramen module is primarily a namespace containing all library
+classes and modules.
+
+Ramen is also useful for creating the Database instance
+
+Detailed documentation is available at http://ramen.rubyforge.org
+=end
+module Ramen
+
+  class << self
+    # Ramen.create( configuration ) #=> new Metadata::Database instance
+    #
+    # A constructor method which creates a database with the given :connection, :sql
+    # and :logger (see Home.new for details about the parameters and defaults).
+    #
+    # usage:
+    #
+    #   database = Ramen.create( :connection => DBI.connect(...), :sql => Sql2005.new )
+    #
+    # The configuration hash can include the following options:
+    #
+    # :connection => connection to use for database access; 
+    # default = no default, :connection is required
+    #
+    # :logger     => a logger, see DefaultLogger for an example;
+    # default = DefaultLogger
+    #
+    # :sql        => class which provides the sql statments;
+    # default = Sql2005
+    #
+    # Ramen does not hold on to the connection.  After this method returns, it
+    # is safe to close the connection or use it for other queries.  
+    #
+    # Links: readme.txt[link:files/readme_txt.html]; source[link:rcov/lib-ramen-ramen_module_rb.html]
+    #
+    def create( configuration={} )
+      connection = configuration[:connection]
+      configuration.delete(:connection)
+      if connection.nil?
+        raise RamenError.new( "Ramen.create called with :connection => nil." )
+      end
+      Metadata::Database.new(connection, Home.new( configuration ))
+    end
+  end
+end

data/lib/ramen/row_data_gateway.rb

@@ -0,0 +1,89 @@
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+module Ramen
+
+  # RowDataGateway implements a simple read-only Row Data Gateway pattern (Fow03).
+  # It simply creates a ruby attribute for each column in the data set row.
+  #
+  # RowDataGateway is the parent class for all classes which contain data from
+  # the database in Ramen.
+  #
+  # The attributes are derived from the row.  Thus to add or remove an attribute
+  # the query would need updating, not the Ruby code.
+  #
+  # RowDataGateway assumes the attributes will not clash with methods that
+  # already exist on Ruby classes.  For example, using 'id' or 'name'
+  # for columns is a bad idea since Ruby already defines these attributes.
+  # The query can rename such columns to something more appropriate (table_name
+  # for example).
+  #
+  # Subclasses:
+  #
+  # Column, ForeignKey, ForeignKeyColumn, Index, IndexColumn, KeyConstraint,
+  # Schema, Table
+  # 
+  # Bibliography:
+  # 
+  # (Fow03) Martin Fowler. Patterns of Enterprise Application Architecture.
+  # Addison Wesley Longman, Reading, MA, 2003.
+  #
+  # Links: readme.txt[link:files/readme_txt.html]; source[link:rcov/lib-ramen-row_data_gateway_rb.html]
+  #
+  class RowDataGateway
+    # :section: Internal Methods
+    # The following methods are for Ramen's internal use.  They
+    # are not intended for clients of Ramen to use.
+    
+    class << self
+      # add_attributes( name )
+      #
+      # Creates and maps attributes provided by the Array of column names.
+      # This is performed at the class level since all instances of the class
+      # in Ramen have the same columns.
+      #
+      # The name Array should give the name of each column in the same order
+      # contained in the row.
+      #
+      # usage:
+      #
+      #   def MyData < RowDataGateway
+      #   end
+      #
+      #   MyData.add_attributes( ['one','two','three'] )
+      #   my_data = MyData.new( [1,2,3], nil )
+      #   my_data.one #=> 1
+      #   my_data.two #=> 2
+      #   my_data.three #=> 3
+      #
+      def add_attributes( names )
+        (0...names.length).each do |index|
+          unless self.instance_methods.include? names[index]
+            attribute = names[index].downcase.to_sym
+            module_eval( "def #{attribute}() @record[#{index}]; end" )
+          end
+        end
+      end
+      
+      # Comparison, returns -1,0,+1, compares name attribute (schema_name,
+      # table_name, index_name, primary_key_name)
+      #
+      # Common code used by sub
+      def compare( name, other )
+        return nil if other.nil? 
+        result = other <=> name
+        (result.nil?) ? nil : -result
+      end
+    end
+    
+    # new( record, database ) #=> new RowDataGateway instance
+    #
+    # Initialize a new instance with the given record.  The database parameter
+    # is used by subclasses to add the instance to a Database.
+    #
+    def initialize( record, database )
+      @record = record
+    end
+  end
+end

data/lib/ramen/version.rb

@@ -0,0 +1,16 @@
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+
+module Ramen
+  #
+  # Links: readme.txt[link:files/readme_txt.html]; source[link:rcov/lib-ramen-version_rb.html]
+  #
+  module Version
+    MAJOR = 0
+    MINOR = 4
+    REVISION = 0
+    STRING = [MAJOR, MINOR, REVISION].join('.')
+  end
+end

data/lib/ramen.rb

@@ -0,0 +1,62 @@
+# Ramen
+#
+# Links: readme.txt[link:files/readme_txt.html]; source[link:rcov/lib-ramen_rb.html]
+#
+# License:
+# 
+# (The MIT License + Free Software Foundation Advertising Prohibition)
+#
+# Copyright (c) 2007 Gregory N. Houston
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+# 
+# Except as contained in this notice, the name(s) of the above copyright holders
+# shall not be used in advertising or otherwise to promote the sale, use or other
+# dealings in this Software without prior written authorization.
+unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+  $:.unshift(File.expand_path(File.dirname(__FILE__)))
+end
+
+# modules and classes
+require 'ramen/row_data_gateway'# superclass to metadata classes
+
+require 'ramen/metadata/metadata'
+require 'ramen/metadata/column'
+require 'ramen/metadata/database'
+require 'ramen/metadata/foreign_key'
+require 'ramen/metadata/foreign_key_column'
+require 'ramen/metadata/index'
+require 'ramen/metadata/index_column'
+require 'ramen/metadata/key_constraint'
+require 'ramen/metadata/primary_key'
+require 'ramen/metadata/primary_key_column'
+require 'ramen/metadata/schema'
+require 'ramen/metadata/table'
+
+require 'ramen/engine/engine'
+require 'ramen/engine/sql2005'
+require 'ramen/engine/mysql'
+
+require 'ramen/core'
+require 'ramen/default_logger'
+require 'ramen/ramen_error'
+require 'ramen/home'
+require 'ramen/ramen_hash'
+require 'ramen/ramen_module'
+require 'ramen/version'