Web Services in Apache OFBiz

Ruth Hoffman

September 2010


Apache OfBiz Cookbook

Apache OfBiz Cookbook

Over 60 simple but incredibly effective recipes for taking control of OFBiz

  • Optimize your OFBiz experience and save hours of frustration with this timesaving collection of practical recipes covering a wide range of OFBiz topics.
  • Get answers to the most commonly asked OFBiz questions in an easy-to-digest reference style of presentation.
  • Discover insights into OFBiz design, implementation, and best practices by exploring real-life solutions.
  • Each recipe in this Cookbook is crafted to describe not only "how" to accomplish a specific task, but also "why" the technique works to ensure you get the most out of your OFBiz implementation.

Read more about this book

(For more resources on Apache see here.)


Ask five people what "web services" are and you will likely get at least six different opinions. Because the term evokes such ambiguity, we need to set ground rules for this article and define what we mean by "web services". Therefore, for the purposes of this book, "web services" are the interactive exchange of messages from one system to another using the Internet as the network transport and HTTP/HTTPS as the messaging protocol. Message exchange transpires without human intervention and may be one-way—that is, called without an immediate response expected—or two-way.

Web services operate as producer/consumer systems where the producer—called the "service provider"—offers one or more "services" to the "consumer"—sometimes referred to as the "client". In the web services world, Internet-based service providers advertise and deliver service from locations throughout the Web. The Internet, and the Web in particular, serve as the highway over which potential web service clients travel to find service providers, make contact, and deliver products.

Service-oriented by design, OFBiz is a natural for building and deploying both web service clients and web service providers. Any OFBiz web application (webapp) may both consume web services and act as a web service provider within the same application or in an unlimited number of OFBiz webapps.

Within the web service producer/consumer model, service providers are responsible for accepting and validating requests for service and delivering the product. Consumers must find service providers, request service, and accept delivery of the product. There are a number of ad-hoc and formal standards that have evolved over the last few years to help facilitate the business of enabling web services, including, but not limited to, URL parameter passing, XML-RPC, and Simple Object Access Protocol (SOAP) based messaging. OFBiz provides builtin support with tools and integration points to make implementing both service provider and consumer web services a snap.

Requesting web services using URL parameters

There are many web service providers that require nothing more than URL parameter passing to request a service. These service providers take HTTP/HTTPS request parameters as appended to a prospective consumer's URL, and process requests according to the passed parameter values. Services are delivered back to the requestor through the client's HTTP/ HTTPS response message or as a separate HTTP/HTTPS request message exchange.

An example of such a real world web service is the PayPal Payments Standard payment processing service . This web service expects requests to come in on an advertised URL with request particulars appended to the URL as request parameters. Prospective consuming systems send HTTP/HTTPS request messages to the PayPal URL asking for service. Once a request for service has been accepted by PayPal, the Payments Standard web service responds and delivers service using the HTTP/HTTPS response message.

A separate web service, also involving PayPal, called the Instant Payment Notification (IPN) web service is an example of a web service in which parameters are passed on the URL from the service provider to a consumer such as OFBiz. In this case, OFBiz listens on a configured URL for an HTTP/HTTPS request message from PayPal. When one is received, OFBiz responds appropriately, taking delivery of PayPal service.

Note: to implement a PayPal IPN client within an OFBiz web application, you must provide PayPal a destination URL that maps to a valid OFBiz request-map, and then process any incoming URL parameters according to the PayPal IPN directions.

Getting ready

To act as a web service client and pass parameters on the URL within an OFBiz Java Event or Service, make sure you include the following Java packages in your program:

import java.io.IOException;
import java.net.URL;
import java.net.URLConnection;
import javax.Servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

How to do it...

To request a service using URL parameters, follow these steps:

  1. Within an existing OFBiz Java program (either an Event, Service, or any other) method, create a Java HashMap containing the name/value pairs that you wish to pass on the URL. For example:

    Map parameters = UtilMisc.toMap("param1", "A", "param2", "B");

  2. Use the OFBiz-provided UtilHttp.urlEncodeArgs method to properly encode the parameters directly from the HashMap into a Java String. For example:

    String encodedParameters = UtilHttp.urlEncodeArgs(parameters, false);

  3. Build a URL and add the encoded parameter string to the URL:

    String redirectUrl = "http://www.somehost.com";
    String redirectString = redirectUrl + "?" + encodedParameters;

  4. Send the request by way of the HttpServletResponse object's redirect method:

    try {
    catch (IOException e) {
    // process errors here
    return "error";

How it works...

In a very simple web service client scenario, OFBiz acts on behalf of a user or another OFBiz process and makes a web service consumer request of a remote service provider. The request is sent using a HTTP/HTTPS request message with one or more service parameters appended to the URL. The URL is the location on the web of the service provider.

Because the scenario described above is a one-way message exchange—that is, the request message is delivered to the destination URL, but OFBiz does not wait around for a response message—there must be assumptions made about how the web service provider will deliver service. Many times, service is delivered through a totally separate message exchange, initiated by first making the one-way request as described earlier.

To illustrate how this may play out, we consider the PayPal Payments Standard web service. This web service may be invoked from OFBiz in at least two different ways. For example, one approach is to include an HTML form on an OFBiz web page with a Submit button. The Submit button when clicked redirects the browser (with the request message) to the PayPal web service site passing the form contents as is.

An alternative implementation is to have an HTML form on an OFBiz web page with a Submit button that, when clicked, forwards the browser's request of an OFBiz Service (or Event). In this case, the OFBiz Event or Service will take the form attribute values (from the request message) and create a URL for the PayPal web service location. The original form attribute values and any other information as provided by the context or through database reads is appended to the URL. OFBiz then redirects the user's original request message using the sendRedirect method on the HttpServletResponse object to effectively send the user, by way of a browser and an appropriately crafted URL, to the PayPal web service.

Building URL request parameters out of plain Java strings can be tricky given the nature of the characters used to construct request parameters and delimit multiple parameter strings. For example, how do you pass a space character as part of a parameter when spaces are used as delimiters?

Enter URL encoding. URL encoding takes certain characters, deemed "special" characters, and "escapes" them so that they may be used as part of a request parameter string. OFBiz provides an easy-to-use encoder (and decoder) method(s): the UrlEncodeArgs method on the UtilHttp utility that takes as an argument a Java Map and returns an encoded string that may then be appended to a URL as shown earlier.

Note: an exhaustive treatment of URL encoding is beyond the scope of this article. For more information on HTML and ASCII character codes and encoding symbols, please see the HTML Codes page

There's more...

The UrlEncodeArgs method has two modes of operation: selecting the false method-parameter value will encode using only an ampersand (&) symbol while the true parameter value tells OFBiz to use &amp as the encoding string. Based on the web service provider's instructions, you will need to determine which mode is appropriate for your application.

Many web services do not require encoded values. You will need to verify for each service whether or not it is necessary to encode and decode URL parameters. For example, the PayPal IPN web service sends request parameters without any encoding. When returning IPN messages, the client web service is, however, instructed to encode parameters.

PayPal IPN is strictly a server-to-server (there is no human intervention) messaging system where message traffic is transported across the web from one server URL to another. PayPal is the web service provider while, in this scenario, OFBiz acts as the web service client. It works something like shown in the following diagram:

Requesting web services using an HttpClient

Many web services are implemented using HTTP/HTTPS request methods and parameters passed as part of the request's message body. These requests for service mimic a user sitting at a browser submitting HTML forms and waiting for server response. Service providers read HTTP/HTTPS request header information and name/value request message parameter pairs, and deliver service through the HTTP/HTTPS response message.

Writing clients for these types of web services usually require a synchronous call to the service provider. From within your OFBiz client code, you initiate a call to a service provider and then wait until a response (or timeout) is received. Unlike the PayPal Payments Standard service described earlier, the OFBiz client program does not redirect HTTP/HTTPS request messages to another URL.

There are a number of examples within the out-of-the-box OFBiz project of service providers that use the HTTP/HTTPS request message body to exchange information with OFBiz clients. They include, but are not limited to:

  • Authorize.net Payment Services
  • ClearCommerce Payment Services
  • Go Software RiTA
  • ValueLink Prepaid/Gift Card Payment Services
  • DHL, FedEx, United Parcel Services (UPS), and United States Post Office Shipping Services
  • CDYNE Web Based Services
  • PayPal Payments Pro

Getting ready

The first step in writing any web service client is to gather the following information about how the target web service operates:

  • The URL on the web for the service provider
  • Any connection parameters and/or HTTP/HTTPS request message header settings that must be passed as required by the service provider
  • The HTTP/HTTPS connection verb (get, post, or other)

Within a Java program, to send and receive web service messages as a client and use the built-in HTTP client utility provided by OFBiz, make sure you have the following Java packages imported in your program:

import org.ofbiz.base.util.HttpClient;
import org.ofbiz.base.util.HttpClientException;

How to do it...

You can request a web service by following these steps:

  1. Create a connection string that includes the URL of the target web service and the type of request:

    String connectString = "http://www.some_web_service_url.com/serviceName";

  2. Within your Java program, create an instance of the HttpClient object with the URL/connection string passed to the constructor as shown here:

    HttpClient http = new HttpClient(connectString);

  3. Create the content of your request as dictated by the target web service provider. For example, some web services expect XML documents; others, simple string parameters. A web service that expects a string of name/value pairs could be coded as follows:

    http.setParameter("Param1", "X");
    http.setParameter("Param2", "Y");

  4. Send your request using the appropriate method on the HttpClient object. For "get" requests, use the get method. For "post" requests, use the post method as shown here:

    try {
    response = http.post();
    catch (HttpClientException e) {
    // Process error conditions here

  5. Handle any service response inline. Unlike the asynchronous nature of the PayPal IPN web service described earlier, HttpClient based web services process return calls inline with the initial web service call. Under the covers, the HttpClient utility handles all the network connection set up and lower-level message transmissions.
  6. There is no need to release or close the connection as OFBiz manages the handoff of connections.

How it works...

When using the HttpClient to access web services remote to OFBiz, you send the consumer-side call synchronously; that is, you wait for the return from the remote web service call within your program. The OFBiz integration of the HttpClient utility manages the details necessary to open the network connection, maintain direct request and response message exchanges, and close the connection upon completion of processing.

There's more...

The OFBiz implementation of the HttpClient object provides several convenience constructors, which may be useful depending on your processing needs. These include:

// To create a new client object and connect using a URL object instead of a String
URL url = "https://www.some_host.com/";
HttpClient http = new HttpClient(url);

// To create a new client object using a Java Map containing request parameters
HttpClient http = new HttpClient(url, UtilMisc.toMap("param1", "X",
"param2", "Y");

//To create a new client object with a parameter map and header settings
HttpClient http = new HttpClient(connectString,
UtilMisc.toMap("param1", "X"),
UtilMisc.toMap("User-Agent, "Mozilla/4.0"));

See also

OFBiz provides an integration of the Apache HttpClient software package: the Jakarta Commons HTTP Client that is accessed by creating a new HttpClient object. Any method you can call on, the original Apache HttpClient object is available in the OFBiz implementation. This includes full support for HTTPS (SSL) clients. For more information, please see the Jakarta Commons HTTP Client web page

Read more about this book

(For more resources on Apache see here.)

Creating HttpClients and passing XML documents

There are many examples within the OFBiz out-of-the-box code base of web service clients that call real world web services and pass XML documents as part of the payload. These web services clients use the HttpClient as described in the previous recipe in addition to XML document preparation utilities to build the necessary message content used to communicate with external web services.

In this section, we discuss how to write your own web service client(s) and exchange XML documents with one or more external-to-OFBiz web services providers.

Getting ready

The first step in writing any web services client is to gather the following facts about how the target web service operates:

  • The URL on the web for the service provider
  • Any connection parameters and/or HTTP/HTTPS request message header settings that must be passed as required by the service provider
  • The HTTP/HTTPS connection verb (get, post, or other)

To write a web service client that passes one or more XML documents, import at least the following into your Java program:

// Use these to build an XML document
import org.ofbiz.base.util.UtilXml;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.xml.sax.SAXException;

// Use these to send/receive web services client services:
import org.ofbiz.base.util.HttpClient;
import org.ofbiz.base.util.HttpClientException;

How to do it...

To create an HttpClient and pass XML documents, follow these steps:

  1. Create a connection string that includes the URL of the target web service and the type of request:

    String connectString = "http://www.some_web_service_url.com/serviceName";

  2. Within your Java program, create an instance of the HttpClient object with the URL/connection string passed to the constructor as shown here:

    HttpClient http = new HttpClient(connectString);

  3. Create the XML document as prescribed by the target web service. For example, the following code snippet was taken from the UpsServices.java program where an XML document is sent to the target web service:

    Document rateRequestDoc = UtilXml.makeEmptyXmlDocument("RatingServiceSelectionRequest");
    Element rateRequestElement = rateRequestDoc.getDocumentElement();
    rateRequestElement.setAttribute("xml:lang", "en-US");

    // XML request header
    Element requestElement = UtilXml.addChildElement(rateRequestElement, "Request", rateRequestDoc);
    // Code removed...

    // Example, setting up required and optional XML document elements: the pickup type
    Element pickupElement = UtilXml.addChildElement(rateRequestElement, "PickupType", rateRequestDoc);
    // Code removed...

    // Example setting more elements, this time: package info
    String maxWeightStr = UtilProperties.getPropertyValue(serviceConfigProps,
    "shipment.ups.max.estimate.weight", "99");
    BigDecimal maxWeight = new BigDecimal("99");
    // Code removed...

    // Use OFBiz UtilXml utility to create the XML document
    try {
    rateRequestString = UtilXml.writeXmlDocument(rateRequestDoc);
    catch (IOException e) {
    String ioeErrMsg = "Error writing RatingServiceSelectionRequest XML Document"
    + " to a String: " + e.toString();
    Debug.logError(e, ioeErrMsg, module);
    return ServiceUtil.returnFailure(ioeErrMsg);
    // More code removed...

    // Call to the method that eventually calls the UPS web service
    try {
    rateResponseString = sendUpsRequest("Rate", xmlString.toString());
    catch (UpsConnectException e) {
    // Process errors here

  4. Invoke the HttpClient object to call the target web service and pass the XML document within the request message. For example, using the UpsServices.java program from step 3, the call to the HttpClient object looks something like the following:

    public static String sendUpsRequest(String upsService, String xmlString)
    throws UpsConnectException {
    // Code removed...
    HttpClient http = new HttpClient(conStr);

    // You may set a timeout in milliseconds
    http.setTimeout(timeout * 1000);
    String response = null;
    try {
    response = http.post(xmlString);
    catch (HttpClientException e) {
    // Process errors here
    // Handle the return response as necessary here

  5. Process the response from the web service call inline.
  6. There is no need to release or close the connection as OFBiz manages the handoff of network connections transparent to the developer.

How it works...

The HttpClient utility may be used to send and receive XML documents as directed by web service providers. When using the HttpClient, web service client requests are made inline with code logic. Once established, communications between the HttpClient and the target web service are streamed directly across the HTTP/HTTPS connection, bypassing OFBiz.

Creating XML-RPC web service clients

XML-RPC-based web services expect service requests in the "XML-RPC" specification format. If you need to access a web service as a client using XML-RPC, then this section is for you. OFBiz provides a utility based in the Apache XML-RPC project that exposes everything necessary to easily write Java-based XML-RPC clients.

Getting ready

Gather the following information about how the target web service operates:

  • Determine the URL of the web service provider
  • Determine the URL of the web service provider
  • Determine any connection parameters

Don't forget to import the following:

import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
import org.apache.xmlrpc.XmlRpcException;
import java.net.URL

How to do it...

To create XML-RPC web service clients, follow these steps:

  1. Create an instance of the XmlRpcClient object as shown here:

    XmlRpcClient client = new XmlRpcClient();

  2. Create an instance of the XmlRpcClient configuration object:

    XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();

  3. Set the XmlRpcClient configuration with the target URL and other parameters as dictated by the web service provider. Wrap the call to the URL in a try/catch block as shown:

    try {
    config.setServerURL(new URL(
    catch (MalformedURLException me) {
    // Add error processing here

  4. Set configuration parameters as shown here. For example, if the target web service requires basic HTML form authentication, set the config object as shown:


  5. Associate the config object with the XmlRpcClient object:


  6. Marshal any parameters that are to be sent to the web service:

    Object[] params = new Object[]{10, "message from xml-rpc client"};

  7. Call the web service by invoking the execute method on the client object. Don't forget to specify the remote procedure, function, or Java method to call. Wrap the call in a try/catch block:

    try {
    Integer result = (Integer) client.execute("testSvc", params);
    catch(XmlRpcException xe) {
    // Add error processing here

  8. Process results.

How it works...

The XML-RPC standard is a remote procedure calling mechanism that may use HTTP/HTTPS as the network transport. (Note: XML-RPC may also run over RMI). XML-RPC web service consumers specify a procedure (or Java method) name and requesting parameters in an XML request document, and the web service provider returns, as payload within the HTTP/HTTPS response message, an XML document with either a service response or error message.

XML-RPC procedure parameters may be (in the vocabulary of the XML-RPC specification) scalars, numbers, strings, dates as well as complex records (or "struct(s)"), and arrays structures. Practically speaking, the Apache XML-RPC implementation supports all primitive Java types including long, byte, short, double as well as calendar objects, timezone setting, and milliseconds.

The response format has a content-type of text/xml. The body of the response contains a single XML structure containing a methodResponse element , a single params element that contains a param element.

See also

For more details, visit the XML-RPC Specification page.

Read more about this book

(For more resources on Apache see here.)

Becoming an XML-RPC web service provider

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.

Getting ready

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"

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 XMLRPC 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"
<event type="xmlrpc"/>
<response name="error" type="none"/>
<response name="success" type="none"/>

Finally, the target Service called through the XML-RPC execute method must exist and must have, in its Service definition, the export fl ag 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"
<description>Test service</description>
<attribute name="defaultValue" type="Double" mode="IN"
<attribute name="message" type="String" mode="IN" optional="true"/>
<attribute name="resp" type="String" mode="OUT"/>

How to do it...

To enable XML-RPC service provider, follow these steps:

  1. 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;

  2. Rebuild the Component containing the new Service.
  3. Restart OFBiz.
  4. Test with an XML-RPC client.

How it works...

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.

See also

Please see the Apache XML-RPC Server website.

OFBiz SOAP messaging clients

Simple Object Access Protocol (SOAP) is a protocol for exchanging structured information in a decentralized, distributed environment. It is XML-based and consists of three parts:

  1. An envelope that defi nes a framework for describing what is in a message and how to process the message
  2. A set of encoding rules for expressing instances of application-defi ned data types
  3. A convention for representing remote procedure calls and responses

To illustrate just how easy it is to use OFBiz to create an unlimited number of SOAP-based web service clients, we shall discuss writing an SOAP-based client to request service from a real world web service: the U.S. National Weather Service's National Digital Forecast Database (NDFD). This web service provides a number of useful weather-related products. To keep our example simple, we shall request service from the NWS operation that provides the latitude and longitude for a given (valid) ZIP code. (Note: this web service only supports ZIP codes for the Continental United States, Alaska, Hawaii, and Puerto Rico).

For more information about the NWS web service, please see the National Weather Service web site

To view the WSDL for all the operations supported by this web service, point your web browser to the ndfdXML page. To see the WSDL for just the zip code operation, select the LatLonListZipCode link.

Getting ready

Verify that the web service is up and running by viewing the WSDL in your browser. While technically not part of the creation of an SOAP web service client, to illustrate many of the points of this article we shall describe a simple HTML form that allows us to enter in ZIP codes from a browser instead of hardcoding values in our SOAP client-code. This form shall be part of the myWebapp main web page. In this way, we may also return results in real time to the same web page as contains the form.

In addition to the HTML form, we shall build an OFBiz Service that takes the web page form, creates the appropriate SOAP message envelope, and calls the NWS web service.

For all this to work, we will also need to create a request-map in the myComponent Component's myWebapp webapp controller.xml file that maps the form's URI request location to our OFBiz Service. To get started, the steps are as follows:

  1. Create an HTML form to allow for dynamic and repeated entry of a ZIP code value. Shown here is a simple form created on the myWebapp (within myComponent). When the run test button is clicked, this form will call an OFBiz Service. This can be seen in the following figure:

  2. The (abbreviated) HTML form looks something like this:

    <form name="soapClient" action="<@ofbizUrl>soapClientService</@ofbizUrl>" method=post>

    <#-- HTML removed to improve readability -->

    <label for="01">Zip Code:</label>
    <input type="text" id="01" name="param1" value="" size="7"/>
    <input id="smt" style="display: inline" type="submit"
    class="smallSubmit" value="run test"/>

  3. Add a request mapping in the controller.xml file for the myWebapp webapp:

    <!-- ======= Testing Soap Client ===== -->
    <request-map uri="soapClientService">
    <security https="false" auth="false"/>
    <event type="service" invoke="soapClientService"/>
    <response name="success" type="view" value="main"/>
    <response name="error" type="view" value="main"/>

  4. Add a Service model definition in an existing Service defi nition fi le for the OFBiz Service that will accept web page form parameters and send them to the NWS service:

    <service name="soapClientService" engine="java"
    <description>Example SOAP client web service</description>
    <attribute name="endPoint" type="String" mode="IN" optional="true"/>
    <attribute name="namespace" type="String" mode="IN" optional="true"/>
    <attribute name="serviceName" type="String" mode="IN" optional="true"/>
    <attribute name="param1" type="String" mode="IN" optional="true"/>
    <attribute name="result" type="String" mode="OUT" optional="true"/>

How to do it...

In this section, we look at the specifics of creating an SOAP client to call the U.S. National Weather Service web service and get the latitude and longitude given a ZIP code as passed from an HTML form:

  1. Import the following JAR files:

    // All the magic is in the following Axis client classes
    // They do all the hard work of creating SOAP wrappers
    // and dealing with the XML
    import org.apache.axis.client.Call;
    import org.apache.axis.client.Service;

    // We also need these JAR files
    import javax.xml.namespace.QName;
    import java.net.MalformedURLException;
    import java.net.URL;
    import java.util.ArrayList;
    import java.util.List;
    import java.util.Map;

  2. Code the client request based on the WSDL. Note that we have already studied the WSDL and know what the remote service is looking for. The following method, called the soapClientService OFBiz Service, is all that is needed to call the NWS web service and return an XML document containing our Service response:

    public static Map<String, Object> soapClientService(DispatchContext dctx, Map context) {
    Map results = FastMap.newInstance();
    results.put("result", "success");
    // Get everything we need out of the context (the HTML Form)
    String endPoint = (String) context.get("endPoint");
    URL endpoint = null;
    // Define the web services end point as a URL
    try {
    endpoint = new URL(endPoint);
    catch (MalformedURLException e) {
    Debug.log("Location not a valid URL" +e);
    Service service = null;
    Call call = null;
    try {
    // Instantiate a new Axis Service object
    service = new Service();
    // And create a call object from the Service
    call = (Call) service.createCall();
    String nameSpace = null;
    // Just in case, validate the FORM variables
    if(UtilValidate.isNotEmpty((String) context.get("namespace"))) {
    nameSpace = (String) context.get("namespace");
    String serviceName = null;
    if(UtilValidate.isNotEmpty((String) context.get("serviceName"))) {
    serviceName = (String) context.get("serviceName");
    // This is how we tell NWS which procedure to invoke
    call.setOperationName(new QName(nameSpace,serviceName));
    // Since this is an artificial program and we know
    // that there is only a single input parameter for this
    // service that is the zip code, we are just going
    // to force it. Making this Service more generic is left
    // as an exercise for the reader.
    String zipcode = (String) context.get("param1");
    // This is where we make the call and let OFBiz and Axis
    // do all the heavy lifting
    Object ret = (String) call.invoke(new Object[] {zipcode});
    // And, hopefully, we return in line with a useful result
    results.put("result", ret.toString());
    catch (Exception e) {
    Debug.log("Exception when running our SOAP client test: "+e);
    results.put("result", "error: ");
    // Note: we are returning the results as is and not extracting
    // each parameter as sent by the NWS web service.
    return results;

  3. Build the myComponent Component.
  4. Restart OFBiz and navigate to myComponent webapp using: http://localhost:8080/mywebapp/control/main

How it works...

Like other web service clients, OFBiz SOAP-based clients fi rst request access to a remote web service and then, when access is granted, consume the Service directly from the service provider inline with the programming logic in which they are embedded. Using the OFBiz SOAP integration greatly simplifi es the business of writing SOAP web service client code.

In this example, results are returned directly to the calling web page as shown here:

There's more...

You may use the WebTools Run Service service utility to invoke the NWS service by making a few simple changes to the Service definition for the testRemoteSoap Service that is part of OFBiz out-of-the-box. The testRemoteSoap Service definition is found in: ~framework/common/servicedef/services_test.xml

The following is the code:

<!-- the location = endpoint -->
<!-- invoke parameter is the name of the service to invoke for example LatLonListZipCode -->
<service name="testRemoteSoap" engine="soap" export="true"
<description>A service to invoke the NWS web service</description>
<attribute name="ZipCode" type="String" mode="IN"/>
<attribute name="invoke" type="String" mode="IN" />
<attribute name="result" type="String" mode="OUT"/>

Note: the out-of-the-box OFBiz Service defi nition for the testRemoteSoap calls a web service that is no longer operational. It will not work as is.

After changing the testRemoteSoap Service defi nition, you may invoke the Service without creating a web page or HTML form using the WebTools Run Service utility as shown here:

Submitting the Run Service form will bring up a form that will allow entry of the required ZIP code input for the NWS web service as shown here:

Hitting the Submit button will run the testRemoteSoap OFBiz Service that, in turn, calls the NWS web service LatLonListZipCode procedure with the ZIP code as entered on the Run Service form as part of the service request. Web service return values or an error code are displayed on the Schedule Job web page as shown here:


In the above article we have covered:

  • Requesting web services using URL parameters
  • Requesting web services using an HttpClient
  • Creating HttpClient and passing XML documents
  • Creating XML-RPC web service clients
  • Becoming an XML-RPC web service provider
  • Building SOAP messaging clients

Further resources on this subject:

You've been reading an excerpt of:

Apache OfBiz Cookbook

Explore Title