|
In This Issue
Welcome to the Enterprise Java Technologies Tech Tips for September 30, 2006. Here you'll get tips on using enterprise Java technologies and APIs, such as those in Java Platform, Enterprise Edition (Java EE).
These tips were developed using the Java EE 5 SDK. You can
download the SDK from the Java EE Downloads page.
You can download the sample archive for the tip Configuring
JAX-WS Handlers on the Client.
Any use of this code and/or information below is subject to the license terms.
See the Subscribe/Unsubscribe note at the end of this newsletter to subscribe to Tech Tips that focus on technologies and products in other Java platforms.
Configuring JAX-WS Handlers on the Client
by Rama Pulavarthi
The August 26, 2006 Tech Tip, Configuring, Packaging, and Deploying JAX-WS Handlers described how to configure, package, and deploy handlers for a web service on the server. This tip shows different ways to configure handlers on a web service client.
Using Handlers on the Client
Handlers can be configured on the client using a @HandlerChain annotation or through an API defined by JAX-WS. The configuration is done by a handler resolver. A Service instance provides access to the handler resolver. The handler resolver configures a set of handlers on a per-service, per-port, or per-protocol binding basis. When a Service instance is used to create a proxy or a Dispatch instance, then the handler resolver currently registered with the service is used to create the required handler chain.
How you configure handlers on the client depends on whether the client is statically generated (through wsimport) or is a dynamic client (using Dispatch). In general, it is easier to specify a handler configuration if you use a static client. That's because the wsimport automatically puts the @HandlerChain annotation on the generated service class. This is described in the section "Configuring Handlers Through JAX-WS Customization" in the August 26, 2006 Tech Tip.
The following example shows a generated service class with handler chain information. The handler chain file specified in the service class defines the handler resolver for the service. This sets the handler chains for all the proxies created using that service.
@WebServiceClient(name = "HelloService1",
targetNamespace = "http://example.com/handlers",
wsdlLocation =
"http://localhost:8080/service1/HelloService1?wsdl")
@HandlerChain(file = "HelloService1_handler.xml")
public class HelloService1
extends Service
{
@WebEndpoint
...
...
}
If the client is a web client or an application client that runs in a Java EE container, you can also specify an @HandlerChain annotation on web service references. This sets the handlers on the injected service. Here's an example:
public class WebClient extends HttpServlet {
@javax.jws.HandlerChain(file="myhandler.xml")
@WebServiceRef HelloService2 service;
public void doGet(HttpServletRequest req,
HttpServletResponse resp)
throws javax.servlet.ServletException {
...
}
}
You can also set a handler resolver programmatically to define handlers for a service. This method is generally used by Dispatch-based clients. The following example programmatically sets a custom handler resolver on a service. Notice that the same handlers specified in the configuration file are set through a handler resolver.
Public void test2() {
client.HelloService2 service =
new client.HelloService2();
// set new HandlerResolver
service.setHandlerResolver(new MyHandlerResolver());
...
}
public class MyHandlerResolver implements HandlerResolver {
public java.util.List<Handler>
getHandlerChain(PortInfo portInfo) {
List<Handler> handlerChain = new ArrayList<Handler>();
QName serviceQName = portInfo.getServiceName();
if(serviceQName.getNamespaceURI().equals(
"http://example.com/handlers") &&
serviceQName.getLocalPart().startsWith(
"HelloService")) {
handlers.common.LogicalLoggingHandler lh =
new handlers.common.LogicalLoggingHandler();
handlerChain.add(lh);
handlers.common.SOAPLoggingHandler sh =
new handlers.common.SOAPLoggingHandler();
handlerChain.add(sh);
}
if(portInfo.getBindingID().equals(
"http://schemas.xmlsoap.org/wsdl/soap/http")) {
client.handlers.SOAP11Handler sh =
new client.handlers.SOAP11Handler();
handlerChain.add(sh);
}
if(portInfo.getBindingID().equals(
"http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/")) {
client.handlers.SOAP12Handler sh =
new client.handlers.SOAP12Handler();
handlerChain.add(sh);
}
return handlerChain;
}
}
You can also configure handler chains on the client side at runtime by setting a chain directly on a BindingProvider (for example, a Dispatch object or a port proxy). This can be handy if you want to define handlers for a particular port. Here's an example that takes that approach:
public void test4() {
client.HelloService1 service =
new client.HelloService1();
client.Hello1 port = service.getHello1Port();
//List<Handler> handlerChain =
((BindingProvider)port).getBinding().getHandlerChain();
client.handlers.SOAP11Handler sh =
new client.handlers.SOAP11Handler();
List<Handler> new_handlerChain =
new ArrayList<Handler>();
new_handlerChain.add(sh);
((BindingProvider)port).getBinding().setHandlerChain(new_handlerChain);
}
Running the Sample Code
The sample code for the August 26, 2006 Tech Tip, Configuring, Packaging, and Deploying JAX-WS Handlers includes code that configures handlers on a web service client. To run the sample code:
- If you haven't already done so, download Java EE 5 SDK from the Java EE Downloads Page, and install it.
- Set the following environment variables:
JAVAEE_HOME. This should point to where you installed the Java EE 5 SDK.ANT_HOME. This should point to where ant is installed. Ant is included in the Java EE 5 SDK bundle that you downloaded. (In Windows, it's in the lib\ant subdirectory.)JAVA_HOME. This should point to the location of JDK 5.0 on your system. JDK is included in the Java EE 5 SDK bundle that you downloaded. (In Windows, it's in the jdk subdirectory.)
Add $JAVA_HOME/bin, $ANT_HOME/bin, and $JAVAEE_HOME/bin to your PATH environment variable
- Download the sample package and extract its contents. You should now see the newly extracted directory as
<sample_install_dir>/handler_config, where <sample_install_dir> is the directory in which you installed the sample package.
- Change to the
handler_config directory and edit the build.properties file as appropriate. For example, if the admin host is remote, change the value of admin.host from the default (localhost) to the appropriate remote host. Also, make sure that the javaee.server.passwordfile location is correct, and modify the wsdlLocation in the config-client.xml file, if the host or port is changed.
- Start the Application Server by entering the following commmand:
$JAVAEE_HOME/bin/asadmin start-domain domain1
- Build and deploy the sample service and webclient. From the
handler_config directory enter the following command:
ant deploy
This builds the web service, creates a handler_config.war file, and deploys the .war file. It also creates a web client and deploys the wsclient.war file.
-
Build the client and run the sample. From the
handler_config directory enter the following command:
ant run
This generates the client artifacts by calling wsimport, and runs the sample.
The sample includes five handler-related tests:
test1 uses handlers that are configured on a proxy using JAX-WS WSDL customization.test2 uses a HandlerResolver to set handlers on a service. test3 uses handlers with a Dispatch client.test4 uses handlers that are set for a particular port.test5 invokes a WebClient(servlet), which demonstrates the use of @HandlerChain on Web Service reference.
Here is the output displayed by the test1 part of the sample:
[java] ************ Start:test1 *************
[java] Executing LogicalLoggingHandler
[java] Outbound message:
[java] <ns2:sayHello xmlns:ns2="http://example.com/handlers">
[java] <arg0>Duke</arg0>
[java] </ns2:sayHello>
[java] Executing SOAPLoggingHandler
[java] Outbound message:
[java] <?xml version="1.0" ?><soapenv:Envelope xmlns:soapenv=
"http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http:/
/www.w3.org/2001/XMLSchema" xmlns "http://example.com/handler
s"><soapenv:Body><ns2:sayHello xmlns:ns2="http:/example.com/h
andlers"><arg0>Duke</arg0></ns2:sayHello></soapenv:Body></soa
p:Envlope>
[java] Executing SOAP11Handler
[java] Executing SOAP11Handler
[java] Verifying Inbound message
[java] Executing SOAPLoggingHandler
[java] Inbound message:
[java] <?xml version="1.0" ?><soapenv:Envelope xmlns:soapenv=
"http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http:/
/example.com/handlers" xmlns:xsd="http://www.w3.org/2001/XMLS
chema"><soapenv:Body><ns1:sayHelloResponse><return>Hello Duk
e!</return></ns1:sayHelloResponse></soapenv:Body></soapenv:En
velope>
[java] Executing LogicalLoggingHandler
[java] Inbound message:
[java] <ns1:sayHelloResponse xmlns:ns1="http://example.com/ha
ndlers">
[java] <return>Hello Duke!</return>
[java] </ns1:sayHelloResponse>
[java] Result = Hello Duke!
[java] ************ End:test1 ***************
Summary
JAX-WS provides different ways to configure handlers on your web service client, you need to choose the one that best suits your application.
About the Author
Rama Pulavarthi is a Member of Technical Staff in the Java Web Services group at Sun Microsystems. He currently works on the development of the JAX-WS Reference Implementation. He previously lead the Software Quality Engineering effort for JAX-RPC.
Tech Tips Quiz
Over the years, the Enterprise Java Technologies Tech Tips have covered a wide variety of enterprise Java technology topics. Here's a short quiz that tests your knowledge of some topics covered in past Tech Tips. You can find the answers at the end of the quiz.
- Which of the following inheritance strategies is not supported by the Java Persistence API?
- Single Table Per Class Hierarchy
- Joined Subclass
- Single Table Per Class
- Multiple Hierarchy
- What is the primary purpose of the
javax.xml.ws.Provider API?
- Binds XML to Java objects.
- Allows web services to work directly with messages.
- Simplifies WSDL creation.
- Specifies the URL of a web service provider.
- None of the above
- Which of the following statements about the
ELResolver class is true?
- In Java EE 5, the classes
VariableResolver and PropertyResolver have been merged into the ELResolver class.
- The way an expression is resolved can be customized by adding custom
ELResolver subclasses to the ELResolver chain.
- To make an
ELResolver class visible to the Java EE runtime, it must be declared in an application configuration resource file.
- All of the above.
- What does the
<service-name-pattern> element in the following set of XML statements do:
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
<handler-chain>
<service-name-pattern
xmlns:ns1="http://example.com/handlers">
ns1:HelloService
</service-name-pattern>
<handler/>
<handler/>
</handler-chain>
</handler-chains>
- Applies the handlers specified in the
<handler-chain> element to the service with the Java EE qname {http://example.com/handlers}HelloService.
- Adds a service named
HelloService to the handlers specified in the <handler-chain> element.
- Applies the handlers specified in the
<handler-chain> element to all ports whose names begin with HelloService.
- None of the above.
- What role does an
XMLHttpRequest object play in an AJAX-enabled application?
- It's used as a proxy to transmit requests to a server in a different domain.
- It's used to identify a filter for exchange of XML-based Ajax requests between the client and server.
- It's used to transmit Ajax requests asynchronously over HTTP to a server-side component.
- There is no such thing as an
XMLHttpRequest object.
Answers
- Which of the following inheritance strategies is not supported by the Java Persistence API?
- Multiple Hierarchy. The Java Persistence API allows for three different inheritance strategies that dictate how subclasses are mapped to database tables. The three strategies are single table per class hierarchy, joined subclass, and single table per class. For more information about these inheritance strategies, see the June 24, 2006 Tech Tip Inheritance and the Java Persistence API.
- What is the primary purpose of the
javax.xml.ws.Provider API?
- Allows web services to work directly with messages. The JAX-WS 2.0 specification provides two new APIs which make it possible for web services to work with messages or message payloads. The APIs are
javax.xml.ws.Provider and java.xml.ws.Dispatch. Provider is a server-side API, while Dispatch is a client-side API. You can learn more about these APIs in the July 29, 2006 Tech Tip Document Handling Using JAX-WS Dispatch and Provider APIs.
- Which of the following statements about the
ELResolver class is true?
- All of the above. For more about the
ELResolver class, especially how to create a customized ELResolver, see the Tech Tip Extending the Java EE Unified Expression Language with a Custom ELResolver.
- What does the
<service-name-pattern> element in the following set of XML statements do:
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
<handler-chain>
<service-name-pattern
xmlns:ns1="http://example.com/handlers">
ns1:HelloService
</service-name-pattern>
<handler/>
<handler/>
</handler-chain>
</handler-chains>
- Applies the handlers in the specified in the
<handler-chain> element to the service with the Java EE qname {http://example.com/handlers}HelloService. The <service-name-pattern> element applies handlers to specific services. Handlers are interceptors that can be easily plugged into the JAX-WS 2.0 runtime environment to do additional processing of inbound and outbound messages. A handler chain is an ordered list of handlers that is used for configuring handlers. Learn more about JAX-WS handlers in the June 24, 2006 Tech Tip Writing a Handler in JAX-WS. Learn more about handler chains in the August 26, 2006 Tech Tip Configuring, Packaging, and Deploying JAX-WS Handlers.
- What role does an
XMLHttpRequest object play in an AJAX-enabled application?
- It's used to transmit Ajax requests asynchronously over HTTP to a server-side component. An
XMLHttpRequest object plays a central role in the AJAX methodology as the means of interaction between the client and server-side component that processes AJAX requests. For more information about AJAX, see the November 22, 2005 Tech Tip Using AJAX With Java Technology.
|
Print-friendly Version
