Sequence Toolbox

Let's start with a simple toolbox: the sequence toolbox. A Sequence represents a generator of tokens with and inherent order. Normally we will use a sequence to generate numeric tokens but it can be use to generate almost anything you need.

Properties of a Sequence

A sequence is characterized mainly by three properties:

• Order - the sequence produces tokens in a specific order (normally ins ascendant order). As a consequence the token must contain an object with a natural order.
• Gap Resilience - the sequence may accept gaps or not. Accept gaps means not all token values must be used. Example: an integer sequence car run like : 1, 2, 3 , 6, 7,8 ... not using the 4 or the 5 for the token value.
• Limit - the sequence may stop because no more tokens are possible. Although conceptually a sequence may have an infinite number of tokens, in practice no sequence is infinite Has so, all sequences in MiddleHeavewn are considered "potentially infinite" , i.e. they would be infinite if there was no computational/environmental limit. thus, limited sequence are those that we know would never be infinite (e.g. a sequence based on the items of an array)

All sequences in MiddleHevaen are considerer ordered, unlimited and allow gaps. Sequences that are not ordered must inherit from RandomSequence. This is mainly a marker interface as no method is added to the interface.
Sequence that are intended to be limited must implement LimitedSequence. LimitedSequence adds an hasNext method to check if there are more tokens in the sequence.
Gap resiliance is a more difficult feature to implement has it must be defined over a transaction context. It two transactions A and B acquire tokens from the same sequence and A rollback, the dumped tokens must be reused by B , has there can't be gaps. TransactableSequence tries to address this by locking the sequence to a specific transaction until it ends (committing or rolling back)

Model

The figure below illustrates the basic set of sequence types in MiddleHeaven and who the relate to each other.

Not all sequences are present as some are implement inside other toolboxes. I'll talk about them later.
Following the Separation of Concerns principle all basic types are modeled as interfaces. All sequences are type-generic and have a next() method that return the next token in the sequence. StateEditableSequence allows for manipulation of the sequence state (read/write). This is usefull mainlly for defining StatePersistableSequence, a sequence whose state can be persisted so it never resets. This will be most useful for identity generation has we will see when we discuss the Storage Toolbox.

RandomCharSequence can be used to generate random sequence of characters (that may be further converted into String) and RandomNumberSequence can be used to generate random sequences of numbers. For both instances of Random can be specified for better control.

Use

Using a sequence is very simple:

			Sequence<Long> sequence = new LongSequence();
			
			Long value = sequence.next().value();
		

Sequences can be used per se or in conjunction or within other toolboxes. The Storage Toolbox uses sequences to create different identification tokens for storable objects. For database supported storage MiddleHeaven abstracts the native sequence mechanism present in some databases as a Sequence of Long.