/ 
CouchDB-ExternalProcess-0.01
River stage zero No dependents
/ CouchDB::ExternalProcess

NAME

CouchDB::ExternalProcess - Make creating Perl-based external processs for CouchDB easy

SYNOPSIS

In C<MyProcess.pm>:
---------------------------------------------------------------------------
package MyProcess;
use base qw/CouchDB::ExternalProcess/;

sub _before {
    my ($self, $request) = @_;
    # Do something with the hashref $request
    return $request;
}

sub hello_world :Action {
    my ($self, $req) = @_;
    my $response = {
        body => "Hello, " . $req->{query}->{greeting_target} . "!"
    };
    return $response;
}

sub _after {
    my ($self,$response) = @_;
    # Do something with the hashref $response
    return $response;
}

---------------------------------------------------------------------------

In CouchDB's C<local.ini>:
---------------------------------------------------------------------------
[external]
my_process = perl -MMyProcess -e 'MyProcess->new->run'

[httpd_db_handlers]
_my_process = {couch_httpd_external, handle_external_req, <<"my_process">>}
---------------------------------------------------------------------------

Now queries to the database I<databaseName> as:

  C<http://myserver/databaseName/_my_process/hello_world/?greeting_target=Sally>

Will return a document with Content-Type "text/html" and a body containing:

  C<Hello, Sally!>

The power really comes when the External Process API is used to generate and
parse JSON requests.

See L<http://wiki.apache.org/couchdb/ExternalProcesses>

DESCRIPTION

This module makes creating CouchDB External Processes simple and concise.

USAGE

METHODS

new

Create an external process, just needs C<run()> to be called to start processing
STDIN.

run

Run the action, read lines from STDIN and process them one by one

Named arguments can be passed to run like run(a => 1, c => 2). 

Accepted arguments are:
in_fh

File Handle to read input from. *STDIN by default

out_fh

File handle to write output to. *STDOUT by default

jsonParser

getter/setter for the JSON::Any instance used for an instance.

All methods of an ExternalProcess class should use this processor so they can
share the same magical 'true' and 'false' markers.

CHILD CLASS METHODS

These methods may be overridden by child classes to add processing to various
parts of the script and request handling lifecycle

_init

Called at program startup before any requests are processed.

_destroy

Called when STDIN is closed, or at program termination (if possible)

_before

Receives, and can manipulate or replace, the JSON request as hash reference
produced by JSON::Any before the requested action is processed.

_after

Passed the return value of whatever action was called, as a hash reference
parseable by JSON::Any. May modify or replace it.

_error

Passed any errors that occur during processing. Returns a hash reference to be
used as the response.

The default response for an error $error is:
    {
    code => 500,
    json => {
        error => $error
    }
}

_extract_action_name

Extracts the name of the action to handle a request. 

Receives the request object. Defaults to:

C<$req->{path}->[2]>

INTERNAL METHODS

_process

Process a request.

Receives one argument, a JSON string, does all CouchDB::ExternalProcess
processing and returns a valid External Process response.

_meta

Returns metadata about the methods we're providing

Action

Processes 'Action' Attribute

Description

Processes 'Description' Attribute

Args

Processes 'Args' Attribute

attrArgs

Helper method to process Attribute::Handlers arguments

BUGS

SUPPORT

AUTHOR

Mike Walker
CPAN ID: FANSIPANS
mike-cpan-couchdb-externalprocess@napkindrawing.com
http://napkindrawing.com/

COPYRIGHT

This program is free software licensed under the...

The BSD License

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

perl(1).

CouchDB ExternalProcesses http://wiki.apache.org/couchdb/ExternalProcesses