Implement extensions to JAX-RPC web services clients

WebSphere Application Server provides extensions to web services clients using JAX-RPC.

We can customize web services using the following extensions to the JAX-RPC client programming model.

Tasks

• Set the REQUEST_SOAP_HEADERS and RESPONSE_SOAP_HEADERS properties in a JAX-RPC client Stub to enable a web services client to send or retrieve implicit SOAP headers.

  An implicit SOAP header is a SOAP header that is not explicitly defined in the WSDL file. An implicit SOAP header file fits one of the following descriptions:

  • A message part that is declared as a SOAP header in the binding in the WSDL file, but the message definition is not referenced by a portType within a WSDL file.

  • An element that is not contained in the WSDL file.

  Handlers and service endpoints can manipulate implicit or explicit SOAP headers using the SOAP with Attachments API for Java (SAAJ) data model.

  To learn how to modify the client code to send or retrieve transport headers, see the information on sending implicit SOAP headers with JAX-RPC or receiving implicit SOAP headers with JAX-RPC.

• Set the REQUEST_TRANSPORT_PROPERTIES and RESPONSE_TRANSPORT_PROPERTIES properties to enable a web services client to send or retrieve transport headers.

  Set the properties on the Stub or Call object.

  By modifying the client code to send or retrieve transport headers, we can send or receive specific information within the transport headers of outgoing requests or incoming responses from the server. For requests or responses that use the HTTP transport, the information is sent or retrieved in an HTTP header. Similarly, for a request or response that uses the JMS transport, the information is sent or retrieved in a JMS message property.

  To learn how to modify the client code to send or retrieve transport headers, see the information on sending transport headers with JAX-RPC or retrieving transport headers with JAX-RPC.

  To learn how to enable a Web services client to send or retrieve transport headers, see the transport header properties best practices information.

• Implement support for javax.xml.rpc.ServiceFactory.loadService() methods.

  The loadService methods create an instance of the generated service implementation class in an implementation-specific manner. The loadService methods are new for JAX-RPC 1.1 and include three signatures:

  • public.javax.xml.rpc.Service loadService (Class serviceInterface)

    As documented in the JAX-RPC specification, this method returns the generated service implementation for the service interface. See the web services specifications and API documentation to review the JAX-RPC specification.

  • public.javax.xml.rpc.Service loadService (URL wsdlDocumentLocation, Class serviceInterface, Properties properties)

    This method behaves like the loadService (Class serviceInterface) because the following parameters are ignored:

    • wsdlDocumentLocation
    • properties

  • public.javax.xml.rpc.Service loadService (URL wsdlDocumentLocation, QName serviceName, Properties properties)

    This method returns the generated service implementation for the specified service using optional namespace-to-package mapping information.

    • wsdlDocumentLocation - ignored
    • serviceName - QName (namespace, localpart) of the service
    • properties - If this parameter is non-null, it contains namespace-to-package mapping entries. Each Property entry key is a String corresponding to the namespace. Each Property entry value is a String corresponding to the Java package name.

      If the properties argument contains an entry with a key (namespace) that matches the namespace portion of the QName serviceName argument, the entry value (javaPackage) is used as the package name when trying to locate the service implementation.

  For more information on these methods, see the JAX-RPC specification.

• Implement the CustomBinder interface to provide concrete custom data binders for a specific XML schema type (JAX-RPC applications only).

  Custom data binders are used to map XML schema types with Java objects. Custom data binders provide bindings for XML schema types that are not supported by the current Java API for XML-based Remote Call Procedure (JAX-RPC) specification. WAS provides an extension to the Web Services for Java EE programming model called the CustomBinder interface that implements these custom bindings for a specific XML schema type. The CustomBinder interface has three properties, in addition to deserialize and serialize methods:

  • QName for the XML schema type
  • QName scope
  • Java type

  The custom data binder defines serialize and deserialize methods to convert between a Java object and a SOAPElement interface. A custom data binder is added to the runtime system and interacts with the web services runtime using a SOAPElement. They are added to the runtime using custom binding providers. Read about the custom data binders and the custom binding provider to learn more. See the CustomBinder interface documentation to learn more about how we can implement this interface to provide concrete custom data binders for a specific XML schema type.

Subtopics

• Custom data binders for JAX-RPC applications
  A custom data binder is used to map XML schema types with Java objects. Custom data binders provide bindings for XML schema types that are not supported by the current Java API for XML-based Remote Call Procedure (JAX-RPC) specification.

• 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.

• CustomBinder interface for JAX-RPC applications
  WAS 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.

• Usage patterns for deploying custom data binders for JAX-RPC applications
  Custom data binders are used to map XML schema types with Java objects. Custom data binders provide bindings for XML schema types that are not supported by the current Java API for XML-based Remote Call Procedure (JAX-RPC) specification. WAS provides an extension to the Web Services for Java EE programming model called the CustomBinder interface that implements these custom bindings for a specific XML schema type. The custom binding provider is the package for the custom data binders that is imported into the runtime.

• Sending implicit SOAP headers with JAX-RPC
  We can enable an existing JAX-RPC Web services client to send values in implicit SOAP headers. By modifying the client code to send implicit SOAP headers, we can send specific information within an outgoing web service request.

• Receiving implicit SOAP headers with JAX-RPC
  We can enable an existing JAX-RPC Web services client to receive values from implicit SOAP headers. By modifying the client code to receive implicit SOAP headers, we can receive specific information within an incoming web service response.

• Sending transport headers with JAX-RPC
  We can enable an existing JAX-RPC Web services client to send application-defined information along with your Web services requests using transport headers.

• Retrieving transport headers with JAX-RPC
  We can enable an existing JAX-RPC Web services client to retrieve values from transport headers. For a request that uses HTTP, the transport headers are retrieved from HTTP headers found in the HTTP response message. For a request that uses Java Message Service (JMS), the transport headers are retrieved from the JMS message properties found on the JMS response message.

Related:

SOAP with Attachments API for Java interface

Implement JAX-RPC web services clients

Transport header properties best practices

Additional Application Programming Interfaces (APIs)

Web services specifications and APIs