/ 
KSx-IndexManager-0.004
River stage zero No dependents
/ KSx::IndexManager

NAME

KSx::IndexManager - high-level invindex management interface

VERSION

0.004

SYNOPSIS

my $mgr = KSx::IndexManager->new({
  root   => '/path/to/some/dir',
  schema => 'My::Schema',
});

my %arg = (type => "animal", id => 17);

$mgr->context(\%arg);

$mgr->write(\@docs);
$mgr->append(\@more_docs);
my $hits = $mgr->search(%search_arg);

my $invindexer = $mgr->invindexer;

my $searcher = $mgr->searcher;

NOTICE

This module is new and not completely thought out. The interface may change in incompatible ways, though I will give big alerts in the changelog when that happens. Please use it and give me feedback. Please do not use it if you want something that you can install and forget about.

In particular, the plugin interface is likely to change a great deal.

DESCRIPTION

KSx::IndexManager aims to provide simple access to one or more invindexes that all share a single schema.

Functionality is intentionally simple and is basically limited to convenient wrappers around common InvIndexer and Searcher methods. Additional functionality can be added through plugins.

CLASS METHODS

new

my $mgr = KSx::IndexManager->new(\%data);

Return a new IndexManager. Possible data keys are root, context, and schema; see those method descriptions for details.

add_plugins

My::Manager->add_plugins( $plugin => \%arg, $other_plugin => \%other_arg );

Instantiates one or more plugins and adds them to the manager class. See PLUGINS for details.

Arguments are a list of pairs, plugin name and hashref of arguments. See individual plugin classes for details.

invindexer_class

searcher_class

schema_class

Default to KinoSearch::InvIndexer and KinoSearch::Searcher, respectively. Setting these to new classes will automatically load those classes; see "set_component_class" in Class::Accessor::Grouped.

If you do not set schema_class, you will have to supply a schema argument for every object instantiation.

OBJECT ACCESSORS

root

Accessor/mutator for the base directory for this Manager. This directory may or may not actually be an invindex, depending on the plugins loaded.

schema

Name of the KinoSearch::Schema-derived class to use. This argument is mandatory if you have not set schema_class.

context

Arbitrary, application-specific data that defines the current context for index management. For example, the Partition plugin looks at the manager's context to determine which specific invindex to use.

path

Returns the path to the manager's invindex, based on root (and possibly context). With no plugins loaded, this is probably the same as root.

WRITING TO INVINDEXES

write

append

add_docs

$mgr->add_docs(\%options, \@docs);
$mgr->add_docs(\%options, $doc_iterator);

$mgr->write(\@docs);
$mgr->append(\@docs);

Add documents to an invindex. This combines invindexer creation, document addition, and invindexer finishing all in one call.

Currently the only valid option is mode, which may be one of 'clobber' or 'open'.

write and append are convenient wrappers around add_docs with the 'clobber' and 'open' modes, respectively.

The documents to be added may be passed in an arrayref or an iterator. Any object with a 'next' method will be treated as an iterator and used until exhausted.

Returns the number of objects processed.

to_doc

my $doc = $mgr->to_doc($obj);

Given some object, convert it into a document suitable for passing to the invindexer's add_doc method.

The structure of the object is manager-subclass dependent. The default to_doc is to do nothing, meaning that the object should be a hashref whose keys correspond to the schema class' fields.

You almost certainly want to override this in your manager subclass.

clobber

open

invindexer

my $invindexer = $mgr->invindexer({ mode => $mode });

Open a new invindexer with the given mode, which may be one of 'clobber' or 'open'.

clobber and open are convenient wrappers around invindexer with the 'clobber' and 'open' modes, respectively.

lock

unlock

lockfile

$mgr->lock;
# do some stuff
$mgr->unlock;

You should never have to use these methods.

lock and unlock open and call flock() on the file 'mgr.lock' in the manager's path. Writing to the invindex calls these methods implicitly.

If the lockfile is already locked, lock will die.

READING FROM INVINDEXES

searcher

my $searcher = $mgr->searcher;

my $hits = $mgr->search(%args);

Retrieve a searcher (using searcher_class).

search is a shortcut for $mgr->searcher->search.

PLUGINS

A manager class can add any number of plugins. Plugin names are assumed to be under KSx::IndexManager::Plugin:: unless they are prepended with a '+' (+My::KSx::Plugin).

Plugins can be added multiple times, possibly with different arguments. See KSx::IndexManager::Plugin::Partition for an example.

See KSx::IndexManager::Plugin for details of what plugins can do, and see add_plugin for details of adding them.

SEE ALSO

KinoSearch

AUTHOR

Hans Dieter Pearcey, <hdp@cpan.org>

BUGS

Please report any bugs or feature requests to bug-ksx-indexmanager at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=KSx-IndexManager. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc KSx::IndexManager

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to Listbox.com, who sponsored the original version of this module.

COPYRIGHT & LICENSE

Copyright 2007 Hans Dieter Pearcey, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.