1Boulder::Store(3)     User Contributed Perl Documentation    Boulder::Store(3)
2
3
4

NAME

6       Boulder::Store - Simple persistent storage for Stone tag/value objects
7

SYNOPSIS

9        Boulder:Store;
10
11        my $store=new Boulder::Store('test.db',1);
12        my $s = new Stone (Name=>'george',
13                           Age=>23,
14                           Sex=>M,
15                           Address=>{
16                                  Street=>'29 Rockland drive',
17                                  Town=>'Fort Washington',
18                                  ZIP=>'77777'
19                                  }
20                              );
21        $store->put($s);
22        $store->put(new Stone(Name=>'fred',
23                              Age=>30,
24                              Sex=>M,
25                              Address=>{
26                                          Street=>'19 Gravel Path',
27                                          Town=>'Bedrock',
28                                          ZIP=>'12345'},
29                              Phone=>{
30                                        Day=>'111-1111',
31                                        Eve=>'222-2222'
32                                        }
33                                    ));
34        $store->put(new Stone(Name=>'andrew',
35                              Age=>18,
36                              Sex=>M));
37
38        $store->add_index('Name');
39
40        my $stone = $store->get(0);
41        print "name = ",$stone->Name;
42

DESCRIPTION

44       Boulder::Store provides persistent storage for Boulder objects using a
45       simple DB_File implementation.  To use it, you need to have Berkeley db
46       installed (also known as libdb), and the Perl DB_File module.  See the
47       DB_File package for more details on obtaining Berkeley db if you do not
48       already have it.
49
50       Boulder::Store provides an unsophisticated query mechanism which takes
51       advantage of indexes that you specify.  Despite its lack of
52       sophistication, the query system is often very helpful.
53

CLASS METHODS

55       $store = Boulder::Store->new("database/path",$writable)
56           The new() method creates a new Boulder::Store object and associates
57           it with the database file provided in the first parameter (undef is
58           a valid pathname, in which case all methods work but the data isn't
59           stored).  The second parameter should be a true value if you want
60           to open the database for writing.  Otherwise it's opened read only.
61
62           Because the underlying storage implementation is not multi-user,
63           only one process can have the database for writing at a time.  A
64           fcntl()-based locking mechanism is used to give a process that has
65           the database opened for writing exclusive access to the database.
66           This also prevents the database from being opened for reading while
67           another process is writing to it (this is a good thing).  Multiple
68           simultaneous processes can open the database read only.
69
70           Physically the data is stored in a human-readable file with the
71           extension ".data".
72

OBJECT METHODS

74       $stone = $store->read_record(@taglist)
75           The semantics of this call are exactly the same as in
76           Boulder::Stream.  Stones are returned in sequential order, starting
77           with the first record.  In addition to their built-in tags, each
78           stone returned from this call has an additional tag called
79           "record_no".  This is the zero-based record number of the stone in
80           the database.  Use the reset() method to begin iterating from the
81           beginning of the database.
82
83           If called in an array context, read_record() returns a list of all
84           stones in the database that contains one or more of the provided
85           tags.
86
87       $stone = $store->write_record($stone [,$index])
88           This has the same semantics as Boulder::Stream.  A stone is
89           appended to the end of the database.  If successful, this call
90           returns the record number of the new entry.  By providing an
91           optional second parameter, you can control where the stone is
92           entered.  A positive numeric index will write the stone into the
93           database at that position.  A value of -1 will use the Stone's
94           internal record number (if present) to determine where to place it.
95
96       $stone = $store->get($record_no)
97           This is random access to the database.  Provide a record number and
98           this call will return the stone stored at that position.
99
100       $record_number = $store->put($stone,$record_no)
101           This is a random write to the database.  Provide a record number
102           and this call stores the stone at the indicated position, replacing
103           whatever was there before.
104
105           If no record number is provided, this call will look for the
106           presence of a 'record_no' tag in the stone itself and put it back
107           in that position.  This allows you to pull a stone out of the
108           database, modify it, and then put it back in without worrying about
109           its record number.  If no record is found in the stone, then the
110           effect is identical to write_record().
111
112           The record number of the inserted stone is returned from this call,
113           or -1 if an error occurred.
114
115       $store->delete($stone),Boulder::Store::delete($record_no)
116           These method calls delete a stone from the database.  You can
117           provide either the record number or a stone containing the
118           'record_no' tag.  Warning: if the database is heavily indexed
119           deletes can be time-consuming as it requires the index to be
120           brought back into synch.
121
122       $record_count = $store->length()
123           This returns the length of the database, in records.
124
125       $store->reset()
126           This resets the database, nullifying any queries in effect, and
127           causing read_record() to begin fetching stones from the first
128           record.
129
130       $store->query(%query_array)
131           This creates a query on the database used for selecting stones in
132           read_record().  The query is an associative array.  Three types of
133           keys/value pairs are allowed:
134
135           (1) $index=>$value
136               This instructs Boulder::Store to look for stones containing the
137               specified tags in which the tag's value (determined by the
138               Stone index() method) exactly matches the provided value.
139               Example:
140
141                       $db->query('STS.left_primer.length'=>30);
142
143               Only the non-bracketed forms of the index string are allowed
144               (this is probably a bug...)
145
146               If the tag path was declared to be an index, then this search
147               will be fast.  Otherwise Boulder::Store must iterate over every
148               record in the database.
149
150           (2) EVAL=>'expression'
151               This instructs Boulder::Store to look for stones in which the
152               provided expression evaluates to true.  When the expression is
153               evaluated, the variable $s will be set to the current record's
154               stone.  As a shortcut, you can use "<index.string>" as
155               shorthand for "$s->index('index.string')".
156
157           (3) EVAL=>['expression1','expression2','expression3'...]
158               This lets you provide a whole bunch of expressions, and is
159               exactly equivalent to EVAL=>'(expression1) && (expression2) &&
160               (expression3)'.
161
162           You can mix query types in the parameter provided to query().  For
163           example, here's how to look up all stones in which the sex is male
164           and the age is greater than 30:
165
166                   $db->query('sex'=>'M',EVAL=>'<age> > 30');
167
168           When a query is in effect, read_record() returns only Stones that
169           satisfy the query.  In an array context, read_record() returns a
170           list of all Stones that satisfy the query.  When no more
171           satisfactory Stones are found, read_record() returns undef until a
172           new query is entered or reset() is called.
173
174       $store->add_index(@indices)
175           Declare one or more tag paths to be a part of a fast index.
176           read_record() will take advantage of this record when processing
177           queries.  For example:
178
179                   $db->add_index('age','sex','person.pets');
180
181           You can add indexes any time you like, when the database is first
182           created or later.  There is a trade off:  write_record(), put(),
183           and other data-modifying calls will become slower as more indexes
184           are added.
185
186           The index is stored in an external file with the extension
187           ".index".  An index file is created even if you haven't indexed any
188           tags.
189
190       $store->reindex_all()
191           Call this if the index gets screwed up (or lost).  It rebuilds it
192           from scratch.
193

CAVEATS

195       Boulder::Store makes heavy use of the flock() call in order to avoid
196       corruption of DB_File databases when multiple processes try to write
197       simultaneously.  flock() may not work correctly across NFS mounts,
198       particularly on Linux machines that are not running the rpc.lockd
199       daemon.  Please confirm that your flock() works across NFS before
200       attempting to use Boulder::Store.  If the store.t test hangs during
201       testing, this is the likely culprit.
202

AUTHOR

204       Lincoln D. Stein <lstein@cshl.org>, Cold Spring Harbor Laboratory, Cold
205       Spring Harbor, NY.  This module can be used and distributed on the same
206       terms as Perl itself.
207

SEE ALSO

209       Boulder, Boulder::Stream, Stone
210
211
212
213perl v5.36.0                      2022-07-22                 Boulder::Store(3)
Impressum