NAME

Data::ObjectStore - store perl objects, hashes and arrays in a rooted tree on-disc.

DESCRIPTION

If you have structured data you want to store, store it in an object store. Have really huge arrays or hashes? No problem, those are chunked in batches. They're neatly TIED and loaded as needed.

Add to, remove from or update the structure and the store knows. A single method brings it all of it up to date.

SYNOPSIS

 use Data::ObjectStore;

 my $store = Data::ObjectStore::open_store( '/path/to/data-directory' );

 my $root_container = $store->load_root_container;

 my $current_data = [ 123,123,345,45,3752,346,326,43745,76 ];

 # get_experiment and set_experiment automagically work.
 my $experiment = $root_container->get_expirement;
 unless( $experiment ) {
   # My::Experiment @ISA Data::ObjectStore::Container
   $experiment = $root_container->set_expirement(
             $store->create_container( 'My::Experiment' )
                                                );
 }

 # returns val if val is defined.
 # If val isn't defined, it sets val to 'default value' and returns it.
 my $val = $experiment->get_val( 'default value' );

 $experiment->set( "note", "this is identical to 'set_note'" );

 # creates data_sets list or uses existing one
 $experiment->add_to_data_sets( $current_data );

 $store->save;

 # forgot a point! Add to the current data and save it.
 push @$current_data, 234;
 $store->save;

 ....

 my $data_sets = $store->load_root_container
                       ->get_experiment
                       ->get_data_sets;
 for my $set (@$data_sets) {
   ....
 }

SUBCLASSING

Blessed objects must be a subclass of Data::ObjectStore::Container in order to be able to be stored in the object store. _init and _load can be useful to override.

 package Mad::Science::User;
 use Data::ObjectStore;
 use base 'Data::ObjectStore::Container';

 # called when an object is newly created
 sub _init {
   my $self = shift;
   $self->set_status( "NEWLY CREATED" );
   $self->set_experiments([]);
 }

 # called when the object is loaded from the store
 sub _load {
   my $self = shift;
   print "Loaded " . $self->get_name . " from store";
   if( @{$self->get_experiments} > 0 ) {
     $self->set_status( "DOING EXPERIMENTS" );
   }
 }

 sub evacuate {
   my $self = shift;
   $self->set_status( "HEADING FOR THE HILLS" );
 }

PUBLIC METHODS

open_store( '/path/to/directory' )

Starts up a persistance engine that stores data in the given directory and returns it.

load_root_container

Fetches the root node of the store, a Data::ObjectStore::Container object.

info

Returns a hash of info about this opened data store. Updating the hash has no effect.

 * db_version
 * ObjectStore_version
 * created_time
 * last_update_time

get_db_version

Returns the version of Data::RecordStore that this was created under.

get_store_version

Returns the version of Data::ObjectStore that this was created under.

get_created_time

Returns when the store was created.

get_last_update_time

Returns the last time this store was updated.

create_container( optionalClass, { data } )

Returns a new Data::ObjectStore::Container container object or a subclass, depending if the optional class parameter is supplied. If provided with data, the object is initialized with the data.

If the object is attached to the root or a container that is ultimately attached to the root, it will be saved when save is called.

run_recycler

This checks for objects that are not traceable to the root object and removes them, recycling thier ids.

save

When called, this stores all objects that have been changed since the last time save was called.

Data::ObjectStore::Container

 Persistant Perl container object.

SYNOPSIS

 $obj_A = $store->create_container;

 $obj_B = $store->create_container( {
                          myfoo  => "This foo is mine",
                          mylist => [ "A", "B", "C" ],
                          myhash => { peanut => "Butter" } 
                                  } );

 $obj_C = $store->create_container( 'My::Subclass' );

 $obj_D = $store->create_container( 'My::Othersubclass', { initial => "DATA" } );

 #
 # get operations
 #
 print $obj_B->get_myfoo; # prints "this foo is mine"

 print $obj_B->get( "myfoo" ); # prints "this foo is mine"

 print $obj_B->get_myhash->{peanut}; # prints 'butter'

 $val = $obj_A->get_val; # $val is now undef

 $val = $obj_A->get_val("default"); # $val is now 'default'

 $val = $obj_A->get_Val("otherdefault"); # $val is still 'default'

 $val = $obj_A->set_arbitraryfield( "SOMEVALUE" ); # $val is 'SOMEVALUE'

 #
 # set operations
 #
 $obj_C->set( "MYSET", "MYVAL" );
 $val = $obj_C->get_MYSET; # $val is 'MYVAL'

 $obj_B->set_A( $obj_A );

 $root = $store->load_root_container;

 $root->set_B( $obj_B );

 #
 # list operations
 #
 $mylist = $obj_B->add_to_mylist( "D" ); #mylist now 'A','B','C','D'

 $newlist = $obj_B->add_to_newlist( 1, 2, 3, 3, 3 );
 print join(",", $newlist);  # prints 1,2,3,3,3

 $obj_B->remove_from_newlist( 3 );
 print join(",", $newlist);  # prints 1,2,3,3
 $obj_B->remove_all_from_newlist( 3 );
 print join(",", $newlist);  # prints 1,2

 # yes, the $newlist reference is changed when the object is operated on with list operations

DESCRIPTION

This is a container object that can be used to store key value data where the keys are strings and the values can be hashes, arrays or Data::ObjectStore::Container objects. Any instances that can trace a reference path to the store's root node are reachable upon reload.

This class is designed to be overridden. Two methods are provided for convenience. _init is run the first time the object is created. _load is run each time the object is loaded from the data store. These methods are no-ops in the base class.

METHODS

set( field, value )

Sets the field to the given value and returns the value. The value may be a Data::ObjectStore::Container or subclass, or a hash or array reference.

get( field, default_value )

Returns the value associated with the given field. If the value is not defined and a default value is given, this sets the value to the given default value and returns it.

The value may be a Data::ObjectStore::Container or subclass, or a hash or array reference.

store

Returns the Data::ObjectStore that created this object.

_init

    This is called the first time an object is created. It is not
    called when the object is loaded from storage. This can be used
    to set up defaults. This is meant to be overridden.

_load

    This is called each time the object is loaded from the data store.
    This is meant to be overridden.

AUTHOR Eric Wolf coyocanid@gmail.com

COPYRIGHT AND LICENSE

       Copyright (c) 2018 Eric Wolf. All rights reserved.  This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

VERSION Version 1.1 (Mar, 2018))

cpanm Data::ObjectStore

perl -MCPAN -e shell
install Data::ObjectStore