Mark Allen Jensen > REST-Neo4p-0.2012 > REST::Neo4p::Agent

Download:
REST-Neo4p-0.2012.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  4
Stalled  1
View/Report Bugs
Module Version: 0.2000   Source   Latest Release: REST-Neo4p-0.3004

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.

REST::Neo4p::Agent will retry requests that fail with REST::Neo4p::CommException. The default number of retries is 3; the default wait time between retries is 5 sec. These can be adjusted by setting the package variables

 $REST::Neo4p::Agent::RQ_RETRIES
 $REST::Neo4p::Agent::RETRY_WAIT

to the desired values.

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::Exceptions 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::Exceptions 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.

syntax highlighting: