NAME

REST::Neo4p::Batch - Mixin for batch processing

SYNOPSIS

 use REST::Neo4p;
 use REST::Neo4p::Batch;
 use List::MoreUtils qw(pairwise);

 my @bunch = map { "new_node_$_" } (1..100);
 my @nodes;
 batch {
  my $idx = REST::Neo4p::Index->new('node','bunch');
  @nodes = map { REST::Neo4p::Node->new({name => $_}) } @bunch;
  pairwise { $idx->add_entry($a, name => $b) } @nodes, @bunch;
  $nodes[$_]->relate_to($nodes[$_+1],'next_node') for (0..$#nodes-1);
 } 'keep_objs';

 $idx = REST::Neo4p->get_index_by_name('node','bunch');
 ($the_99th_node) = $nodes[98];
 ($points_to_100th_node) = $the_99th_node->get_outgoing_relationships;
 ($the_100th_node) = $idx->find_entries( name => 'new_node_100');

DESCRIPTION

REST::Neo4p::Batch adds some syntactic sugar allowing ordinary REST::Neo4p code to be processed through the Neo4j REST batch API.

batch {} ($action)

To execute server calls generated by REST::Neo4p code, wrap the code in a batch block:

 batch {
  # create and manipulate REST::Neo4p objects
 } $action;

The $action parameter must be (there is no default) one of

• 'keep_objs'

  If keep_objs is specified, any nodes, relationships or indexes returned in the server reponse will be created in memory as REST::Neo4p objects. This is more time-efficient if the program plans to use the objects subsequently.

• 'discard_objs'

  If discard_objs is specified, Neo4j entities in the server response will not be automatically registered as REST::Neo4p objects. Of course, these objects can be retrieved from the server through object creation and other methods, outside of the batch block. This is more space efficient if the program does not plan to use the objects subsequently:

   #!perl
   # loader...
   use REST::Neo4p;
   use REST::Neo4p::Batch;
   
   open $f, shift() or die $!;
   batch {
     while (<$f>) {
      chomp;
      ($name, $value) = split /\t/;
      REST::Neo4p::Node->new({name => $name, value => $value});
     } 'discard_objs';
   exit(0);

Errors in batch jobs

batch{}() returns returns an array of REST::Neo4p::Exceptions error objects for each job that returns a server-generated error. If no errors were encountered, it returns undef.

 foreach ( batch { _do_stuff() } 'discard_objs' ) {
   print STDERR $_->message, "(", $_->code, ")\n";
 }

batch will warn() for each error immediately if $REST::Neo4p::VERBOSE is set.

CAVEATS

• No call to the server is made until after the block is executed. There is some magic provided, but not all object functionality is available to REST::Neo4p entities obtained within the batch block.

  For example, this works:

   my $idx = REST::Neo4p::Index->new('node' => 'pals_of_bob');
   my $name = 'fred'
   batch {
    my $node = REST::Neo4p::Node->new({name => $name});
    $idx->add_entry($node, name => $name);
   } 'keep_objs';

  but this does not:

   my $idx = REST::Neo4p::Index->new('node' => 'pals_of_bob');
   my $name = 'fred'
   batch {
    my $node = REST::Neo4p::Node->new({name => $name});
    $idx->add_entry($node, name => $node->get_property('name'));
   } 'keep_objs';

  because $node has not been created on the server at the time that add_entry() is executed.

SEE ALSO

REST::Neo4p, REST::Neo4p::Agent

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.