NAME

REST::Neo4p::Agent - LWP client interacting with Neo4j

SYNOPSIS

$agent = REST::Neo4p::Agent->new();
$agent->server('http://127.0.0.1:7474');
unless ($agent->connect) {
 print STDERR "Didn't find the server\n";
}

See examples under "METHODS" below.

DESCRIPTION

The agent's job is to encapsulate and connect to the REST service URLs of a running neo4j server. It also stores the discovered URLs for various actions. and provides those URLs as getters from the agent object. The getter names are the keys in the JSON objects returned by the server. See http://docs.neo4j.org/chunked/milestone/rest-api.html for more details.

API and HTTP errors are distinguished and thrown by Exception::Class subclasses. See REST::Neo4p::Exceptions.

REST::Neo4p::Agent is a subclass of LWP::UserAgent and inherits its capabilities.

According to the Neo4j recommendation, the agent requests streamed responses by default (i.e.,

X-Stream:true

is a default header. This can be removed by calling

$agent->no_stream

and added back with

$agent->stream

For batch API experimental features, see "Batch Mode".

METHODS

new()

$agent = REST::Neo4p::Agent->new();
$agent = REST::Neo4p::Agent->new("http://127.0.0.1:7474");

Returns a new agent. Accepts optional server address arg.

server()

$agent->server("http://127.0.0.1:7474");

Sets the server address and port.

data()

$neo4j_data_url = $agent->data();

Returns the base of the Neo4j server API.

admin()

$neo4j_admin_url = $agent->admin();

Returns the Neo4j server admin url.

node()

reference_node()

node_index()

relationship_index()

extensions_info

relationship_types()

batch()

cypher()

$relationship_type_url = $agent->relationship_types;

These methods get the REST URL for the named API actions. Other named actions may also be available for a given server; these are auto-loaded from self-discovery responses provided by Neo4j. Use available_actions() to identify them.

You will probably prefer using the "get_{action}()", "put_{action}()", "post_{action}()", and "delete_{action}()" methods to make requests directly.

neo4j_version()

$version = $agent->neo4j_version;

Returns the version of the connected Neo4j server.

available_actions()

@actions = $agent->available_actions();

Returns all discovered actions.

location()

$agent->post_node(); # create new node
$new_node_url = $agent->location;

Returns the value of the "location" key in the response JSON.

get_{action}()

$decoded_response = $agent->get_data(@url_components,\%rest_params)
$types_array_ref = $agent->get_relationship_types();

Makes a GET request to the REST endpoint mapped to {action}. Arguments are additional URL components (without slashes). If the final argument is a hashref, it will be sent as key-value form parameters.

put_{action}()

# add a property to an existing node
$agent->put_node([13, 'properties'], { name => 'Herman' });

Makes a PUT request to the REST endpoint mapped to {action}. The first argument, if present, must be an array reference of additional URL components. The second argument, if present, is a hashref that will be sent in the request as (encoded) JSON content. The third argument, if present, is a hashref containing additional request headers.

post_{action}()

# create a new node with given properties
$agent->post_node({ name => 'Wanda' });
# do a cypher query and save content to file
$agent->post_cypher([], { query => 'START n=node(*) RETURN n', params=>{}},
                    { ':content_file' => $my_file_name });

Makes a POST request to the REST endpoint mapped to {action}. The first argument, if present, must be an array reference of additional URL components. The second argument, if present, is a hashref that will be sent in the request as (encoded) JSON content. The third argument, if present, is a hashref containing additional request headers.

delete_{action}()

$agent->delete_node(13);
$agent->delete_node_index('myindex');

Makes a DELETE request to the REST endpoint mapped to {action}. Arguments are additional URL components (without slashes). If the final argument is a hashref, it will be sent in the request as (encoded) JSON content.

decoded_response()

$decoded_json = $agent->decoded_response;

Returns the response content of the last agent request, as decoded by JSON. It is generally a reference, but can be a scalar if a bareword was returned by the server.

no_stream()

$agent->no_stream;

Removes X-Stream: true from the default headers.

stream()

$agent->stream;

Adds X-Stream: true to the default headers.

Batch Mode

When the agent is in batch mode, the usual request calls are not executed immediately, but added to a queue. The "execute_batch()" method sends the queued calls in the format required by the Neo4p REST API (using the post_batch method outside of batch mode). "execute_batch()" returns the decoded json server response in the return format specified by the Neo4p REST batch API.

batch_mode()

print ($agent->batch_mode ? "I am " : "I am not ")." in batch mode\n";
$agent->batch_mode(1);

Set/get current agent mode.

batch_length()

if ($agent->batch_length() > $JOB_LIMIT) {
  print "Queue getting long; better execute\n"
}

Returns current queue length. Throws REST::Neo4p::LocalException if agent not in batch mode.

execute_batch()

$tempfile_name = $agent->execute_batch();

while (my $tmpf = $agent->execute_batch(50)) {
  # handle responses
}

Processes the queued calls and returns the decoded json response from server in a temporary file. Returns with undef if batch length is zero. Throws REST::Neo4p::LocalException if not in batch mode.

Second form takes an integer argument; this will submit the next [integer] jobs and return the server response in the tempfile. The batch length is updated.

You are responsible for unlinking the tempfile.

execute_batch_chunk()

while (my $tmpf = $agent->execute_batch_chunk ) {
 # handle response
}

Convenience form of execute_batch($REST::Neo4p::JOB_CHUNK). $REST::Neo4p::JOB_CHUNK has default value of 1024.

AUTHOR

Mark A. Jensen
CPAN ID: MAJENSEN
majensen -at- cpan -dot- org

LICENSE

Copyright (c) 2012 Mark A. Jensen. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.