view release on metacpan or  search on metacpan

JRPC/Client.pm  view on Meta::CPAN

# Send Requests to a JSON-RPC Service.
# We completely ride on the wonderful LWP Module.
{
package JRPC::Client;
#
use LWP;
use LWP::UserAgent;
use base ('LWP::UserAgent');
use JSON::XS;
use Data::Dumper;

#our $mime;
#BEGIN {
# De-facto JSON-RPC Mime type
our $mime = 'application/json';
#};

=head1 NAME

JRPC::Client - JSON-RPC 2.0 Client

=head1 SYNOPSIS

   use JRPC::Client;

   my $client = JRPC::Client->new();
   $req = $client->new_request("http://jservices.com/WorldTime");
   my $resp = $req->call('Timeinfo.getlocaltime', {'tzname' => 'CET', 'clockhrs' => '24'});
   if (my $err = $resp->error()) { die("$err->{'message'}"); }
   my $res = $resp->result();
   print("Local time in CET is: $res->{'timeiso'}\n");

=head1 DESCRIPTION

JRPC::Client is a Perl LWP based JSON-RPC 2.0 Client hoping to minimize tedious boilerplate code for JSON-RPC
interaction, yet enabling advanced use cases by the power of LWP / HTTP::Request.

JRPC::Client complies to conventions of JSON-RPC 2.0, but it can be coerced to be used for other versions as well.

=head2 $client = JRPC::Client->new()

Instantiate a new JSON-RPC (2.0) Client.
HTTP keep-alive is turned on, cookie store is established and
default user-agent name is set here.
Any of the LWP::UserAgent methods are callable on the returned object as JRPC::Client IS-A LWP::UserAgent.

The lifetime of the JRPC::Client can be kept long (e.g. throughout app) and it can usually be kept as single instance
in app runtime (singleton, however JRPC::Client does not control singularity of instantiation).
The factory method method new_request() takes care of instatiating requests for various URL:s, various methods.

=cut
sub new {
  my ($class, %c) = @_;
  my $ua = LWP::UserAgent->new('keep_alive' => 1, 'cookie_jar' => {});
  $ua->agent("JSON-RPC Client/0.9");
  if ($c{'jsonrpc'}) {$ua->{'_jsonrpc'} = $c{'jsonrpc'};}
  # Re-bless ...
  return bless($ua, $class);
}

=head2 $req = $client->new_request($url, %opts)

Factory method to instantiate and prepare a new JSON-RPC request to a URL. Options in %opts:

=over 4 

=item * 'mime' - Mime content-type for request (default: 'application/json')

=item * 'debug' - Dump Request after instantiation (to STDERR).

=back



=cut
sub new_request {
   my ($ua, $url, %c) = @_;
  # 'mime' - Special mime type to use (default: 'application/json')
  my $req = HTTP::Request->new('POST', $url);
  
  $req->content_type($c{'mime'} || $mime); # text/plain
  #if ($c{'cred'}) {$req->header('Authorization', "Basic $c{'cred'}");}
  # Need to associate agent to request for call-phase
  $req->{'_ua'} = $ua;
  # Rebless to JRPC::Client::Request. @ISA / use base takes care of HTTP::Request methods being callable.
  bless($req, 'JRPC::Client::Request');
  if ($c{'debug'}) {print(STDERR Dumper($req));} # Store persistently: $req->{'_jsonrpcdebug'} = $c{'debug'};
  # Verification / Sanity check
  if (!$req->isa('HTTP::Request')) {die("NOT a HTTP::Request");}
  return($req);
}