Hessian::Tiny::Client - Hessian RPC Client implementation in pure Perl
Version 0.12
use Hessian::Tiny::Client; my $foo = Hessian::Tiny::Client->new( url => 'http://hessian.service.com/serviceName', version => 2, # hessian protocol version ); my($stat,$res) = $foo->call('add',2,4); if($stat == 0){ # success print "2 + 4 = $res"; }else{ print "error: $Hessian::Tiny::Client::Error"; }
Hessian is a compact binary protocol for web communication in form of client/server RPC.
This module allows you to write Hessian clients in Perl.
This module supports Hessian Protocol 1.0 and 2.0
Perl 5.6.0 or later is required to install this modle.
my $foo = Hessian::Tiny::Client->new( url => 'http://hessian.service.com/serviceName', # mandatory version => 2, # default is 1 debug => 1, # add some debugging output (to STDERR) auth => [$http_user,$http_pass], # http basic auth, if needed hessian_flag => 1, # if you need strong typing in return value );
hessian server url, need to be a valid url, otherwise the constructor will return undef.
hessian protocol version, 1 or 2.
for debugging, you probably don't need to set this flag.
if http server requires authentication. (passed on to LWP request)
default off, that means return value are automatically converted into native perl data; if set to true, you will get Hessian::Type::* object as return.
# for convinience, simple types can be passed directly ($stat,$res) = $foo->call('addInt',1,2); # or use Hessian::Type::* for precise typing ($stat,$res) = $foo->call('method1', Hessian::Type::Date( Math::BigInt->new( $milli_sec ) ), Hessian::Type::Double( 3.14 ), Hessian::Type::List( length=>2, data=>[ Hessian::Type::String->new('unicode_stream'), Hessian::Type::Binary->new('bytes') ] ); Hessian::Type::Map( type=>'Car', data=>{ 'Make' => 'Toto', 'Modle' => 'XYZ' } ); ); # end call if($stat == 0){ # success }elsif($stat == 1){ # Hessian Fault print "Exception: $res->{code}, $res->{message}"; }else{ # communication failure print "error: $res"; }
$stat: 0 for success, 1 for Hessian level Fault, 2 for other errors such as http communication error or parsing anomaly;
$res: will hold the hessian call result if call was successful, or will hold error (Hessian::Fault or string) in case of unsuccessful call;
normally Hessian types are converted to perl data directly, if you want strong typing in return value, you can set (hessian_flag => 1) in the constructor call new().
$foo->call('argNull', Hessian::Type::Null->new() );
As return value, by default, you will get undef; when 'hessian_flag' is set to true, you will get Hessian::Type::Null.
$foo->call('argTrue', Hessian::Type::True->new() ); $foo->call('argFalse', Hessian::Type::False->new() );
As return value, by default, you will get 1 (true) or undef (false); when 'hessian_flag' is set to true, you will get Hessian::Type::True or Hessian::Type::False as return value.
$foo->call('argInt', 250 );
No extra typing for Integer type. Note, if the number passed in falls outside the range of signed 32-bit integer, it will be passed as a Long type parameter (64-bit) instead.
$foo->call('argLong', Math::BigInt->new(100000) ); # core module $foo->call('argLong', Hessian::Type::Long->new('100000') ); # same as above
As return value, by default, you will get string representation of the number; when 'hessian_flag' is set to true, you will get Math::BigInt.
$foo->call('argDouble', -2.50 ); # pass directly, if looks like floating point number $foo->call('argDouble', Hessian::Type::Double(-2.50) ); # equivalent
As return value, by default, you will get the number directly; when 'hessian_flag' is set to true, you will get Hessian::Type::Double. Note, floating point numbers may appear slightly inaccurate, due to the binary nature of machines (not the fault of protocol itself, or Perl even).
$foo->call('argDate', Hessian::Type::Date->new($milli_sec) ); $foo->call('argDate', DateTime->now() ); # if you have this module installed
As return value, by default, you will get epoch seconds; when 'hessian_flag' is set to true, you will get Hessian::Type::Date (milli sec inside).
$foo->call('argBinary', Hessian::Type::Binary->new("hello world\n") ); $foo->call('argString', Hessian::Type::String->new("hello world\n") ); $foo->call('argString', Unicode::String->new("hello world\n") );
As return value, by default, you will get the perl string; when 'hessian_flag' is set to true, you will get Hessian::Type::Binary or Hessian::Type::String object. (Binary means byte stream, while String is UTF-8)
$foo->call('argXML', Hessian::Type::XML->new( $xml_string ) );
As return value, by default, you will get xml string; when 'hessian_flag' is set to true, you will get Hessian::Type::XML. Note, XML type is removed from Hessian 2.0 spec.
$foo->call('argList', [1,2,3] ); # untyped fixed length list $foo->call('argList', Hessian::Type::List->new([1,2,3]); # same as above $foo->call('argList', Hessian::Type::List->new(length=>3,data=>[1,2,3],type=>'Triplet');
As return value, by default, you will get array ref; when 'hessian_flag' is set to true, you will get Hessian::Type::List.
$foo->call('argMap', {a=>1,b=>2,c=>3} ); # untyped map $foo->call('argMap', Hessian::Type::Map->new({a=>1,b=>2,c=>3} ); # same as above $foo->call('argMap', Hessian::Type::Map->new(type=>'HashTable',data=>{a=>1,b=>2,c=>3} ); # typed
As return value, by default, you will get hash ref (Tie::RefHash is used to allow non-string keys); when 'hessian_flag' is set to true, you will get Hessian::Type::Map.
my $x = Hessian::Type::Object->new( type => 'my.package.LinkedList', data => {_value => 1, _rest => undef} ); my $y = Hessian::Type::Object->new( type => 'my.package.LinkedList', data => {_value => 2, _rest => $x} ); $foo->call('argObject',$y);
As return value, by default, you will get hash_ref (Tie::RefHash is used to allow non-string keys); when 'hessian_flag' is set to true, you will get Hessian::Type::Object. Note, Object is essentially a typed Map.
Ling Du, <ling.du at gmail.com>
<ling.du at gmail.com>
Please report any bugs or feature requests to bug-hessian-tiny-client at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hessian-Tiny-Client. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-hessian-tiny-client at rt.cpan.org
Hessian::Tiny::Server, not sure if anyone will need to use the server part, except for testing maybe.
You can find documentation for this module with the perldoc command.
perldoc Hessian::Tiny::Client
For information on the wonderful protocol itself, take a look at: http://hessian.caucho.com/
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hessian-Tiny-Client
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Hessian-Tiny-Client
CPAN Ratings
http://cpanratings.perl.org/d/Hessian-Tiny-Client
Search CPAN
http://search.cpan.org/dist/Hessian-Tiny-Client/
Algo LLC.
Copyright 2010 Ling Du.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install Hessian::Tiny::Type, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Hessian::Tiny::Type
CPAN shell
perl -MCPAN -e shell install Hessian::Tiny::Type
For more information on module installation, please visit the detailed CPAN module installation guide.