Custom binding providers for JAX-RPC applications

 

+

Search Tips   |   Advanced Search

 

A custom binding provider is the packaging of custom data binder classes with a declarative metadata file.

Custom binding providers plug custom data binders into emitter tools and the run time system to generate artifacts. The run time system can augment its existing type mapping system to reflect the applied custom data binders and invoke them.

A custom binding provider works with a specific XML schema type, while applications involve a few related XML schema types. we need a mechanism to aggregate and declare various custom data binders to provide a complete binding solution. The concept of the custom binding provider defines a declarative model that can be used to plug in a set of custom data binders to either emitter tools or the run time system.

We can review information in Custom data binders to learn more about custom data binders and CustomBinder interface, which is the API included in WAS to define the custom data binders. After we have reviewed these articles we are ready to deploy the custom binder package. To learn how to deploy this package, see Usage patterns for deploying custom data binders.

The declarative metadata file, CustomBindingProvider.xml, is an XML file that is packaged with the custom provider classes in a single JAR file and located in...

/META-INF/services

...a provider JAR file is packaged, the binary information and the metadata file located in the JAR file can be used by the WSDL2Java command-line tool and the run time system.

The following example is the XML schema for the CustomBindingProvider.xml file.

The top level type is the providerType that contains a list of mapping elements.

Each mapping element defines the associated custom data binder and properties, including xmlQName, javaName and qnameScope. We can read more about these properties in CustomBinder interface.

The providerType also has an attribute called scope that has a value of server, application or module.

The scope attribute is used by the server deployment to resolve the conflict and to realize a custom binding hierarchy.

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema 
    targetNamespace=
       "http://www.ibm.com/webservices/customdatabinding/2004/06" 
    
    xmlns:customdatabinding=
        "http://www.ibm.com/webservices/customdatabinding/2004/06"
    
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified" attributeFormDefault="qualified">
  
   <xsd:element name="provider" type="customdatabinding:providerType"/>
   
   <xsd:complexType name="providerType">
   <xsd:sequence>
     <xsd:element name="description" type="xsd:string" minOccurs="0"/>
     <xsd:element name="mapping" minOccurs="0" maxOccurs="unbounded">
      <xsd:complexType>
        <xsd:sequence>
          <xsd:element name="description" type="xsd:string" minOccurs="0"/>
          <xsd:element name="xmlQName" type="xsd:QName"/>
          <xsd:element name="javaName" type="xsd:string"/>
          <xsd:element name="qnameScope" 
                       type="customdatabinding:qnameScopeType"/>
          <xsd:element name="binder" type="xsd:string"/>
        </xsd:sequence>
       /xsd:complexType>
      </xsd:element>
       <xsd:attribute name="scope" 
             type="customdatabinding:ProviderScopeType" default="module"/>
       </xsd:sequence>
   </xsd:complexType

  <xsd:simpleType name="qnameScopeType">
      <xsd:restriction base="xsd:string">
         <xsd:enumeration value="simpleType"/>
         <xsd:enumeration value="complexType"/>
         <xsd:enumeration value="element"/>
      </xsd:restriction>
  </xsd:simpleType>

  <xsd:simpleType name="ProviderScopeType">
     <xsd:restriction base="xsd:string">
         <xsd:enumeration value="server"/>
         <xsd:enumeration value="application"/>
         <xsd:enumeration value="module"/>
     </xsd:restriction>
  </xsd:simpleType>  
</xsd:schema>

The following is an example of the CustomBindingProvider.xml file for the SDO DataGraph schema that was introduced in CustomBinder interface. The example displays the mapping between a schema type, DataGraphType, and a Java type, commonj.sdo.DataGraph. The binder that represents this mapping is called test.sdo.SDODataGraphBinder.

<cdb:provider
  
    xmlns:cdb="http://www.ibm.com/webservices/customdatabinding/2004/06"
   
    xmlns:sdo="commonj.sdo">
   <cdb:mapping>
       <cdb:xmlQName>sdo:DataGraphType</cdb:xmlQName>
       <cdb:javaName>commonj.sdo.DataGraph</cdb:javaName>
       <cdb:qnameScope>complexType</cdb:qnameScope>
       <cdb:binder>test.sdo.SDODataGraphBinder</cdb:binder>
   </cdb:mapping>   
</cdb:provider>

we need to import the custom data binders into the WSDL2Java command-line tool for development purposes. The custom data binders affect how the development artifacts, including the Service Endpoint Interface and the JSR 109 mapping data, are generated from the WSDL file.

The WSDL2Java command-line tool ships with WAS and uses the custom binder Java archive file, or custom binder package, to generate these the development artifacts.

The following example is a WSDL file that references the SDO DataGraph schema that is introduced in the CustomBinder interface topic.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="http://sdo.test" 
   
    xmlns:impl="http://sdo.test" 
   
    xmlns:intf="http://sdo.test" 
   
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
   
    xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/" 
   
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   
    xmlns:sdo="commonj.sdo">

 <wsdl:types>
  <schema elementFormDefault="qualified" targetNamespace="http://sdo.test" 
       
    xmlns="http://www.w3.org/2001/XMLSchema" 
    xmlns:sdo="commonj.sdo">
   <import namespace="commonj.sdo" schemaLocation="sdo.xsd"/>
  </schema>
 </wsdl:types>

 <wsdl:message name="echoResponse">
  <wsdl:part element="sdo:datagraph" name="return"/>
 </wsdl:message>

 <wsdl:message name="echoRequest">
   <wsdl:part element="sdo:datagraph" name="parameter"/>
 </wsdl:message>

 <wsdl:portType name="EchoService">
   <wsdl:operation name="echo">
     <wsdl:input message="impl:echoRequest" name="echoRequest"/>
     <wsdl:output message="impl:echoResponse" name="echoResponse"/>
    </wsdl:operation>
 </wsdl:portType>

 <wsdl:binding name="EchoServiceSoapBinding" type="impl:EchoService">
   <wsdlsoap:binding style="document" 
                     transport="http://schemas.xmlsoap.org/soap/http"/>
     <wsdl:operation name="echo">
        <wsdlsoap:operation soapAction=""/>
        <wsdl:input name="echoRequest">
         <wsdlsoap:body use="literal"/>
        </wsdl:input>

       <wsdl:output name="echoResponse">
          <wsdlsoap:body use="literal"/>
       </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>

  <wsdl:service name="EchoServiceService">
     <wsdl:port binding="impl:EchoServiceSoapBinding" name="EchoService">
       <wsdlsoap:address location="http://<uri>"/>
    </wsdl:port>
  </wsdl:service>

</wsdl:definitions>

If we run the WSDL2Java command without the custom data binding package, the following Service Endpoint Interface is generated with a parameter type, as dictated by the JAX-RPC specification:

public interface EchoService extends java.rmi.Remote {
    public javax.xml.soap.SOAPElement 
      echo(javax.xml.soap.SOAPElement parameter)
        throws java.rmi.RemoteException;
}

When you run the WSDL2Java command with the custom data binding package, the custom data binders are used to generate the parameter types. To apply the custom data binders, use the -classpath option on the WSDL2Java tool. The tool searches its classpath to locate all the files with the same file path of...

/META-INF/services/CustomBindingProvider.xml

The following is an example how we can use the command to generate a Service Endpoint Interface with the parameter type of commonj.sdo.Datagraph:

WSDL2Java -role develop-server -container web classpath sdobinder.jar echo.wsdl

The Service Endpoint Interface that is generated looks like the following:

 public interface EchoService extends java.rmi.Remote 
{
    public commonj.sdo.DataGraph 
        echo(commonj.sdo.DataGraph parameter)
        throws java.rmi.RemoteException;
}

The custom binder packaged JAR file has to be made available at runtime to make sure the Web service client is invoked, regardless if it is a stub-based client or a Dynamic Invocation Interface (DII) client. The same applies to the service.

---

Related concepts

Custom data binders for JAX-RPC applications
SOAP with Attachments API for Java interface

 

Related

CustomBinder interface for JAX-RPC applications
Usage patterns for deploying custom data binders for JAX-RPC applications
WSDL2Java command for JAX-RPC applications
Additional APIs
Web services specifications and APIs