NAME

Search::InvertedIndex::DB::DB_File_SplitHash - A Berkeley database interface object for Search::InvertedIndex

SYNOPSIS

use Search::InvertedIndex::DB::DB_File_SplitHash;

my $db = Search::InvertedIndex::DB::DB_File_SplitHash->new({
           -map_name => '/www/search-engine/databases/test-map_names/test',
              -multi => 4,
          -file_mode => 0644,
          -lock_mode => 'EX',
       -lock_timeout => 30,
     -blocking_locks => 0,
          -cachesize => 1000000,
      -write_through => 0, 
    -read_write_mode => 'RDONLY';
      });

my $inv_map = Search::InvertedIndex->new({ -database => $db });

my $query = Search::InvertedIndex::Query->new(...);
my $result = $inv_map->search({ -query => $query });

my $update = Search::InvertedIndex::Update->new(...);
my $result = $inv_map->update({ -update => $update });

$inv_map->close;

DESCRIPTION

Provides a standard interface to an underlaying database - in this case Berkeley DB as extended by the Tie::DB_File::SplitHash package.

There are twelve standard API calls required of any database interface used by the Search::InvertedIndex module:

new     - Takes all parameters required for initialization. 
          Free form parameters as required by the underlaying
          database.
open    - Actually opens the database. No parameters.
close   - Closes the database. No parameters.
lock    - Sets a lock state of (UN, SH or EX) and optionally allows setting/
          changing the 'blocking/non-blocking' and timeouts for locking.
get     - Fetches a string -value for a -key. Returns 'undef' if no -key matches in the database.
put     - Stores a string -value for a -key. Returns true on success, false on failure.
exists  - Returns true if the -key is defined in the database, false otherwise.
delete  - Removes a -key and associated -value from database. Returns true on success, false on failure.
clear   - Clears all keys/values from the database 
status  - Returns open and lock status messages. 

DESTROY - Used to dispose of the database object

CHANGES

1.00 1999.06.16 - Initial release.

1.01 1999.06.17 - Bug fix to 'close' method. Failed to clear the filehandle used for locking.

1.02 1999.06.18 - Major bugfix to locking system and performance tweaking

1.03 1999.07.01 - Documentation corrections.

1.04 1999.10.20 - Removed use of 'use attr' for portability improvement

1.06 2000.01.25 - Bugfix (added 'use Tie::DB_File::SplitHash;' to initialization)

1.07 2000.03.23 - Bugfix for disposal when database was never actually opened 

Public API

new($parm_ref);

Provides the interface for obtaining a new Search::InvertedIndex object for manipulating a inverted database.

Example 1: my $inv_map = Search::InvertedIndex->new;

Example 2: my $inv_map = Search::InvertedIndex->new({ -map_name => '/tmp/imap', # file path to map -multi => 4, # multiple DB file factor. Defaults to 4 -file_mode => 0644, # File permissions to open with. Defaults to 0666. -cachesize => 1000000, # DB cache size. Defaults to 1000000 -lock_mode => 'EX', # DB lock mode. Defaults to EX -lock_timeout => 30, # Seconds to try and get locks. Defaults to 30 -write_through => 0, # Write through on cache? Defaults to 0 (no) -blocking_locks => 0, # Locks should block? Defaults to 0 (no) -read_write_mode => 'RDWR', # RDONLY or RDWR? Defaults to 'RDWR' });

open;

Actually open the database for use.

Example 1: $inv_map->open;

status($parm_ref);

Returns the requested status line for the database. Allowed requests are '-open', and '-lock'.

Example 1: my $status = $db->status(-open); # Returns either '1' or '0'

Example 2: my $status = $db->status(-lock_mode); # Returns 'UN', 'SH' or 'EX'

lock($parm_ref);

Sets or changes a filesystem lock on the underlaying database files. Forces 'sync' if the stat is changed from 'EX' to a lower lock state (i.e. 'SH' or 'UN'). Croaks on errors.

Example:

$inv->lock({ -lock_mode => 'EX',
          -lock_timeout => 30,
        -blocking_locks => 0,
      });

The only _required_ parameter is the -lock_mode. The other parameters can be inherited from the object state. If the other parameters are used, they change the object state to match the new settings.

close;

Closes the currently open -map_name and flushes all associated buffers.

DESTROY;

Closes the currently open -map_name and flushes all associated buffers.

put({ -key = $key, -value => $value });>

Stores the -value at the -key location in the database. No serialization is performed - this is a pure 'store a string' method. Returns '1' on success, '0' on failure.

get({ -key = $key });>

Returns the -value at the -key location in the database. No deserialization is performed - this is a pure 'fetch a string' method. It returns 'undef' if no such key exists in the database.

Example:

my ($value) = $db->get({ -key => $key });

delete({ -key = $key });>

Deletes the -value at the -key location in the database.

exists{-key = $key});>

Returns true if the -key exists in the database. Returns false if the -key does not exist in the database.

clear;

Internal method. Not for access outside of the module.

Completely clears the map database.

COPYRIGHT

Copyright 1999, Benjamin Franz (<URL:http://www.nihongo.org/snowhare/>) and FreeRun Technologies, Inc. (<URL:http://www.freeruntech.com/>). All Rights Reserved. This software may be copied or redistributed under the same terms as Perl itelf.

AUTHOR

Benjamin Franz

TODO

Everything.