Java XML-RPC 3.1.x based web service example

Most of the examples of Java XML-RPC based Web Services are of older versions (apache xml-rpc 1.x or 2.x), most of the methods are deprecated and the programs don't work. So I am creating a simple backbone for XML-RPC based web service based on latest available i.e. Apache 3.1.3 version (last binaries dated 2013-01-31) to get started.

Eclipse Mars IDE
Java 7 version
JBoss 7.1 Application Server
Mac OS X 10.10.3 Operating system

commons-logging-1.1.jar
ws-commons-util-1.0.2.jar
xmlrpc-client-3.1.3.jar
xmlrpc-common-3.1.3.jar
xmlrpc-server-3.1.3.jar

package org.code2care.rpc;

import java.net.URL;

import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;


public class JavaWsClient {
   public static void main (String [] args) {
   
   
	   try {
			System.out.println("XML-RPC Client call to : http://localhost:1080/xmlrpc/xmlrpc");
			XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
			config.setServerURL(new URL(
					"http://localhost:1080/xml-rpc-example/xmlrpc"));
			XmlRpcClient client = new XmlRpcClient();
			client.setConfig(config);
			Object[] params = new Object[] { "Chris Martin" };
			String response = (String) client.execute("HelloWorld.message", params);
			System.out.println("Message : " + response);
			
		} catch (Exception e) {
			e.printStackTrace();
		}
    	    
    	   

    
   }
}

package org.code2care.rpc;

import org.apache.xmlrpc.server.PropertyHandlerMapping;
import org.apache.xmlrpc.server.XmlRpcServer;
import org.apache.xmlrpc.server.XmlRpcServerConfigImpl;
import org.apache.xmlrpc.webserver.WebServer;

public class JavaWsServer {
	
	private static final int PORT = 1080;
	
	public static void main(String[] args) {
		
		

		try {

			System.out.println("Starting XML-RPC 3.1.1 Server on port : "+PORT+" ... ");

			WebServer webServer = new WebServer(PORT);
			XmlRpcServer xmlRpcServer = webServer.getXmlRpcServer();

			PropertyHandlerMapping propHandlerMapping = new PropertyHandlerMapping();
			propHandlerMapping.load(Thread.currentThread().getContextClassLoader(), "handler.properties");
			xmlRpcServer.setHandlerMapping(propHandlerMapping);

			XmlRpcServerConfigImpl serverConfig = (XmlRpcServerConfigImpl) xmlRpcServer.getConfig();
		

			webServer.start();

			System.out.println("Server started successfully...");
		} catch (Exception exception) {
			System.out.println("Something went wrong while starting the server : ");
			exception.printStackTrace();
		}
	}
}

HelloWorld=org.code2care.rpc.HelloWorld

package org.code2care.rpc;

import java.net.URL;

import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;


public class JavaWsClient {
   public static void main (String [] args) {
   
   
	   try {
			System.out.println("XML-RPC Client call to : http://localhost:1080/xmlrpc/xmlrpc");
			XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
			config.setServerURL(new URL(
					"http://localhost:1080/xml-rpc-example/xmlrpc"));
			XmlRpcClient client = new XmlRpcClient();
			client.setConfig(config);
			Object[] params = new Object[] { "Chris Martin" };
			String response = (String) client.execute("HelloWorld.message", params);
			System.out.println("Message : " + response);
			
		} catch (Exception e) {
			e.printStackTrace();
		}

   }
}

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://java.sun.com/xml/ns/javaee"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
	id="WebApp_ID" version="3.0">
	<display-name>xml-rpc-example</display-name>
	<welcome-file-list>
		<welcome-file>index.jsp</welcome-file>
	</welcome-file-list>

	<servlet>
		<servlet-name>xmlrpc</servlet-name>
		<servlet-class>org.apache.xmlrpc.webserver.XmlRpcServlet</servlet-class>
		<init-param>
			<param-name>enabledForExtensions</param-name>
			<param-value>true</param-value>

		</init-param>
	</servlet>
	<servlet-mapping>
		<servlet-name>xmlrpc</servlet-name>
		<url-pattern>/xmlrpc</url-pattern>
	</servlet-mapping>

</web-app>

1. Start the Application Server: Apache/JBoss

2. Now first start Server component : JavaWsServer by right click -> Run As -> Java Application

3. Once the server is started successfully run Client: JavaWsClient by right click -> Run As -> Java Application

Output :

XML-RPC Client call to: http://localhost:1080/xmlrpc/xmlrpc
Message: Hello from the remote place! Chris Martin
Some of the issues you may face and how to solve them :
Nothing works right for the first time, here are some of the exceptions, error that you may face and how to resolve them.

Something went wrong while starting the server : 
java.net.BindException: Permission denied

	at java.net.PlainSocketImpl.socketBind(Native Method)
	at java.net.AbstractPlainSocketImpl.bind(AbstractPlainSocketImpl.java:382)
	at java.net.ServerSocket.bind(ServerSocket.java:375)
	at java.net.ServerSocket.(ServerSocket.java:237)
	at org.apache.xmlrpc.webserver.WebServer.createServerSocket(WebServer.java:164)
	at org.apache.xmlrpc.webserver.WebServer.setupServerSocket(WebServer.java:183)
	at org.apache.xmlrpc.webserver.WebServer.start(WebServer.java:218)
	at org.code2care.rpc.JavaWsServer.main(JavaWsServer.java:31)

You may get BindException if you use a port that is less than or equal to 1024, all Unix-based systems do not allow these ports unless you have privileges to root. This issue can be resolved by using some port that is greater than 1024. I have used 1080 port, also make sure that you do not use ports used by other services like Apache Tomcat: 8080 e.t.c if running.

java.net.BindException: Address already in use
	at java.net.PlainSocketImpl.socketBind(Native Method)
	at java.net.AbstractPlainSocketImpl.bind(AbstractPlainSocketImpl.java:382)
	at java.net.ServerSocket.bind(ServerSocket.java:375)
	at java.net.ServerSocket.(ServerSocket.java:237)
	at org.apache.xmlrpc.webserver.WebServer.createServerSocket(WebServer.java:164)
	at org.apache.xmlrpc.webserver.WebServer.setupServerSocket(WebServer.java:183)
	at org.apache.xmlrpc.webserver.WebServer.start(WebServer.java:218)
	at org.code2care.rpc.JavaWsServer.main(JavaWsServer.java:30)

Again this is an issue related to ports, either some other service is running on the port, or your server component is already running. resolution BindException

java.io.IOException: Unable to locate resource handler.properties
	at org.apache.xmlrpc.server.PropertyHandlerMapping.load(PropertyHandlerMapping.java:53)
	at org.code2care.rpc.JavaWsServer.main(JavaWsServer.java:24)
IOException because you either placed the properties file in wrong location or name mismatch : how to resolve IOException

org.apache.xmlrpc.XmlRpcException: No such handler: HelloWorld.message
	at org.apache.xmlrpc.client.XmlRpcStreamTransport.readResponse(XmlRpcStreamTransport.java:197)
	at org.apache.xmlrpc.client.XmlRpcStreamTransport.sendRequest(XmlRpcStreamTransport.java:156)
	at org.apache.xmlrpc.client.XmlRpcHttpTransport.sendRequest(XmlRpcHttpTransport.java:143)
	at org.apache.xmlrpc.client.XmlRpcSunHttpTransport.sendRequest(XmlRpcSunHttpTransport.java:69)
	at org.apache.xmlrpc.client.XmlRpcClientWorker.execute(XmlRpcClientWorker.java:56)
	at org.apache.xmlrpc.client.XmlRpcClient.execute(XmlRpcClient.java:167)
	at org.apache.xmlrpc.client.XmlRpcClient.execute(XmlRpcClient.java:137)
	at org.apache.xmlrpc.client.XmlRpcClient.execute(XmlRpcClient.java:126)
	at org.code2care.rpc.JavaWsClient.main(JavaWsClient.java:21)

This gets a bit tricky, it may occur when you try to run the client, the reasons that may cause this issue,

You may have misspelled the method call name
You may have specified the wrong URL, check the URL specified and web.xml configuration.
Make sure that the web.xml file is configured correctly

org.apache.xmlrpc.XmlRpcException: Failed to read server's response: Connection refused
	at org.apache.xmlrpc.client.XmlRpcStreamTransport.sendRequest(XmlRpcStreamTransport.java:161)
	at org.apache.xmlrpc.client.XmlRpcHttpTransport.sendRequest(XmlRpcHttpTransport.java:143)
	at org.apache.xmlrpc.client.XmlRpcSunHttpTransport.sendRequest(XmlRpcSunHttpTransport.java:69)
	at org.apache.xmlrpc.client.XmlRpcClientWorker.execute(XmlRpcClientWorker.java:56)
	at org.apache.xmlrpc.client.XmlRpcClient.execute(XmlRpcClient.java:167)
	at org.apache.xmlrpc.client.XmlRpcClient.execute(XmlRpcClient.java:137)
	at org.apache.xmlrpc.client.XmlRpcClient.execute(XmlRpcClient.java:126)
	at org.code2care.rpc.JavaWsClient.main(JavaWsClient.java:21)

Make sure the port specified for the client and server are the same.