Permalink
Browse files

NOM-compatible release

  • Loading branch information...
1 parent bf07348 commit 5a1fd22bc351e2f256f1dd8ac6fca1947d74a5ac @bbkr committed Feb 9, 2012
Showing with 309 additions and 140 deletions.
  1. +0 −2 JSON RPC.xcodeproj/project.pbxproj
  2. +1 −1 META.info
  3. +50 −31 README.md
  4. +215 −55 lib/JSON/RPC/Client.pm
  5. +12 −4 lib/JSON/RPC/Error.pm
  6. +13 −19 lib/JSON/RPC/Server.pm
  7. +15 −27 t/client.t
  8. +3 −1 t/server.t
@@ -11,7 +11,6 @@
810601B514AA806A00E17399 /* logo_32x32.png */ = {isa = PBXFileReference; lastKnownFileType = image.png; path = logo_32x32.png; sourceTree = "<group>"; };
810601B714AA806A00E17399 /* client.t */ = {isa = PBXFileReference; lastKnownFileType = text; path = client.t; sourceTree = "<group>"; };
810601B814AA806A00E17399 /* META.info */ = {isa = PBXFileReference; lastKnownFileType = text; path = META.info; sourceTree = "<group>"; };
- 810601B914AA806A00E17399 /* README */ = {isa = PBXFileReference; lastKnownFileType = text; path = README; sourceTree = "<group>"; };
8111F01714CC345C00E4848B /* Server.pm */ = {isa = PBXFileReference; lastKnownFileType = text.script.perl; path = Server.pm; sourceTree = "<group>"; };
813E6FAE14CE0A9800F35FB7 /* README.md */ = {isa = PBXFileReference; lastKnownFileType = text; path = README.md; sourceTree = "<group>"; xcLanguageSpecificationIdentifier = xcode.lang.man; };
8150AE3314D09D5B005BAB23 /* Error.pm */ = {isa = PBXFileReference; lastKnownFileType = text.script.perl; path = Error.pm; sourceTree = "<group>"; };
@@ -27,7 +26,6 @@
810601B414AA806A00E17399 /* logotype */,
810601B614AA806A00E17399 /* t */,
810601B814AA806A00E17399 /* META.info */,
- 810601B914AA806A00E17399 /* README */,
);
sourceTree = "<group>";
};
View
@@ -1,7 +1,7 @@
{
"name" : "JSON::RPC",
"version" : "0.4",
- "description" : "JSON-RPC client and server",
+ "description" : "JSON-RPC 2.0 client and server",
"author" : "Pawel Pabian",
"authority" : "bbkr",
"depends" : [ "JSON::Tiny" ],
View
@@ -1,32 +1,42 @@
# JSON-RPC client and server
-Implements [spec](http://jsonrpc.org/spec.html "2.0 specification").
-
-
-## VERSION
-
-This module is compatible with Rakudo Star 2012.01+.
+Supports [spec](http://jsonrpc.org/spec.html "2.0 specification").
+Compatible with Rakudo Star 2012.01+.
## CLIENT
-Work in progress
+ use JSON::RPC::Client;
+
+ # create new client with url to server
+ my $c = JSON::RPC::Client.new( url => 'http://localhost:8080' );
+
+ # method without params
+ say $c.ping;
+
+ # method with positional params
+ say $c.hi( 'John Doe' );
+
+ # method with named params
+ say $c.hello( name => 'John Doe' );
## SERVER
-Define application class that will handle remote procedure calls.
+ use JSON::RPC::Server;
+ # define application class
+ # that will handle remote procedure calls
class My::App {
- # method without arguments
- method ping { return 'pong' }
+ # method without params
+ method ping { return 'pong' }
- # method with positional arguments
- method welcome ( Str $name! ) { return 'Hi ' ~ $name }
+ # method with positional params
+ method hi ( Str $name! ) { return 'Hi ' ~ $name }
- # method with named arguments
- method welcome ( Str :$name! ) { return 'Hi ' ~ $name }
+ # method with named params
+ method hello ( Str :$name! ) { return 'Hello ' ~ $name }
# multi method with different signatures
multi method offer ( Int $age where { $age < 8 } ) {
@@ -38,17 +48,19 @@ Define application class that will handle remote procedure calls.
}
-Start server with your application as handler.
-
+ # start server with your application as handler
JSON::RPC::Server.new( application => My::App ).run;
-Your server is now available at http://localhost:8080 .
+Your server is now available at *http://localhost:8080*.
-Jump to advanced stuff below if you like...
+## ADVANCED STUFF
-### Application
+Examples above _make easy things easy_.
+Now it is time to make _hard things possible_.
-* You can provide class name or object instance. Using class name results in static dispatch while using object instance allows you to initialize attributes in your class.
+### Should I use class name vs object instance as server handler?
+
+You can use both. Using class name results in static dispatch while using object instance allows you to initialize attributes in your class.
class My::App {
@@ -67,13 +79,18 @@ Jump to advanced stuff below if you like...
# BEGIN is called
JSON::RPC::Server.new( application => My::App.new ).run;
-* Declare methods as private if you do not wish server to dispatch to them.
+
+### How can method be excluded from server handler dispatch?
+
+Declare it as private.
method !get_database_info ( ) {
return 'username', 'password';
}
-* Validate params in signatures instead of method bodies. This way server correctly returns 'Invalid params' error and method is not called if signature does not match - you can easily separate validation from logic.
+### Should I declare signatures for server handler methods?
+
+It is recommended that you validate params in signatures instead of method bodies. This way server correctly returns 'Invalid params' error (more info later) and method is not called if signature does not match - you can easily separate validation from logic.
method add_programmer (
Str :$name!,
@@ -86,20 +103,24 @@ Jump to advanced stuff below if you like...
$!db.insert( $name, $age, $experience );
}
-* When request can be dispatched to more than one multi method then first candidate in definition order is chosen.
+### What will happen when more than one server handler candidate matches?
+
+When request can be dispatched to more than one multi method then first candidate in definition order is chosen. This is not an error.
+
+### Can I bind server to other port that 8080?
+
+Use port param.
-## ERRORS
+ JSON::RPC::Server.new( port => 9999 ...
+
+### Error handling
Server supports errors defined in 2.0 spec.
* Parse error - Invalid JSON was received by the server.
-
* Invalid Request - The JSON sent is not a valid Request object.
-
* Method not found - The method does not exist in your application.
-
* Invalid params - Invalid method parameters, no candidates with matching signature found.
-
* Internal error - Your method died. Catched message is returned as 'data' explanation field in Error object.
method divide ( Int $x, Int $y ) {
@@ -125,11 +146,9 @@ Server supports errors defined in 2.0 spec.
## TODO
-* Client
* Notification support in server
-* Support for older spec versions
+* 1.0 spec support
* Better documentation for RPC::Error namespace
-* Better documentation for positional vs. named params
## CONTACT
Oops, something went wrong.

0 comments on commit 5a1fd22

Please sign in to comment.