Adding Arguments and Return Types to Inbound Web Service Operations

Add arguments and a return type to an inbound web service to utilize an RPC-style web service; otherwise, for a document-style web service, which passes and returns a W3C XML Document, specify no arguments or return type. The interface with an XML Document argument and return type set is automatically generated for each operation, as illustrated in Adding Arguments and Return Types to Inbound Web Service Operations.

When adding arguments and return types to RPC-style inbound web service operations this is done in the same manner as with process and facade classes as documented in Working with the Cram Model in Rational Software Architect.

Note: Only operations which do not have operation arguments or a return type set will be exposed as a DOWS XML Document service. The interface with an XML Document argument and return type set is automatically generated for each operation, as illustrated in the following Adding Arguments and Return Types to Inbound Web Service Operations:

Figure 1. Sample Generated DOWS XML Document Interface

public interface DOWSXMLDocTestBPO
{
  public org.w3c.dom.Document processDocument
    (org.w3c.dom.Document xmlMessage)
    throws curam.util.exception.AppException,
    curam.util.exception.InformationalException;

  public org.w3c.dom.Document echoDocument
    (org.w3c.dom.Document xmlMessage)
    throws curam.util.exception.AppException,
    curam.util.exception.InformationalException;
}

To specify a schema in the Curam properties tab for the WebService class (where you've set property XML_Document):

Select the XML_Schema property and click the edit (...) button. In the edit window specify the XML schema filename, relative to your EJBServer directory. The schema identified by this filename will be included in the web service WSDL generated at run time by Axis 1.4. This feature provides a way to publish a description of the XML message expected by the service.
Schema files must be stored in the appropriate build structure folder: <SERVER_DIR>/components/custom/webservices/. Each component may have its own set of web services, so in the above path custom should be the name of the component for which the web service is being deployed. For example:

<SERVER_DIR>/components/testComponent/webservices/sampleSchema.xsd
Set the Validate_Request property in the Curam properties tab for the WebService class to 1 - yes. SOAP body request messages will then be validated against the specified XML schema before forwarding the request to the process class. If the message does not conform to the schema the process class will not be invoked, and a fault message will be returned to the client stating that the request does not conform to the schema.

Note: If the declared elements are referenced in the XML schema then any references to these elements should be qualified with the namespace (in the example Figure 2 the references are prefixed with cns). This is required to avoid the name clashes as the XML schema will be included in the web service WSDL.

Figure 2. XML schema

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://ws.curam/FinancialUpdateWS"
  xmlns:cns="http://ws.curam/FinancialUpdateWS"
  elementFormDefault="qualified">
  <xs:element name="root">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="1" maxOccurs="1"
        ref="cns:msgT_financialUpdate"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="msgT_financialUpdate">
    <xs:complexType>
      <xs:sequence>
        <xs:element maxOccurs="unbounded" ref="cns:row"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="row">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="1" maxOccurs="1"
        ref="cns:EXTERNALILIID"/>
        <xs:element minOccurs="1" maxOccurs="1"
        ref="cns:DOCUMENTSTATUSCODE"/>
        <xs:element minOccurs="1" maxOccurs="1"
        ref="cns:OPENAMOUNT"/>
        <xs:element minOccurs="0" maxOccurs="1"
        ref="cns:EXTERNALINVOICEID"/>
        <xs:element minOccurs="0" maxOccurs="1"
        ref="cns:EXTERNALPAYMENTLIST"/>
        <xs:element minOccurs="0" maxOccurs="1"
        ref="cns:LOCKLIST"/>
        <xs:element minOccurs="1" maxOccurs="1"
        ref="cns:TIMESTAMP"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="EXTERNALILIID" type="xs:integer"/>
  <xs:element name="DOCUMENTSTATUSCODE" type="xs:string"/>
  <xs:element name="OPENAMOUNT" type="xs:double"/>
  <xs:element name="EXTERNALINVOICEID" type="xs:integer"/>
  <xs:element name="EXTERNALPAYMENTLIST">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="0" maxOccurs="unbounded"
        ref="cns:EXTERNALPAYMENTID"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="EXTERNALPAYMENTID" type="xs:integer"/>
  <xs:element name="LOCKLIST">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="0" maxOccurs="unbounded"
        ref="cns:LOCKREASON"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="LOCKREASON" type="xs:string"/>
  <xs:element name="TIMESTAMP" type="xs:integer"/>
</xs:schema>

An example of an XML document that conforms to the schema in Figure 2:

Figure 3. XML document

<msgT_financialUpdate
  xmlns="http://ws.curam/FinancialUpdateWS"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://ws.curam/FinancialUpdateWS
  FinancialUpdate.xsd">
 <row>
  <EXTERNALILIID>1</EXTERNALILIID>
  <DOCUMENTSTATUSCODE>C04</DOCUMENTSTATUSCODE>
  <OPENAMOUNT>0</OPENAMOUNT>
  <EXTERNALINVOICEID>000000000000</EXTERNALINVOICEID>
  <EXTERNALPAYMENTLIST>
   <EXTERNALPAYMENTID>233</EXTERNALPAYMENTID>
  </EXTERNALPAYMENTLIST>
  <TIMESTAMP>20080229094755</TIMESTAMP>
 </row>
 <row>
   <EXTERNALILIID>2</EXTERNALILIID>
   <DOCUMENTSTATUSCODE>C05</DOCUMENTSTATUSCODE>
   <OPENAMOUNT>0</OPENAMOUNT>
   <EXTERNALINVOICEID>000000000000</EXTERNALINVOICEID>
   <EXTERNALPAYMENTLIST>
    <EXTERNALPAYMENTID>3455</EXTERNALPAYMENTID>
   </EXTERNALPAYMENTLIST>
   <TIMESTAMP>20080229094744</TIMESTAMP>
 </row>
</msgT_financialUpdate>

Note: A web service cannot be called if it has validation schema enabled and the specified validation schema xsd file imports other xsd files. This is illustrated by the following examples where validation schema " Determination.xsd " imports " businesstypes.xsd ".

Figure 4. Determination.xsd

<?xml version="1.0"?>

<!-- root element, namespace and form definitions -->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
               xmlns:bt="businesstypesURI"
      xmlns:dt="determinationURI"
  elementFormDefault="qualified"
    attributeFormDefault="unqualified"
  targetNamespace="determinationURI">

  <!-- import the businesstypes schema -->
  <xs:import namespace="businesstypesURI"
    schemaLocation="businesstypes.xsd" />

  <...>

</xs:schema>

The schema " businesstypes.xsd ", which is imported in " Determination.xsd " above:

Figure 5. businesstypes.xsd

<?xml version="1.0" encoding="UTF-8"?>
<!-- The contents of this file are fixed, by the SDEJ.
     It could easily be shipped with the SDEJ -->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="curamtypesURI">

  <xs:simpleType name="date">
    <xs:annotation>
      <xs:documentation>Cram builtin type date.
      </xs:documentation>
    </xs:annotation>
    <xs:restriction base="xs:date"/>
  </xs:simpleType>

    <...>

</xs:schema>

When calling a web service having a validation schema which imports another schema as shown in the example above an error " src-resolve: Cannot resolve the name <...> to a type definition component " will be thrown.

There are two workarounds to solve this issue:

Disable schema validation on a web service.

If a web service's schema validation still needs to be specified avoid using schema imports within the schema, and define the contents of the imported schema instead. If we take the example given above, the schema " Determination.xsd " shown below no longer imports " businesstypes.xsd ", but now has its contents inline:

Figure 6. Determination.xsd

<?xml version="1.0"?>

 <!-- root element, namespace and form definitions -->
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:dt="determinationURI"
   elementFormDefault="qualified"
   attributeFormDefault="unqualified"
   targetNamespace="determinationURI">

   <!-- import the businesstypes schema -->
   <!-- BEGIN businesstypes.xsd -->

     <xs:simpleType name="date">
       <xs:annotation>
         <xs:documentation>
           Curam builtin type date.
         </xs:documentation>
       </xs:annotation>
       <xs:restriction base="xs:date"/>
     </xs:simpleType>

     <...>

    <!-- END businesstypes.xsd -->

     <...>

</xs:schema>

Adding Arguments and Return Types to Inbound Web Service Operations illustrates a skeleton implementation. This simple example shows an implementation of class DOWSXMLDocTestBPO that consists of two operations, echoDocument and processDocument, which are exposed as two web services that echo and process the request SOAP body XML message respectively.

Figure 7. Sample DOWS XML Document Implementation Class

package webservice.impl;

import curam.util.exception.AppException;
import curam.util.exception.InformationalException;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.Node;

public class DOWSXMLDocTestBPO extends
    webservice.base.DOWSXMLDocTestBPO {

  /**
   * Sample method for echoing an XML message.
   *
   * @param xmlMessage The request message
   * @return the response message.
   *
   * @throws AppException
   * @throws InformationalException
   */
  public Document echoDocument
    (final Document xmlMessage)
    throws AppException, InformationalException {

    Document responseMessage = null;
    try {
      responseMessage = xmlMessage;
    } catch (Exception ex) {
      .....
    }
    return responseMessage;
  }

  /**
   * Sample method for processing an XML message.
   *
   * @param xmlMessage The request message
   * @return the response message.
   *
   * @throws AppException
   * @throws InformationalException
   */
  public Document processDocument
    (final Document xmlMessage)
    throws AppException, InformationalException {

    Document responseMessage = null;
    try {
      responseMessage =
        doXMLDocumentProcessing(xmlMessage);
    } catch (Exception ex) {
      ....
    }
    return responseMessage;
  }

  /**
   * Do processing of XML and return an XML message.
   * @param bodyXML The message to be processed.
   * @return The processed message.
   */
  private Document doXMLDocumentProcessing
    (final Document bodyXML) {

    final Document doc = bodyXML;

    /** business logic implemented here... **/

    return doc;
  }

}