16-2 Programming Advanced Features of JAX-WS Web Services for Oracle WebLogic Server
■
WS-ReliableMessaging
■
WS-MakeConnection
■
WS-AtomicTransaction
16.2 Usage Modes and Message Formats for Operating at the XML Level
When operating on messages at the XML level using Provider-based endpoints or Dispatch clients, you use one of the usage modes defined in the following table. You
define the usage mode using the javax.xml.ws.ServiceMode annotation, as described in
Section 16.3.4, Specifying the Usage Mode ServiceMode Annotation.
Provider-based endpoints and Dispatch clients can receive and send messages using one of the message formats defined in
Table 16–2 . This table also defines the valid
message format and usage mode combinations based on the configured binding type SOAP or XML over HTTP.
16.3 Developing a Web Service Provider-based Endpoint
A Web service Provider-based endpoint, implemented using the javax.xml.ws.ProviderT interface, enables you to access content directly at the
XML message level—without the JAXB binding.
The following procedure describes the typical steps for programming a JWS file that implements a Web service provider.
Table 16–1 Usage Modes for Operating at the XML Message Level
Usage Mode Description
Message Operates directly with the entire message. For example, if a SOAP binding is used,
then the entire SOAP envelope is accessed. Payload
Operates on the payload of a message only. For example, if a SOAP binding is used, then the SOAP body is accessed.
Table 16–2 Message Formats Supported for Operating at the XML Message Level
Message Format Usage Mode Support for
SOAPHTTP Binding Usage Mode Support for
XMLHTTP Binding javax.xml.transform.Source
Message mode : SOAP envelope
Payload mode : SOAP body
Message mode : XML content as
Source
Payload mode : XML content as
Source javax.activation.DataSource
Not valid in either mode because attachments in SOAPHTTP
binding are sent using SOAPMessage format.
Message mode : DataSource
object Not valid in payload mode
because DataSource is used for sending attachments.
javax.xml.soap.SOAPMessage
Message mode : SOAPMessage
object Not valid in payload mode
because the entire SOAP message is received, not just the payload.
Not valid in either mode because the client can send a non-SOAP
message in XMLHTTP binding.
Operating at the XML Message Level 16-3
16.3.1 Example of a JWS File That Implements a Web Service Provider-based Endpoint
The following sample JWS file shows how to implement a simple Web service provider. The sample is described in detail in the sections that follow.
To review the JWS file within the context of a complete sample, see Creating JAX-WS Web Services for Java EE in the Web Services Samples distributed with Oracle
WebLogic Server.
Table 16–3 Steps to Develop a Web Service Provider-based Endpoint
Step Description
1 Import the JWS annotations
that will be used in your Web service Provider-based JWS
file. The standard JWS annotations for a Web service Provider-based JWS file
include: import javax.xml.ws.Provider;
import javax.xml.ws.WebServiceProvider; import javax.xml.ws.ServiceMode;
Import additional annotations, as required. For a complete list of JWS annotations that are supported, see Web Service Annotation Support in
WebLogic Web Services Reference for Oracle WebLogic Server. 2
Specify one of the message formats supported, defined in
Table 16–2 , when developing
the Provider-based implementation class.
See Section 16.3.2, Specifying the Message Format
.
3 Add the standard required
WebServiceProvider JWS annotation at the class
level to specify that the Java class exposes a Web service
provider. See
Section 16.3.3, Specifying that the JWS File Implements a Web Service Provider WebServiceProvider Annotation.
4 Add the standard
ServiceMode JWS annotation at the class level to
specify whether the Web service provider is accessing
information at the message or message payload level.
Optional See
Section 16.3.4, Specifying the Usage Mode ServiceMode Annotation. The service mode defaults to Service.Mode.Payload.
5 Define the invoke
method. The invoke method is called and provides the message or message
payload as input to the method using the specified message format. See Section 16.3.5, Defining the invoke Method.
Note: To start from WSDL and flag a port as a Web service provider,
see Section 16.3.6, Starting from WSDL
.
Note:
RESTful Web Services can be built using XMLHTTP binding based Provider endpoints. For an example of programming a
Provider-based endpoint within the context of a RESTful Web service, see
Section 17.3, Programming Web Services Using XML Over HTTP
.
16-4 Programming Advanced Features of JAX-WS Web Services for Oracle WebLogic Server
Example 16–1 Example of a JWS File that Implements a Web Service Provider
package examples.webservices.jaxws; import org.w3c.dom.Node;
import javax.xml.transform.Source; import javax.xml.transform.TransformerFactory;
import javax.xml.transform.Transformer; import javax.xml.transform.dom.DOMResult;
import javax.xml.transform.stream.StreamSource; import javax.xml.ws.Provider;
import javax.xml.ws.ServiceMode; import javax.xml.ws.WebServiceProvider;
import javax.xml.ws.Service; import java.io.ByteArrayInputStream;
A simple Provider-based Web service implementation. author Copyright c 2010, Oracle andor its affiliates.
All Rights Reserved. The ServiceMode annotation specifies whether the Provider instance
receives entire messages or message payloads. ServiceModevalue = Service.Mode.PAYLOAD
Standard JWS annotation that configures the Provider-based Web service. WebServiceProviderportName = SimpleClientPort,
serviceName = SimpleClientService, targetNamespace = http:jaxws.webservices.examples,
wsdlLocation = SimpleClientService.wsdl public class SimpleClientProviderImpl implements ProviderSource {
Invokes an operation according to the contents of the request message. public Source invokeSource source {
try { DOMResult dom = new DOMResult;
Transformer trans = TransformerFactory.newInstance.newTransformer; trans.transformsource, dom;
Node node = dom.getNode; Get the operation name node.
Node root = node.getFirstChild; Get the parameter node.
Node first = root.getFirstChild; String input = first.getFirstChild.getNodeValue;
Get the operation name. String op = root.getLocalName;
if invokeNoTransaction.equalsop { return sendSourceinput;
} else { return sendSource2input;
} }
catch Exception e { throw new RuntimeExceptionError in provider endpoint, e;
} }
private Source sendSourceString input {
Operating at the XML Message Level 16-5
String body = ns:invokeNoTransactionResponse
xmlns:ns=\http:jaxws.webservices.examples\return + constructed: + input
+ returnns:invokeNoTransactionResponse; Source source = new StreamSourcenew ByteArrayInputStreambody.getBytes;
return source; }
private Source sendSource2String input { String body =
ns:invokeTransactionResponse xmlns:ns=\http:jaxws.webservices.examples\return
+ constructed: + input + returnns:invokeTransactionResponse;
Source source = new StreamSourcenew ByteArrayInputStreambody.getBytes; return source;
} }
16.3.2 Specifying the Message Format
Specify one of the message formats supported, defined in Table 16–2
, when developing the Provider-based implementation class.
For example, in the Provider implementation example shown in Section 16.3.1,
Example of a JWS File That Implements a Web Service Provider-based Endpoint , the
SimpleClientProviderImpl class implements the ProviderSource interface, indicating that both the input and output types are java.xml.transform.Source
objects.
public class SimpleClientProviderImpl implements ProviderSource { . . .
}
16.3.3 Specifying that the JWS File Implements a Web Service Provider WebServiceProvider Annotation
Use the standard javax.xml.ws.WebServiceProvider annotation to specify, at the class level, that the JWS file implements a Web service provider, as shown in the
following code excerpt:
WebServiceProviderportName = SimpleClientPort, serviceName = SimpleClientService,
targetNamespace = http:jaxws.webservices.examples, wsdlLocation = SimpleClientService.wsdl
In the example, the service name is SimpleClientService, which will map to the wsdl:service element in the generated WSDL file. The port name is
SimpleClientPort, which will map to the wsdl:port element in the generated WSDL. The target namespace used in the generated WSDL is
http:jaxws.webservices.examples and the WSDL location is local to the Web service provider, at SimpleClientService.wsdl.
For more information about the WebServiceProvider annotation, see https:jax-ws.dev.java.netnonav2.1.5docsannotations.html
.
16-6 Programming Advanced Features of JAX-WS Web Services for Oracle WebLogic Server
16.3.4 Specifying the Usage Mode ServiceMode Annotation
The javax.xml.ws.ServiceMode annotation is used to specify whether the Web service Provider-based endpoint receives entire messages Service.Mode.MESSAGE
or message payloads Service.Mode.PAYLOAD only.
For example: ServiceModevalue = Service.Mode.PAYLOAD
If not specified, the ServiceMode annotation defaults to Service.Mode.PAYLOAD. For a list of valid message format and usage mode combinations, see
Table 16–2 .
For more information about the ServiceMode annotation, see https:jax-ws.dev.java.netnonav2.1.4docsannotations.html
.
16.3.5 Defining the invoke Method
The ProviderT interface defines a single method that you must define in your implementation class:
T invokeT request When a Web service request is received, the invoke method is called and provides
the message or message payload as input to the method using the specified message format.
For example, in the Provider implementation example shown in Section 16.3.1,
Example of a JWS File That Implements a Web Service Provider-based Endpoint , the
class defines an invoke method to take as input the Source parameter and return a Source response.
public Source invokeSource source { try {
DOMResult dom = new DOMResult; Transformer trans = TransformerFactory.newInstance.newTransformer;
trans.transformsource, dom; Node node = dom.getNode;
Get the operation name node. Node root = node.getFirstChild;
Get the parameter node. Node first = root.getFirstChild;
String input = first.getFirstChild.getNodeValue; Get the operation name.
String op = root.getLocalName; if invokeNoTransaction.equalsop {
return sendSourceinput; } else {
return sendSource2input; }
} catch Exception e {
throw new RuntimeExceptionError in provider endpoint, e; }
}
16.3.6 Starting from WSDL
If the Provider-based endpoint is being generated from a WSDL file, the provider WSDL extension can be used to mark a port as a provider. For example:
Operating at the XML Message Level 16-7
?xml version=1.0 encoding=UTF-8 standalone=yes? bindings wsdlLocation=SimpleClientService.wsdl
xmlns=http:java.sun.comxmlnsjaxws bindings node=wsdl:definitions
package name=provider.server providertrueprovider
bindings
16.4 Developing a Web Service Dispatch Client
