<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<meta name="description" content="SourceForge presents the java-json-rpc project. java-json-rpc is an open source application. SourceForge provides the world's largest selection of Open Source Software. Json-rpc 2.0 server imlpementation in java." />
<meta name="keywords" content="Open Source, Software, Development, Developers, SF.net, SourceForge, Java, JSON, RPC, JSON-RPC, Libraries, Networking, GNU General Public License (GPL), java-json-rpc,java-json-rpc" />
<title>
Java-json-rpc library
</title>
</head>
<body>
<h1>Java-json-rpc library</h1>
<h2>Overview</h2>
<p>
Java-json-rpc is library implementing JSON-RPC 2.0. Specification proposal can be found at <a href="http://groups.google.com/group/json-rpc/web/json-rpc-2-0">here</a>. Reason for this library is lack of good JSON-RPC implementations in java, especially on server side. It is distributed under GPL license.
Library has implemented HTTP(using servlets)/TCP server and very simple HTTP/TCP clients.
</p>
<p>
<a href="javadoc">javadoc</a>.
</p>
<h2>Features</h2>
<p>
Java-json-rpc uses as definition of JSON-RPC services service class implementations, all that is needed to do is to add class to config of JsonRpcServlet in web.xml and that's it.
</p>
<h2>Installation - HTTP SERVER</h2>
<ul>
<li>Download java-json-rpc jar from <a href="http://sourceforge.net/projects/java-json-rpc/files/">downloads</a> and add it to your classpath.</li>
<li>Download dependencies - <a href="http://logging.apache.org/log4j/1.2/download.html">log4j</a> and jackson-core, jackson-mapper from <a href="http://wiki.fasterxml.com/JacksonDownload">Jackson download page</a> and add them to your classpath.</li>
<li>Edit your web.xml - add JsonRpcServlet. Add services. Services are added as init parameters to servlet where key is url of webservice and value is full classname of webservice as shown in example
<pre>
<servlet>
<servlet-name>JsonRpcServlet</servlet-name>
<display-name>JsonRpcServlet</display-name>
<servlet-class>cz.eman.jsonrpc.server.JsonRpcServlet</servlet-class>
<init-param>
<param-name>test1</param-name>
<param-value>cz.eman.jsonrpc.server.example.WebService</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>JsonRpcServlet</servlet-name>
<url-pattern>/jsonrpc/*</url-pattern>
</servlet-mapping>
</pre>
Class must have public default constructor, all public non-static classes will be exposed. Complex types in methods must have public default constructor.<br />
</li>
<li>Start your application, go to url of your JsonRpcServlet (in our case it is ROOT_OF_APPLICATION/jsonrpc/list) and check definitions of exposed services.</li>
<li>Enjoy calling your methods! :)</li>
</ul>
<h2>Calling with named parameters</h2>
JSON-RPC specification allows sending parameters as <i>map</i>. Unfortunately java doesn't by default name parameters of methods. One way is to always send parameters in the correct order and server will ignore parameter names. Another approach is to annotate every parameter of service method with annotation cz.eman.jsonrpc.shared.ParameterName which will name it. Example:
<pre>
public void count(@ParameterName("car") Car car, @ParameterName("house") House house) { ... }
</pre>
<h2>TCP Server example</h2>
There are currently 2 implementations of TCP server - single and multithreaded. They are both used same way, just multithreaded can work with more clients at once.
To start multithreaded server use:
<pre>
new TcpJsonMultiServer(WebService.class, 20000);
</pre>
Where WebSerivce.class is implementation of service:
<pre>
public class WebService implements IMyService {
public Integer add(Integer a, Integer b) {
return a + b;
}
public B echo(B b) {
return b;
}
}
</pre>
To start singlethreaded server use:
<pre>
new TcpJsonSingleServer(WebService.class, 20000);
</pre>
<h2>HTTP/TCP Client example</h2>
If you have interface of webservice, for example like this:
<pre>
public interface IMyService {
Integer add(Integer a, Integer b) throws IOException;
B echo(B b) throws IOException;
}
</pre>
If you want to create client for this service, you must extend class from AbstractClientProxy:
<pre>
public class WebServiceClientProxy extends AbstractClientProxy<IMyService> implements IMyService {
public WebServiceClientProxy(ClientProvider clientProvider) {
super(IMyService.class, clientProvider);
}
@Override
public B echo(B b) throws IOException {
return (B) super.callMethod("echo", b);
}
@Override
public Integer add(Integer a, Integer b) throws IOException {
return (Integer) super.callMethod("add", new Object[] { a, b });
}
}
</pre>
Note that it isn't necessary for thi class to implement IMyService or any, but it is better for code. All you have to do is to map parameters like as shown in method add and echo. Also don't use primitive type, use their wrappers instead.
<br />
Now that you have proxy, you need ClientProvider. If you want http client, use proxy like this:
<pre>
WebServiceClientProxy proxy = new WebServiceClientProxy(new HttpJsonClient(new URL("http://localhost/json-rpc-testserver/jsonrpc/test1")));
System.out.println(proxy.add(1, 2));
System.out.println(proxy.echo(new B()));
</pre>
If you want tcp client:
<pre>
WebServiceClientProxy proxy = new WebServiceClientProxy(new TcpJsonClient(new Socket("localhost", 20000)));
System.out.println(proxy.add(1, 2));
System.out.println(proxy.echo(new B()));
</pre>
<h2>TODO</h2>
<ul>
<li>Error code returning according to specification</li>
<li>jUnit</li>
</ul>
<h2>Contact</h2>
You can contact me at my gmail account hovi6337 or project <a href="https://sourceforge.net/projects/java-json-rpc/forums/forum/1223566">open discussion</a>. I will welcome any feedback and/or comments :)
</body>
</html>
