Last Updated: 9/25/2001

A_View

Purpose

License

Description

Dependencies

Limitations

Performance Considerations

To Do

Usage

Class Methods

Instance Methods

Testing

A_Debug Usage

 

Purpose:

Provides a framework with examples for how to create views. A view allows you to collect and iterator over portions of one more tables, indexes, and/or views.

 

Description:

A view is basically a method that you create and register with the A_View class. This method iterates over rows in Tables, Indexes, and/or other Views and yields an A_Table_Data object. It is similar to the A_Table class in that you can connect and iterate over the rows in the view. I tired to keep the interface between the A_Table, A_Index, and A_View classes consistent. Since an A_View object is Ruby code that is created and registered at run time, they are not stored in the system catalog. Views are stored in a Hash inside the A_View class. You can iterate over all existing views by calling A_View.each. This class is Thread safe.

Inner joins, outer joins, and unions between and across many tables are easy to accomplish by creatively iterating over each table. How you construct the iterators is all important. There are examples of these in the test script described below in the Testing section.

 

Dependencies:

• a_debug.rb - this provides debugging messages for all of my Ruby code. See a_debug.html for more details.
• a_catalog.rb - the system catalog mutex is used for protecting updates to the Hash that stores all views with multiple threads.
• a_filesort.rb - this is used by the each_sorted method to allow you to iterate over rows in the view sorted.
• a_column.rb - the A_Table_Data class is used by the A_View class. The iterators yield an object of A_Table_Data.
• a_table.rb - this class is not directly dependant on the a_table.rb module but you can't create a view without table.

 

Limitations:

• Views are not updateable.

 

Performance Considerations:

• It is faster it iterate over an entire table than to iterate over an index that returns 40% or more of the rows in a table. Use indexes only when they help reduce the number of records by more than 40%.
• When building views that iterate over multiple tables, use the table (or iterator) that looks at the fewest number of records as the outer most iterator. The fewer the rows that are iterated over, the faster the view will perform.

 

To Do:

• Provide support for updateable views.

 

 Usage:

# This assumes you have created a table called Membership(member_id, first_name, last_name, status)

# create a method that iterates over rows in the Membership and yields rows for the view

def membership_view1(data_array, transaction=nil, min=nil, max=nil, update=nil)

# All parameters are required as listed

membership = A_Table.connect('membership')

membership.each(transaction, min, max) do |_m_|

data_array.member_id = _m_.member_id

data_array.name = _m_.first_name + ' ' + _m_.last_name

end

membership.disconnect

end

cols_ = [] # create an array of columns for the View, our view has two columns

cols_.push(A_Column.new('name', 'v', nil, nil, nil, nil, '%-40.40s'))

cols_.push(A_Column.new('member_id', nil, nil, nil, nil, nil, '%3d'))

# Create a view called memberhip_v1 using your new method

A_View.register('membership_v1', 'membership_view1', cols)

 

# connect an iterate over the view

v = A_View.connect('membership_v1')

v.each{|data_array| print "#{data_array}\n"}

v.close

 

Class Methods:

A_View.connect(view_name)

Alias for A_View.new().

A_View.create(view_name, method, column_array)

Alias for A_View.register().

A_View.drop(view_name)

Drop this view.

A_View.each()

Iterate over all views. Yields(view_name, view).

A_View.exists?(view_name)

Returns true if this view has been registered. Otherwise, returns false.

A_View.new(view_name)

Connect to an existing view. This creates a connection to an existing or registered view. This does not establish a new view. To actually create a new view see A_View.create() or A_View.register().

A_View.open(view_name)

Alias for A_View.new().

A_View.register(view_name, method_name, column_array)

This creates and/or registers a new view. Once a view has been registered, you can connect and iterator over it.

• view_name - this is the name of this view.
• method_name - this is the name of a Ruby method that you create to iterate over rows. Here is an example of a method (all parameters are required exactly as listed):

def membership_view(data_array, transaction=nil, min=nil, max=nil, update=nil)

• data_array - is required. This is an A_Table_Data class. This method will populate the data_array and yield it.
• transaction - this is passed through from the view's iterator. You should pass this along to the iterator of each table, index, and view that your method refereces.
• min - this is passed through from the view's iterator. You should pass this along to the iterator of each table, index, and view that your method refereces.
• max - this is passed through from the view's iterator. You should pass this along to the iterator of each table, index, and view that your method refereces.
• update - this is passed through from the view's iterator. This can be ignored. You may want to pass this along to the iterator of each table, index, and view that your method references.

membership = A_Table.connect('membership')

membership.each(transaction, min, max) do |_m_|

data_array.member_id = _m_.member_id

data_array.name = _m_.first_name + ' ' + _m_.last_name

end

membership.disconnect

end

• column_array - this is an Array of A_Column objects. This is a list of columns that will be yielded (returned) when iterating over this view.

 

Instance Methods:

close()

Close this view and free any used resources.

disconnect()

Alias for close.

drop()

Drop this view.

each(transaction=nil, min=nil, max=nil, update=nil) # for each primary key, yeild(pkey), the pkey may not exist yet in the primary key

Iterate over the rows in the view.

• transaction - this is an A_Transaction object. If nil, then this method will ignore any inserts/updates/deletes in all transactions while iterating. If not nil, then this method will include any inserts/updates/deletes that have occurred inside this transaction.
• min - this is the min key you want iterate over. This is passed to the method you created for this view as the min_key.
• max - this is the max key you want iterate over. This is passed to the method you created for this view as the max_key.
• update - this grabs the write lock before you start iterating. This is not useful at this time because you can't update views.

each_row

Alias for each.

each_sorted(transaction=nil, sort_block=nil)

• transaction - this is an A_Transaction object. If nil, then this method will ignore any inserts/updates/deletes in all transactions while iterating. If not nil, then this method will include any inserts/updates/deletes that have occurred inside this transaction.
• sort_block - if nil, then rows are sorted according to the columns in the view. If not nil, then this block is used when sorting. This allows to sort by the third and forth fields in the array. Here is an example that sorts on the 3^rd and 4^th columns:

sort_block = proc {|data_array1, data_array2| data_array1[3] <=> data_array2[3] && data_array1[4] <=> data_array2[4]}

rev_block = proc {|data_array1, data_array2| data_array2[3] <=> data_array1[3] }

You have to use numbers (the index of the column in the column array for this view) rather than column names because the a_filesort class does not support singleton methods and this excludes the column name methods from being supported in the sorting. If anyone has a cool work around for this limitation, please let me know. I would apprecaiate it deeply.

each_value

Alias for each.

exists?(transaction, key)

Returns true if the method you created for this view yields any rows. Returns false if no rows are yielded. It returns after the first row is retrieved.

• transaction - this is an A_Transaction object. If nil, then this method will ignore any inserts/updates/deletes in all transactions while iterating. If not nil, then this method will include any inserts/updates/deletes that have occurred inside this transaction.
• key - this key is passed to the method you created for this view as both the min_key and the max_key.

find(transaction, key)

Returns the data_array filled the first row in this view.

• transaction - this is an A_Transaction object. If nil, then this method will ignore any inserts/updates/deletes in all transactions while iterating. If not nil, then this method will include any inserts/updates/deletes that have occurred inside this transaction.
• key - this key is passed to the method you created for this view as both the min_key and the max_key.

find_last(transaction, key)

Returns the data_array filled the last row in this view. This iterates over all rows to find the last row, so it may be slow.

• transaction - this is an A_Transaction object. If nil, then this method will ignore any inserts/updates/deletes in all transactions while iterating. If not nil, then this method will include any inserts/updates/deletes that have occurred inside this transaction.
• key - this key is passed to the method you created for this view as both the min_key and the max_key.

name()

Returns the name of the view.

rows_accessed()

Returns the number of rows accessed while iterating. I did not want to have to manually track the row count while I was iterating.

show(prefix='')

Prints the content of this view.

to_s()

Format the content of this view (name, method name, columns) for printing.

view_name()

 Returns the name of this view.

 

Testing: 

tst_a_view.rb - this script performs basic testing for the A_View class. This test script includes examples for creating views that perform inner joins, outer joins, and unions on one or more tables, indexes, and/or views. To run this tests type:

ruby -I.. tst_a_view.rb

 

A_Debug Usage:

10 - create and drop views

15 - iterating over views