NAME
SYNOPSIS
DESCRIPTION
CONSTRUCTOR
PUBLIC METHODS
INHERITANCE
AUTHOR
COPYRIGHT
SEE ALSO

NAME

Site::Sequence - Imperia numerical sequences

SYNOPSIS

 use Site::Sequence;

 my $sequence = Site::Sequence->new;

 $sequence->create ('my_sequence',
                    INCREMENT => 1,
                    MINVALUE  => 1,
                    MAXVALUE  => 2147483647,
                    START     => 1,
                    CACHE     => 1,
                    CYCLE     => 'yepp');

 $sequence->exists ('my_sequence')
     && print "Sequence my_sequence exists\n";

 $sequence->drop ('my_sequence');

 $sequence->currentValue ('my_sequence');

 $sequence->nextValue ('my_sequence');

DESCRIPTION

The Site::Sequence(3) module is the high-level interface to Imperia numeric sequences. See Dynamic::Sequence::Interface(3) for documentation of the low-level interface (its direct use is deprecated).

The module is capable of managing concurrent access to the sequences.

CONSTRUCTOR

new [PLUGIN_NAME, PLUGIN_PARAMS]: You may optionally tell the constructor which Sequence plugin to load using the PLUGIN_NAME parameter. PLUGIN_PARAMS as an optional array of arguments which are passed to the constructor of the plugin.

PUBLIC METHODS

create NAME[, ARGS]

Create a new sequence of the desired NAME. The function accepts a hash with optional named-style arguments:

INCREMENT: A positive value will make an ascending sequence, a negative one a descending sequence. The default value is one (1).
MINVALUE: The optional MINVALUE determines the minimum value a sequence can generate. The defaults are 1 and -2147483647 for ascending and descending sequences, respectively.
MAXVAULE: The optional argument MAXVALUE is used to determine the maximum value for the sequence. The defaults are 2147483647 and -1 for ascending and descending sequences, respectively.
START: The optional START argument must enable the sequence to begin anywhere. The default starting value is MINVALUE for ascending sequences and MAXVALUE for descending ones.
CACHE: The CACHE argument should enable sequence numbers to be preallocated and stored in memory for faster access. The minimum value is 1 (only one value can be generated at a time, i. e. no cache) and this is also the default. The CACHE argument may be completely ignored by implementations.
CYCLE: The optional CYCLE argument may be used to enable the sequence to continue when the MAXVALUE or MINVALUE has been reached by an ascending or descending sequence respectively. If the limit is reached, the next number generated will be whatever the MINVALUE or MAXVALUE is, as appropriate.

The method returns true for success or undef for failure (and an error message is pushed on the error stack). Possible error conditions are:

sequence NAME already exists
INCREMENT of 0
START less than MINVALUE
START greater than MAXVALUE
MINVALUE greater or equal MAXVALUE
Other backend specific error conditions

exists NAME

Returns true if the sequence of name NAME exists, false otherwise.

currentValue NAME

Returns the current value of the sequence of name NAME or undef for failure. Possible error conditions are:

NAME.currval is not yet defined in this session: This diagnostic is generated for sequences that have been created but that have not yet been initialized by calling the nextValue method.
Other backend specific error conditions

nextValue NAME

Generates and returns the next value for sequence NAME or false for failure. Possible error conditions (available from the object error stack) are:

NAME.nextval got MAXVALUE (maxvalue)
NAME.nextval got MINVALUE (minvalue): Generated if the sequence has reached its limit and it has not been created with a CYCLE argument.
Other backend specific error conditions

drop NAME

Delete the sequence NAME. Returns true for success or undef for failure (error message on error stack).

INHERITANCE

Since the module inherits from ErrorSaver(3), you can also use the methods described in ErrorSaver(3).

AUTHOR

Guido Flohr <guido@imperia.net>.