XML-RPC provides a straightforward XML-based mechanism for providing web-based services such as publishing information. Any OFBiz Service may act as an XML-RPC web service provider simply by setting the Service's export configuration setting to true and using the OFBiz XML-RPC event handler (org.ofbiz.webapp.event.XmlRpcEventHandler) wrapper to receive XML-RPC requests and route them to the proper OFBiz Service for handling.
OFBiz provides an XML-RPC event handler, extending the basic XmlRpcHttpServer that comes with the integrated Apache XML-RPC libraries. To use it, you must include an entry in a controller.xml file of the web application where the XML-RPC call will be published. This entry should look something like the following. (If the following line does not already exist either within the common-controller.xml file or your local web application's controller.xml file, add it to either file):
<handler name="xmlrpc" type="request" class="org.ofbiz.webapp.event.XmlRpcEventHandler"/>
You must also include a request-map similar to the following that instructs the OFBiz controller for the web application handling the XML-RPC request to use the generic OFBiz XML-RPC handler:
<!-- No need to track server hits or visits for an XML-RPC URI --> <!-- Also note: the XML-RPC request will contain the name of the OFBiz Service to call --> <request-map uri="xmlrpc" track-serverhit="false" track-visit="false"> <event type="xmlrpc"/> <response name="error" type="none"/> <response name="success" type="none"/> </request-map>
Finally, the target Service called through the XML-RPC execute method must exist and must have, in its Service definition, the export flag set to true. For example, if the following client call (in Java) is invoked by a remote consumer:
<service name="myTestService" engine="java" export="true" validate="false" require-new-transaction="true" location="org.ofbiz.common.CommonServices" invoke="testService"> <description>Test service</description> <attribute name="defaultValue" type="Double" mode="IN" default-value="999.9999"/> <attribute name="message" type="String" mode="IN" optional="true"/> <attribute name="resp" type="String" mode="OUT"/> </service>
To enable XML-RPC service provider, follow these steps:
- Create a Service as a method in any existing OFBiz Service's class (or create a new class) that takes the standard OFBiz Service's context map parameters and processes them. For example, the following OFBiz Service is called
myTestService. This Service could be deployed using the Service definition shown:public static Map<String, Object> myTestService( DispatchContext dctx, Map<String, ?> context) { Map<String, Object> response = ServiceUtil.returnSuccess(); if (context.size() > 0) { for (Map.Entry<String, ?> entry: context.entrySet()) { Object cKey = entry.getKey(); Object value = entry.getValue(); // Process Service parameters } } return response; } - Rebuild the Component containing the new Service.
- Restart OFBiz.
- Test with an XML-RPC client.
The OFBiz XML-RPC event handler acts as a wrapper for any OFBiz Service that may want to provide web services based on the XML-RPC specification. It is called from the controller servlet when HTTP/HTTPS request messages are received for the configured URL.
The XML-RPC event handler, based on the Java Apache XML-RPC libraries, manages all the web service interface details such as extracting the XML elements from the request message and passing those to the target Service as name/value pairs (in the standard OFBiz Service context map.) It also handles authentication and the formatting of the HTTP/HTTPS response message, based on the results returned from the Service call, to the web service consumer.
As a result, the developer of any XML-RPC web service need only concentrate on the business logic of the Service and not on the details of implementing the XML-RPC specification.