CustomBinder interface for JAX-RPC applications

WebSphere Application Server defines a CustomBinder interface that we can implement for Java API for XML-based Remote Call Procedure (JAX-RPC) applications to provide concrete custom data binders for a specific XML schema type.

The CustomBinder interface has three properties, in addition to deserialize and serialize methods. These properties are QName for the XML schema type, the QName scope, and the Java type that the schema type maps to. The properties are accessible through the corresponding getter methods.

getQName

The getQName method returns the QName of the target XML schema type. Custom data binders only work with the root level schema type.

For anonymous types, the getQName method returns the QName of the containing element.

For named types, the getQName method returns the QName of the complexType or the simpleType.

getQNameScope

The getQNameScope method returns the binder qnameScope property that indicates whether the schema type is a named type or an anonymous type. The qnameScope property value can be complexType for an <xsd:complexType>, simpleType for an <xsd:simpleType> or element for an <xsd:element> that is defined with an anonymous type.

In the following schema, data1 is an element that is defined with an anonymous type. The element, data2, is defined using the named type, data2Type.

<xsd:element name="data1">
	<xsd:complexType>
		...
	</xsd:complexType>
</xsd:element>

<xsd:element name= "data2" type="data2Type"/>
<xsd:complexType name="data2Type">
	...
</xsd:complexType>

The anonymous type, data1, has a qNameScope of element and a qName of data1. The type, data2Type, has a qNameScope of complexType and a qName of data2Type.

The element, data2, is not represented in the custom data binder. The custom data binder only processes types and not elements.

getJavaName

The getJavaName method returns the fully-qualified class name for the Java type that is mapped to the named or anonymous type. The class can be an interface or a concrete class. The object returned from the deserialize method has a type that is compatible with the Java type that is returned by the getJavaName method.

serialize

The serialize method returns the SOAPElement that the custom data binder builds from the Java object. The Java object is passed from the run time system and is expected to match what is returned from the getJavaName method. The SOAPElement parameter does not have child elements, but it does have a valid QName. This parameter is a reference for the binder to create the final SOAPElement.

In most cases, the binder implementation appends the child elements to the root SOAPElement. The run time system guarantees that the SOAPElement QName is correct. Therefore, the custom data binder for named types keeps the QName of the root element because the binder does not know the enclosing element. The binder implementation for an anonymous type should always include the QName in the returned SOAPElement that matches the defined schema type. WebSphere Application Server does not have concrete methods in the CustomBindingContext parameter.

deserialize

The deserialize method returns a Java object that the custom data binder builds from the passed root SOAPElement. The object type of the returned Java object must match what is returned from the getJavaName method. Unlike the parameter serialize method, the passed SOAPElement contains the original XML data with the necessary namespace declarations.

The following is an example of an implementation of the SDO DataGraph binder, where the convertToSDO and convertToSAAJ utility methods convert between SOAPElement and an SDO object.

package test.sdo.binder;

import javax.xml.namespace.QName;
import javax.xml.soap.SOAPElement;

import com.ibm.wsspi.webservices.binding.CustomBinder;
import com.ibm.wsspi.webservices.binding.CustomBindingContext;

public class DataGraphBinder implements CustomBinder {
	public QName getQName() {
		return new QName("commonj.sdo", "DataGraphyType");
}
public String getJavaName() {
	return CustomBinder.QNAME_SCOPE_COMPLEXTYPE;
}
public String getJavaName() {
	return commonj.sdo.DataGraph.class.getName();
}
public javax.xml.soap.SOAPElement serialize(
		Object bean,
		SOAPElement rootNode,
		CustomBindingContext context)
		throws javax,xml.soap.SOAPException {
	// convertToSAAJ is a utility method to convert
	// the SDO DataGraph to the SOAPElement
	return convertToSAAJ(bean, rootNode);

public Object deserialize(
		SOAPElement source,
		CustomBindingContext context)
		throws javax.xml.soap.SOAPException {
		// convertToSDO is a utility method to convert
		// the SOAPElement to the SDO DataGraph
		return convertToSDO(source);
	}
}

To learn more about custom data binders, see the custom data binders for JAX-RPC applications information. To learn how to plug our custom data binders into the WSDL2Java command-line tool for development, see the custom binding providers for JAX-RPC applications information.

Related:

Custom data binders for JAX-RPC applications

Custom binding providers 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