Custom binding providers

Custom binding providers

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 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 WebSphere Application Server to define the custom data binders. After you have reviewed these articles you 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 Java archive (JAR) file and located in the /META-INF/services/directory. After 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>
You need to import your 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 WebSphere Application Server 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 you 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 you would 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.
To review the documentation used for APIs and SPIs, see Reference: Generated API documentation. Follow the instructions in this topic that lead you to the API and SPI interfaces.
We can also review the specifications for the standards and APIs used in developing Web services.
Related concepts
Custom data binders SOAP with Attachments API for Java interface Related reference
CustomBinder interface Usage patterns for deploying custom data binders WSDL2Java command for JAX-RPC applications Web services: Resources for learning