Enterprise Java Technologies Tech Tips Tips, Techniques, and Sample Code 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). This issue covers: * Configuring JAX-WS Handlers on the Client * Tech Tips Quiz These tips were developed using the Java EE 5 SDK. You can download the SDK from the Java EE Downloads page (http://java.sun.com/javaee/downloads/index.jsp). You can view this issue of the Tech Tips on the Web at http://java.sun.com/mailers/techtips/enterprise/2006/TechTips_Sept06.html You can download the sample archive for the tip Configuring JAX-WS Handlers on the Client at: http://java.sun.com/mailers/techtips/enterprise/2006/download/ttaug2006handlers.zip. Any use of this code and/or information below is subject to the license terms at http://developers.sun.com/dispatcher.jsp?uid=6910008. 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" (http://java.sun.com/mailers/techtips/enterprise/2006/TechTips_Aug06.html#2) 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 getHandlerChain(PortInfo portInfo) { List handlerChain = new ArrayList(); 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 handlerChain = ((BindingProvider)port).getBinding().getHandlerChain(); client.handlers.SOAP11Handler sh = new client.handlers.SOAP11Handler(); List new_handlerChain = new ArrayList(); 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" (http://java.sun.com/mailers/techtips/enterprise/2006/TechTips_Aug06.html#2) includes code that configures handlers on a web service client. To run the sample code: 1. If you haven't already done so, download Java EE 5 SDK from the Java EE Downloads Page (http://java.sun.com/javaee/downloads/index.jsp), and install it. 2. Set the following environment variables: o JAVAEE_HOME. This should point to where you installed the Java EE 5 SDK. o 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.) o 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. 3. Download the sample package (http://java.sun.com/mailers/techtips/enterprise/2006/download/ttaug2006handlers.zip) and extract its contents. You should now see the newly extracted directory as /handler_config, where is the directory in which you installed the sample package. 4. 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. 5. Start the Application Server by entering the following commmand: $JAVAEE_HOME/bin/asadmin start-domain domain1 6. 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. 7. 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: o test1 uses handlers that are configured on a proxy using JAX-WS WSDL customization. o test2 uses a HandlerResolver to set handlers on a service. o test3 uses handlers with a Dispatch client. o test4 uses handlers that are set for a particular port. o 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] [java] Duke [java] [java] Executing SOAPLoggingHandler [java] Outbound message: [java] Duke [java] Executing SOAP11Handler [java] Executing SOAP11Handler [java] Verifying Inbound message [java] Executing SOAPLoggingHandler [java] Inbound message: [java] Hello Duk e! [java] Executing LogicalLoggingHandler [java] Inbound message: [java] [java] Hello Duke! [java] [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. 1) Which of the following inheritance strategies is not supported by the Java Persistence API? a) Single Table Per Class Hierarchy b) Joined Subclass c) Single Table Per Class d) Multiple Hierarchy 2) What is the primary purpose of the javax.xml.ws.Provider API? a) Binds XML to Java objects. b) Allows web services to work directly with messages. c) Simplifies WSDL creation. d) Specifies the URL of a web service provider. e) None of the above 3) Which of the following statements about the ELResolver class is true? a) In Java EE 5, the classes VariableResolver and PropertyResolver have been merged into the ELResolver class. b) The way an expression is resolved can be customized by adding custom ELResolver subclasses to the ELResolver chain. c) To make an ELResolver class visible to the Java EE runtime, it must be declared in an application configuration resource file. d) All of the above. 4) What does the element in the following set of XML statements do: ns1:HelloService a) Applies the handlers specified in the element to the service with the Java EE qname {http://example.com/handlers}HelloService. b) Adds a service named HelloService to the handlers specified in the element. c) Applies the handlers specified in the element to all ports whose names begin with HelloService. d) None of the above. 5) What role does an XMLHttpRequest object play in an AJAX-enabled application? a) It's used as a proxy to transmit requests to a server in a different domain. b) It's used to identify a filter for exchange of XML-based AJAX requests between the client and server. c) It's used to transmit AJAX requests asynchronously over HTTP to a server-side component. d) There is no such thing as an XMLHttpRequest object. Answers 1) Which of the following inheritance strategies is not supported by the Java Persistence API? d) 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" (http://java.sun.com/mailers/techtips/enterprise/2006/TechTips_June06.html#2). 2) What is the primary purpose of the javax.xml.ws.Provider API? b) Allows web services to work directly with messages. The JAX-WS 2.0 specification (http://jcp.org/en/jsr/detail?id=224) 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" (http://java.sun.com/mailers/techtips/enterprise/2006/TechTips_July06.html#1). 3) Which of the following statements about the ELResolver class is true? d) 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" (http://java.sun.com/mailers/techtips/enterprise/2006/TechTips_Aug06.html#1). 4) What does the element in the following set of XML statements do: ns1:HelloService a) Applies the handlers in the specified in the element to the service with the Java EE qname {http://example.com/handlers}HelloService. The 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" (http://java.sun.com/mailers/techtips/enterprise/2006/TechTips_June06.html#1). Learn more about handler chains in the August 26, 2006 Tech Tip "Configuring, Packaging, and Deploying JAX-WS Handlers" (http://java.sun.com/mailers/techtips/enterprise/2006/TechTips_Aug06.html#2). 5) What role does an XMLHttpRequest object play in an AJAX-enabled application? c) 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" (http://java.sun.com/developer/EJTechTips/2005/tt1122.html#1). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - DEVELOPER ASSISTANCE Need programming advice on Java EE? Try Developer Expert Assistance (http://developers.sun.com/services/expertassistance/) . . . . . . . . . . . . . . . . . . . . . . . Please read our Terms of Use and Licensing policies: http://www.sun.com/share/text/termsofuse.html http://developers.sun.com/dispatcher.jsp?uid=6910008 PRIVACY STATEMENT: Sun respects your online time and privacy (http://sun.com/privacy). You have received this based on your e-mail preferences. If you would prefer not to receive this information, please follow the steps at the bottom of this message to unsubscribe. * FEEDBACK Comments? Send your feedback on the Enterprise Java Technologies Tech Tips to: Enterprise_TechTips@sun.com * SUBSCRIBE/UNSUBSCRIBE Subscribe to other Java developer Tech Tips: - Core Java Technologies Tech Tips. Get tips on using core Java technologies and APIs, such as those in the Java 2 Platform, Standard Edition (J2SE). - Wireless Developer Tech Tips. Get tips on using wireless Java technologies and APIs, such as those in the Java 2 Platform, Micro Edition (J2ME). To subscribe to these and other JDC publications: - Go to the Sun Developer Network - Subscriptions page, (https://softwarereg.sun.com/registration/developer/en_US/subscriptions), choose the newsletters you want to subscribe to and click "Submit". - To unsubscribe, go to the Subscriptions page, (https://softwarereg.sun.com/registration/developer/en_US/subscriptions), uncheck the appropriate checkbox, and click "Submit". - To use our one-click unsubscribe facility, see the link at the end of this email: - ARCHIVES You'll find the Enterprise Java Technologies Tech Tips archives at: http://java.sun.com/developer/EJTechTips/index.html - COPYRIGHT Copyright 2006 Sun Microsystems, Inc. All rights reserved. 901 San Antonio Road, Palo Alto, California 94303 USA. This document is protected by copyright. For more information, see: http://java.sun.com/developer/copyright.html Enterprise Java Technologies Tech Tips September 30, 2006 Trademark Information: http://www.sun.com/suntrademarks/ Java, J2SE, J2EE, J2ME, and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.