[TRex documentation]

Developer's arena

TRex::Storage

NAME

TRex::Storage - provides storage management services

SYNOPSIS

    use TRex::Storage;

DESCRIPTION

The data storage module is an abstraction presented to the core (or anyone interfacing with it) to manage the storage of any persistent data storage. This one must be emphasized, mainly because all volatile info would be stored in memory storage (accessed through variables), and not through the Data Storage. Albeith the generic name is retained for simplicity, and because in a future implementation volatile info could be accessed also through this module (this could be very useful for data that must be encrypted).

To allow a generic use of this interface (and that allows the storage in any media) in a consistent way across any storage access method (plain text files, relational databases, etc.), hidding the implementation details to the core.

First sight

The actions that all storage allow us to do are reading data from it and writing into it. Additionally there's security considerations to do, such as context creation (authentication), internal data structure preparation, and so on.

Based on these generic assumptions, the next methods will be used:

Additionally the storage is separated into distinct storage classes, each one representing a conceptually different stored data but that could be implemented in the same media. Examples of these are configuration data, profile data and e-mails. This separation is only for construction purposes, but logically all of them respond to the same model, described in the next section:

The TRex::Storage model

This model shows all data as tree, a bush is a better name, composed of a root, branches and leaves: the root is the beginning (the starting pont), the branches are simple organizers where the leaves are inserted.

Common operations are defined, as shown above, and each one has the same meaning across all class IDs with some minor refinements that are explained below, in the detailed description for each of them.

There exist the next so called class IDs, that identifies the storage classes. They are:

Implementation details

The class assigned to the storage objects is TRex::Storage.

As explained, each object has methods (open, close, read, write, etc.) to manipulate data in the data storage, whose interface (and usage) is defined in the following paragraphs.

Returned values

A note, before starting with the methods, is that all methods return a non-zero value to signal an error, and zero when the operation was successful.

The non-zero value, indicating an error, varies for each method except for the value ``1''. When this is returned, it means that an ``unspecified error'' has occured. This is also used when an error has occurred, and it has not corresponding error number assigned or belongs to an internal one.

FIXES TO DO

METHODS

new($)

This is the constructor, an returns a new handler for to the specified storage class (mandatory parameter). A value ``undef'' is returned in case a constructor founds problems.

Usage :

  use TRex::Storage;
  my $handler = TRex::Storage->new( 'EMail' );
  die "Crashhhh new() !!!\n"  if ( ! defined $handler );

authMethods()

Each class ID can be implemented using different technologies (relational database, X.500 repository, etc.), and using different authentication schemas.

The returned value is an array containing the preferred authentication methods, ordered from most preferred to least preferred.

The supported authentication methods are:

Usage :

  use TRex::Storage;
  my $handler = TRex::Storage->new( 'EMail' );
  die "Crashhhh new() !!!\n"  if ( ! defined $handler );
  my @authMethods = authMethods();

notExistsAuthMethod(%)

Checks if the passed authentication method exists in the array obtained via authMethods() call.

The parameters are passed in a hash, and the key values are :

The return values are non-zero on failure and 0 (zero) on success.

Usage :

  use TRex::Storage;
  my $method = "AMAIL";
  ### ... handler obtained via new() ... 
  ### ... auth methods obtained via authMethods() ..
  die "$method auth. schema not supported"
      if  notExistsAuthMethod( { AUTH_METHOD => $method, 
                                 AUTH_ARRAY => \@authMethods });

open(%)

Opens a connection to the desired storage class.

The parameters are passed in a hash, and the key values corresopnd to the desired parameters to be passed:

The the code returned are the ones specified in the ``Returned values'', plus :

Usage :

  use TRex::Storage;
  my $handler = TRex::Storage->new( 'EMail' );
  die "Crashhhh new() !!!\n"  if ( ! defined $handler );
  my @authMethods = $handler->authMethods();
  die "Unknown authentication method\n"
      if  ! AMAIL_Method_in_list( @authMethods );
  die "Can't authenticate\n"
      unless !  $handler->open( { AUTH_METHOD => 'AMAIL',
                                AUTH_PARAMETERS => { aMail_ID => 'bit-man', 
                                                     SID => '331868645' } } );

insert(%)

Inserts an object in the data store.

The parameters are passed in a hash, and the key values correspond to the desired parameters to be passed:

The returned codes are the one specified in ``Return values'' section plus :

Usage :

  use TRex::Storage;
  my $folder = "myFolder"
  my $MID;  ## Here will be stored the Message ID
  ### ... handler obtained via new() ... 
  ### ... auth methods obtained via authMethods() ..
  ### ... authentication via open() ...
  die "Can't store message at $folder"
      unless  ! $handler->insert( { OBJECT => 'FOLDER',
                                    FOLDER => $folder,
                                    DATA => $message,
                                    OID => \$MID } );

delete(%)

Deletes an object in the data store.

The parameters are passed in a hash, and the key values correspond to the desired parameters to be passed:

In case of a general error, it is returned as a scalar. If some objects can be deleted (and some not) the global error is zero, and the error for each object is returned in the RETURN hash (passed as a reference), where each MID is a key into it corresponding to the messages in the MID list, and as 'Error' as a second key.

The returned codes are the one specified in ``Return values'' section plus :

Usage :

  use TRex::Storage;
  my $folder = "myFolder";
  my $globalError;
  ### ... handler obtained via new() ... 
  ### ... auth methods obtained via authMethods() ..
  ### ... authentication via open() ...
  $globalError = $handler->delete( { OBJECT => 'FOLDER',
                                     DATA => $folder } );
  die "Can't delete folder"    if $globalError;
  my @MID;
  push @MID, 2782534;
  push @MID, 18253563;
  push @MID, 2924680;
  my %Return;
  $globalError = $handler->delete( { OBJECT => 'MESSAGE',
                                     DATA => \@MID, 
                                     RETURN => \%Return } );
  die "Can't delete messages"    if $globalError;
  foreach ( keys %Return ) {
      my $error = %Return{$_}{'Error'};
      print "Can't delete MID '$_': $error\n"
          if( $error );
  };

update(%)

Updates an object in the data store.

The parameters are passed in a hash, and the key values correspond to the desired parameters to be passed:

The returned codes are the one specified in ``Return values'' section plus :

Usage :

  use TRex::Storage;
  my $MID = 23564756;
  ### ... handler obtained via new() ... 
  ### ... auth methods obtained via authMethods() ..
  ### ... authentication via open() ...
  die "Can't rename folder $old_name to $new_name"
      unless  ! $handler->update( { OBJECT => 'MESSAGE',
                                        OID => $MID
                                    PROPERTIES => { HAS_BEEN_READ => 1,
                                                                    FOLDER = 'my_new_folder' } 
                                  } );

readBulk(%)

Retrieves ALL the specified objects (equivalent to read + read_next + read_next + ... ).

The parameters are passed in a hash, and the key values correspond to the desired parameters to be passed:

The returned codes are the one specified in ``Return values'' section plus all the object attributes contained in are placed in the hash, whose reference is passed in RETURN.

In case of FOLDER object: The keys returned are one for each message (referenced by its Message ID or MID) which, at the same time, contains all the attributes for each message inside its hash element, and whose keys are:

In case of REPOSITORY object: The keys returned are one for each folder (referenced by its Folder ID or FID) which, at the same time, contains all the attributes for each folder inside its hash element, and whose keys are:

3) the whole message in case of MESSAGE object (WARNING it will return it in a scalar NOT in an array !!)

... PLUS the next error codes:

Usage :

  use TRex::Storage;
  my $folder = "myFolder";
  my %data;
  ### ... handler obtained via new() ... 
  ### ... auth methods obtained via authMethods() ...
  ### ... authentication via open() ...
  die "Can't retrieve folder $folder content."
      if ! $handler->readBulk( { OBJECT => 'FOLDER',
                                 OID => $folder,
                                 RETURN => \%data } );
  foreach my $MID ( keys %data ) {
      print "================ MID: $MID\n";
      foreach my $attribute ( keys %{$data{$MID}}  ) {
          print "$attribute: ";
          print ${$data{$MID}}{$attribute};
          print "\n";
     }
  }

search(%)

Searches for data in the leaves of the data store. Only data in the leaves is searched, and not the properties names in it. e.g. if the word 'Subject' is searched in the 'Message' class ID all the e-mail would match if the complete e-mail were searched, but this not the case because only the data (the real subject, not the string 'Subject:' that identifies it) is searched.

This was made so because the properties are known words, and in case we need one we know how to retrieve it.

The parameters are passed in a hash, and the key values correspond to the desired parameters to be passed:

The returned codes are the one specified in ``Return values''.

Usage :

  use TRex::Storage;
  my $textToSearch = 'tax declaration';
  my @data;    ### Container for leaves that meet 
               ### the search conditions
  ### ... handler obtained via new() ... 
  ### ... auth methods obtained via authMethods() ...
  ### ... authentication via open() ...
  die "Can't search today (I'm a bit tired ... ;-) )"
      unless  ! $handler->search( { TEXT => [ 0, $textToSearch],
                                    DATE => [ 1, '06-10-2003' ],
                                    FOLDERS => [ 'Inbox', 'stuff' ],
                                        RETURN => \@data 
                                  } );
[TRex documentation]

Developer's arena

TRex::Storage