a_sequences

Seva Software

What is Aruna DB?

Last Updated: 9/25/2001

A_Sequences

Performance Considerations

Provide sequence support for ArunaDB. ArunaDB is a database server written in Ruby. Sequences allow you to easily create automatic incrementing numbers (also called the Serial data type in PostgreSQL) in A_Table.

Description:

A sequence is an auto-incrementing number whose value is stored in the system catalog. Sequences work in groups or collections. A_Sequences.new(name) creates a new collection of sequences. This collection of sequences is stored as a single item in the system catalog. The A_Table class creates and uses a collection of sequences called 'sequences'. If you call A_Sequences.use(new_name) directly, then the A_Table class will look for sequences in the new_name collection.

Dependencies:

a_debug.rb - this provides debugging messages for all of my Ruby code. See a_debug.html for more details.
a_catalog.rb - this is the system catalog for ArunaDB. It stores every collection of sequences. See a_catalog.html for more details.

Limitations:

You can't specify how the incrementing of the sequence occurs. They always increment by one.
You can't set a high water mark and get an error when the sequence grows too large.

Performance Considerations:

Try to not commit after every sequence update. ArunaDB, automatically commits sequences when Transaction.commit is called.

To Do:

None

Usage:

A_Catalog.use('tst_a_view.ctl') # we need a system catalog

seq = A_Sequences.use('your_sequence_name') # create or open a collection of sequences

seq.create('member_id_seq') # create a new sequence

id = seq.next_val('member_id_seq')

seq.commit()

seq.close

Class Methods:

A_Sequences.commit()

Write the current collection of sequences to the system catalog. This flushes any changes to disk.

A_Sequences.create(sequence_name, start=0)

Creates a new sequence in the current collection of sequences.

A_Sequences.curr_val(sequence_name)

Return the value of the sequence from the current collection of sequences.

A_Sequences.dirty?()

Returns true if the current collection of sequences has been updated and not written to disk. Otherwise, returns nil.

A_Sequences.drop(sequence_name)

Drops the sequence from the current collection of sequences.

A_Sequences.exists?(sequence_name)

Return true if this sequence exists in the current collection of sequences, otherwise, return false.

A_Sequences.new(name)

If name already exists in the system catalog, then it opened. If name does not already exist in the system catalog, then creates a new collection of sequences. This is a grouping of sequences rather than an individual sequence. This creates a new entry in the system catalog.

A_Sequences.next_val(sequence_name)

Increments the value of the sequence in the current collection of sequences and return it.

A_Sequences.open(name)

Opens an existing collection of sequences. If the collection does not exist in the system catalog then a new collection is created.

A_Sequences.set_val(sequence_name, value)

Set the value of the sequence in the current collection of sequences to the specific value.

A_Sequences.rollback()

This clears the dirty flag for the current collection of sequences. We can't actually rollback the sequences because another transaction may have updated it.

A_Sequences.use(name='sequences')

Avoid using this method. This method is used internally by A_Table to establish a collection of sequences for use with tables. If you have created several sequences and then call this method, the original sequences may not exist in the new collection. This could cause problems with the A_Table class. If the collection of sequences called name exists, then it is opened. If it does not exist, then it is created. This becomes or sets the current collection of sequences. Be careful calling this method, call new() instead.

Instance Methods:

close()

Closes this collection of sequences. It also commits any pending changes to the system catalog.

commit(transaction=nil)

Write or flush any changes to this collection of sequences to disk (the system catalog)

transaction - is needed for the transaction manager, A_Transaction.commit calls this method.

create(sequence_name, start=0)

Create a new sequence in this collection of sequences.

curr_val(sequence_name)

Returns the current value of this sequence in this collection of sequences.

dirty()

Returns true if this collection of sequences has been updated and not written to disk. Otherwise, returns nil.

drop(sequence_name)

Drop this sequence from this collection of sequences.

flush()

Alias for commit().

name()

Returns the name of this collection of sequences.

next_val(sequence_name)

Increments and then returns the current value of this sequence in this collection of sequences.

rollback(transaction=nil)

This does not actually rollback the sequences because we can't tell if another transaction has changed a sequence. This method does not do anything. It is provided for consistency in it's interaction with the transaction manager.

transaction - is needed for the transaction manager, A_Transaction.rollback calls this method.

set_val(sequence_name, value)

Sets the value of this sequence in this collection of sequences to value.

to_s()

Returns a string containing every sequence and their values in this collection of sequences.

write()

Alias for commit().

Testing:

a_sequences_tst.rb - this script tests the basic functionality of the A_Sequences class.

A_Debug Usage:

N/A