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_timeget_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 operationsDESCRIPTION
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.