Web Service Descriptor Language (WSDL) is an XML-based grammar used to define the interface provided by a web service. Web service providers publish—on the Web—one or more WSDL(s) describing how an interested service consumer may connect and consume a Service.
The work of creating SOAP web service's WSDLs by hand can be tedious and error-prone. Fortunately, OFBiz makes the job of publishing WSDLs easy by automatically creating them from a Service's definition.
For this section, we shall assume that an OFBiz Service already exists. In fact, we shall use as an illustration the testSvc Service that comes with OFBiz out-of-the-box.
To publish a SOAP WSDL for this Service, or any other OFBiz Service, follow these simple steps:
- To indicate that a URL should be handled as a SOAP web service request and be forwarded to the SOAP event handler, add the following line to the
controller.xmlfile for the OFBiz webapp where the web service will be exposed:<handler name="soap" type="request" class="org.ofbiz.webapp.event.SOAPEventHandler"/>
- Add one or more
controller.xml request-mapdefinitions for the location of the SOAP-based web service(s). For example, the following is taken from the WebTools Componentcontroller.xmlfile. Note response types are set tonone. This indicates that the Service will handle the caller's response message by streaming directly to the HTTP/HTTPS response variable:<request-map uri="SOAPService"> <event type="soap"/> <response name="error" type="none"/> <response name="success" type="none"/> </request-map>
- Make sure the Service's definition has the
exportattribute set totrue. - Ensure that the Service's definition has all the settings necessary to create a valid WSDL. For example, at a minimum, define the engine as
soapand providelocationandinvokeattribute values as shown here:<service name="testSoap" engine= "soap" export = "true" location= "http://localhost:8080/webtools/control/SOAPService?WSDL" invoke="testSvc"> <description>A SOAP Service with WSDL found here </description> <attribute name="message" type="String" mode="IN" optional="true" /> <attribute name="response" type="String" mode="OUT" /> </service>
- Create a WSDL as follows: (You can see this in your browser by going to the
locationattribute value specified in the Service definition):<wsdl:definitions targetNamespace= "http://ofbiz.apache.org/service/"> <wsdl:message name="testSoapResponse"> <wsdl:part name="resp" type="xsd:string"/> </wsdl:message> <wsdl:message name="testSoapRequest"> <wsdl:part name="message" type="xsd:string"/> </wsdl:message> <wsdl:portType name="testSoapPortType"> <wsdl:operation name="testSoap"> <wsdl:input message="tns:testSoapRequest"/> <wsdl:output message="tns:testSoapResponse"/> </wsdl:operation> </wsdl:portType> <wsdl:binding name="testSoapSoapBinding" type="tns:testSoapPortType"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="testSoap"> <soap:operation soapAction= "http://localhost:8080/webtools/control/SOAPService" style="rpc"/> <wsdl:input> <soap:body encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/" namespace="http://ofbiz.apache.org/service/" use="literal"/> </wsdl:input> <wsdl:output> <soap:body encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/" namespace="http://ofbiz.apache.org/service/" use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name="testSoap"> <wsdl:port binding="tns:testSoapSoapBinding" name="testSoapPort"> <soap:address location= "http://localhost:8080/webtools/control/SOAPService"/> </wsdl:port> </wsdl:service> </wsdl:definitions>
- If this is a new Service or if you have changed some Service definition settings, restart OFBiz to make the changes effective. That is all you need to do.
The OFBiz ModelService object provides a handy set of methods that can take an instance of a Service's definition and dynamically construct a WSDL based on configured attributes. For example, the following table maps WSDL XML specification requirements to OFBiz Service definition elements and attributes:
|
Element |
Usage |
OFBiz service definition attribute |
|---|---|---|
|
|
The root element. Declares the name of the web service. |
|
|
|
Declares the data types supported and transmitted by the web service. |
Taken from the |
|
|
Describes one or more "messages". Messages have a name and may have "parts" that may refer to parameters and/or return values. Each message declares a one-way request or one-way response operation. |
|
|
|
|
|
|
|
The network transport is declared through the binding. SOAP-specific details are declared here. |
Default to SOAP because the |
|
|
The URL (Web address) for this web service. |
|
To create a WSDL from a Service's definition, OFBiz simply gets the service's model from the service dispatch context and passes configuration settings to a WSDL generation tool (provided by the Apache Axis library).
When a request for an OFBiz resource comes across the wire and the destination is a URL of an OFBiz Service that has been mapped to the OFBiz SOAP event handler, OFBiz first checks to see if the request has a WSDL request parameter affixed to it. If it does, then OFBiz will automatically call the service DispatchContext object's getWSDL method to get the WSDL, based on the Service's definition, and return the WSDL as part of the HTTP/HTTPS response message.