Custom binding providers for JAX-RPC applications

Custom binding providers for JAX-RPC applications

A custom binding provider is the packaging of custom data binder classes with a declarative metadata file. The main purpose of a custom binding provider is to aggregate related custom data binders to support particular user scenarios. The custom binding provider is used to plug the custom data binders into the emitter tools and the run time system so that the emitter tools can generate the appropriate artifacts and 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. You 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 used to plug in a set of custom data binders to either emitter tools or the run time system.

See the custom data binders information and the information on the CustomBinder interface to learn more about custom data binders and the CustomBinder API included in WebSphere Application Server to define the custom data binders. After we have defined the custom data binders, we are ready to deploy the custom binder package. To learn how to deploy this package, see the information on usage patterns for deploying custom data binders for JAX-RPC applications.

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 the /META-INF/services/directory. Once 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 containing 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 the information for CustomBinder interface for JAX-RPC applications. 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 our 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 Web Services Description Language (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 we 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 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:

Custom data binders for JAX-RPC applications
SOAP with Attachments API for Java interface
CustomBinder interface for JAX-RPC applications
Usage patterns for deploying custom data binders for JAX-RPC applications
WSDL2Java command for JAX-RPC applications
Additional Application Programming Interfaces (APIs)
Web services specifications and APIs