/ 
Dezi-Client-0.003004
River stage one • 1 direct dependent • 1 total dependent
/ Dezi::Client

NAME

Dezi::Client - interact with a Dezi server

SYNOPSIS

use Dezi::Client;

# open a connection
my $client = Dezi::Client->new(
   server  => 'http://localhost:5000',
);

# add/update a filesystem document to the index
$client->index( 'path/to/file.html' );

# add/update an in-memory document to the index
$client->index( \$html_doc, 'foo/bar.html' );

# add/update a Dezi::Doc to the index
$client->index( $dezi_doc );

# remove a document from the index
$client->delete( '/doc/uri/relative/to/index' );

# search the index
my $response = $client->search( q => 'foo' );

# iterate over results
for my $result (@{ $response->results }) {
    printf("--\n uri: %s\n title: %s\n score: %s\n",
       $result->uri, $result->title, $result->score);
}

# print stats
printf("       hits: %d\n", $response->total);
printf("search time: %s\n", $response->search_time);
printf(" build time: %s\n", $response->build_time);
printf("      query: %s\n", $response->query);

DESCRIPTION

Dezi::Client is a client for the Dezi search platform.

METHODS

new( params )

Instantiate a Client instance. Expects the following params:

server url

The url of the Dezi server. If the search or index params are not passed to new(), then the server will be interrogated at initial connect for the correct paths for searching and indexing.

server_params params

Passed internally to URI::Query and appended to server url.

search path

The URI path for searching. Dezi defaults to /search.

index path

The URI path for indexing. Dezi defaults to /index.

username username
password password

If present, the username and password credentials will be set in each internal HTTP::Request object for any non-idempotent action (delete(), index(), commit(), rollback()).

index( doc [, uri, content-type, GET_params] )

Add or update a document. doc should be one of:

path

path should be a readable file on an accessible filesystem. path will be read with Search::Tools->slurp.

scalar_ref

scalar_ref should be a reference to a string representing the document to be indexed. If this is the case, then uri must be passed as the second argument.

dezi_doc

A Dezi::Doc object.

uri and content-type are optional, except in the scalar_ref case, where uri is required. If specified, the values are passed explicitly in the HTTP headers to the Dezi server. If not specified, they are (hopefully intelligently) guessed at.

Returns a HTTP::Response object which can be interrogated to determine the result. Example:

my $resp = $client->index( file => 'path/to/foo.html' );
if (!$resp->is_success) {
   die "Failed to add path/to/foo.html to the Dezi index!";
}

GET_params is an optional value. It is passed to URI::Query->new() internally and appended to the search_server/index URL.

search( params )

Fetch search results from a Dezi server. params can be any key/value pair as described in Search::OpenSearch::Engine. The only required key is q for the query string.

Returns a Dezi::Response object on success, or 0 on failure. Check the last_response() accessor for the raw HTTP::Response object.

my $resp = $client->search('q' => 'foo')
   or die "search failed: " . $client->last_response->status_line;

last_response

Returns the last HTTP::Response object that the Client object interacted with. Useful when search() returns false (HTTP failure). Example:

my $resp = $client->search( q => 'foo' );
if (!$resp) {
    die "Dezi search failed: " . $client->last_response->status_line;
}

delete( uri )

Remove a document from the server. uri must be the document's URI.

Returns a HTTP::Response object which can be interrogated to determine the result. A 200 response indicates success.

commit

Send a COMMIT HTTP request to the server. This is only useful if the server has been configured with:

engine_config => {
    auto_commit => 0,
}

Otherwise the server will not act on the index and will return a 400 response, indicating an invalid request.

If successful and at least one document was committed, returns a 200 response.

If successful and no documents were committed, returns a 204, indicating zero un-committed changes were pending.

commit() returns a HTTP::Response object which can be interrogated to determine the result.

rollback

Send a ROLLBACK HTTP request to the server. This is only useful if the server has been configured with:

engine_config => {
    auto_commit => 0,
}

Otherwise the server will not act on the index and will return a 400 response, indicating an invalid request.

If successful the server returns a 200 response.

rollback() returns a HTTP::Response object which can be interrogated to determine the result.

AUTHOR

Peter Karman, <karman at cpan.org>

BUGS

Please report any bugs or feature requests to bug-dezi-client at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dezi-Client. 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 Dezi::Client

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2011 Peter Karman.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.