view release on metacpan or  search on metacpan

lib/NoSQL/PL2SQL/Simple.pm  view on Meta::CPAN

=head3 db()

C<new()> no arguments and returns an I<instance> of the data definition class.  As is typical in perl, the method C<NoSQL::PL2SQL::Simple::new()> is the 
conventional constructor.  However, NoSQL::PL2SQL::Simple is invoked by 
creating a subclass, which may need its own constructor.  Consequently, 
the following two statements are equivalent:

  $instance = NoSQL::PL2SQL::Simple->new ;
  $instance = NoSQL::PL2SQL::Simple->db ;

The instance has several functions:

=over 8

=item As a data definition, with methods to alter the definition

=item As a factory, with methods to create objects

=item As a data source, with methods to query the data

=back

All these methods are detailed in the following sections.

=head2 Data Definition Methods

Tabular data is I<tabular> because each element (a data object) has a common
structure. The entire data set can be laid on a grid with identifiable, 
pre-defined column names.  Data elements are laid out as rows which can be 
easily added or deleted.

I use the term I<NVP set> (an associative array in perl) to generalize 
these elements, and the term I<tabular> requires that each NVP set use 
the same names.  It's helpful if the reader can visualize this more abstract
model, because NoSQL::PL2SQL::Simple allows much more flexibility 
(or variation) among each NVP, so the result can be much less tabular than
data stored in a traditional RDB.

The difference is that in NoSQL::PL2SQL::Simple, only some names 
(or columns or fields) need to be commonly defined within each element 
(or object).  These names are determined by the data definition which are 
properties of the instance described above.  

As an example, consider an application that needs to save each user's session 
state.  If the application is complex, with numerous interfaces, this data 
is going to be quite unstructured as the state definition gets more 
complicated.  Nevertheless, there are a handful of common elements, say:
I<SessionID>, I<UserID>, I<Email>, and I<Password>.  Theoretically, this could
be done within a strict tabular structure by marshalling the fuzzy stuff into
a single BLOB value.  (Actually, this approach is not uncommon.)

  ## A simple application for saving a complex session

  BEGIN {
	package TQIS::Session ;
	use base qw( NoSQL::PL2SQL::Simple ) ;
	}
  
  $instance = TQIS::Session->new ;

The data definition is itself an NVP set data object.  This is perl, so it's 
accessed as a hash reference.

  ## display the data definition

  print join "\n", %$instance, '' ;

I<hash reference>, I<associative array>, or I<NVP set> are interchangable
terms.  Each name (or key) in this set is the same name required in each 
data object (or element).  Each associated value is a data type.  The data
types are intrinsic to NoSQ::PL2SQL::Simple, three are currently defined.
There's a little magic under the hood, so the best way to add data 
definitions are the following three methods:

=head3 addTextIndex()

=head3 addNumberIndex()

=head3 addDateIndex()

Here's how it's done in our example:

  $instance->addNumberIndex( qw( UserID ) ) ;
  $instance->addTextIndex( qw( Email Password ) ) ;

In this example I<SessionID> will be an internal, automatically generated key.
Since these definitions do not specify uniqueness, the code to enforce a
unique I<UserID> is shown later in L<Unique Keys>.

=head2 Factory Methods

Generally, an I<instance> needs a data definition before it's available for 
factory methods.

=head3 record()

As described above, the constructor creates an I<instance> that represents 
the data definition.  Data I<objects> are created using a factory method 
applied to the instance.  C<record()> is that factory method.  Because of
this special significance, it is heavily overloaded.

  $session = { ... } ;		## A tabular data object
  $sessionid = 231 ;		## An assigned id I made up

  $object = $instance->record( $session ) ;	## Returns an object copy
  $object = $instance->record( $sessionid ) ;	## Returns the stored object
  $object = $instance->record( 
		$sessionid => $session ) ;	## overwrites a stored object

The same C<record()> factory method is used to read, write, or overwrite a
data object, depending on the arguments.  Naturally, developers can create
conventional C<read()> and C<write()> methods in a subclass.

As a factory, C<record()> is always called via the instance.

=head2 Query Methods

Earlier, I compared NoSQL::PL2SQL::Simple to a solution that marshalls the
non-tabular data into a single BLOB value.  NoSQL::PL2SQL::Simple does
not perform any marshalling, so the resulting data storage is more accessible
and portable.  But it should be obvious that the data marshalled into the