Implementing dynamic JAX-WS web services clients
You can develop dynamic web services clients based on the Web Services for Java™ Platform, Enterprise Edition (Java EE) specification and the Java API for XML-Based Web Services (JAX-WS) programming model.
Before you begin

About this task
- Developing web services clients based on the JAX-WS programming model
Web services clients that can both access and invoke JAX-WS web services are developed based on the Web Services for Java Platform, Enterprise Edition (Java EE) specification. The application server supports Enterprise JavaBeans (EJB) clients, Java EE application clients, JavaServer Pages (JSP) files and servlets that are based on the JAX-WS programming model. Web services clients based on the JAX-RPC specification can invoke JAX-WS based web services if the Web Services Description Language (WSDL) file complies with the Web Services-Interoperability (WS-I) Basic Profile.
The JAX-WS client programming model supports both the Dispatch client API and the dynamic proxy client API. The Dispatch client API is a dynamic client programming model, whereas the static client programming model for JAX-WS is the dynamic proxy client. The Dispatch and dynamic proxy clients enable both synchronous and asynchronous invocation of JAX-WS web services.
The Dispatch client API, javax.xml.ws.Dispatch, is an XML messaging-oriented client that is intended for advanced XML developers who prefer using XML constructs. The Dispatch API can send data in either PAYLOAD or MESSAGE mode. When using the PAYLOAD mode, the Dispatch client is only responsible for providing the contents of the soap:Body and JAX-WS includes the payload in a soap:Envelope element. When using the MESSAGE mode, the Dispatch client is responsible for providing the entire SOAP envelope. You do not need a WSDL file if you are developing a dynamic client.
In contrast, the dynamic proxy client invokes a web service based on a service endpoint interface (SEI) that is provided. The JAX-WS dynamic proxy instances leverage the dynamic proxy function in the base Java SE Runtime Environment (JRE) 6.
To develop web services clients based on the JAX-WS programming model, you must determine the client model that best suits the needs of your web service application. If you want to work directly with XML rather than a Java abstraction and work with either the message structure or the message payload structure, use the Dispatch API to develop a dynamic web services client. However, if you want the Web services client to invoke the service based on service endpoint interfaces with a dynamic proxy, use the Dynamic Proxy API to develop a static web service client. Read about implementing static JAX-WS web services clients to learn how to develop static web services clients.
Complete this task to develop a dynamic web services client using the Dispatch API.
To invoke web services asynchronously using a static or dynamic JAX-WS client, determine if you want to implement the callback or the polling model. Read about invoking JAX-WS web services asynchronously for more information regarding implementing asynchronous callback or polling for web service clients. The JAX-WS programming model for the service and client uses annotations to represent the same information that was provided in JAX-RPC client binding in a vendor-neutral manner.
- Managed and unmanaged JAX-WS web services clients
The application server supports both managed and unmanaged web services clients when using the JAX-WS programming model:
- Managed clients
Web services for Java EE clients are defined by Java Specification Requirements (JSR) 109 and are managed clients because they run in a Java EE container. These clients are packaged as enterprise archive (EAR) files and contain components that act as service requesters. These components are comprised of a Java EE client application, a web component such as a servlet or JavaServer Pages (JSP), or a session Enterprise JavaBeans (EJB). Web services managed clients use JSR 109 APIs and deployment information to look up and invoke a web service.
For the managed clients, you can use Java Naming and Directory Interface (JNDI) look up to perform service lookup, or you can use annotations to inject instances of a JAX-WS service or port. Read about setting up UserName token Web Services Security, digital signature Web Services Security and Lightweight Third-Party Authentication (LTPA) token Web Services Security. The following code is an example of a context lookup that is JSR 109 compliant:
InitialContext ctx = new InitialContext(); FredsBankService service =(FredsBankService)ctx.lookup("java:comp/env/service/FredsBankService"); FredsBank fredsBank = service.getFredsBankPort(); long balance = fredsBank.getBalance();
You can use the @WebServiceRef or @Resource annotation to declare managed clients. The usage of these annotations results in the type specified by the annotation being bound into the JNDI namespace. When the annotations are used on a field or method, they also result in injection of a JAX-WS service or port instance. You can use these annotations instead of declaring service-ref entries in the client deployment descriptor. You can still use the client deployment descriptor to declare JAX-WS managed clients, similar to JAX-RPC managed clients. You can also use the deployment descriptor to override and augment the information specified by @WebServiceRef and @Resource annotations. Use the @WebServiceRef annotation to bind and inject a JAX-WS service or port instance. You can only use the @Resource annotation to bind and inject a JAX-WS service instance. The use of either of these annotations to declare JAX-WS managed clients is only supported in certain class types. Some of these class types include JAX-WS endpoint implementation classes, JAX-WS handler classes, enterprise bean classes, and servlet classes.
The following example uses the @WebServiceRef annotation to obtain an instance of FredsBank:
Now within the class, the fredsBank field does not have to be initialized. You can use this field directly:@WebServiceRef(name=”service/FredsBankPort”, value=FredsBankService.class) FredsBank fredsBank;
long balance = fredsBank.getBalance();
You can also use the @WebServiceRef annotation to obtain instances of JAX-WS service classes; for example:@WebServiceRef(name=”service/FredsBankService”) FredsBankService service;
Now within the class, the service field does not have to be initialized. You can use this field directly:FredsBank fredsBank = service.getFredsBankPort(); long balance = fredsBank.getBalance();
In addition to the @WebServiceRef annotation, you can use the @Resource annotation to obtain an instance of JAX-WS service classes; for example:@Resource(name=”service/FredsBankService”, type=FredsBankService.class) FredsBankService service;
As with the @WebServiceRef annotation, you can now use the service field without instantiation; for example:FredsBank fredsBank = service.getFredsBankPort(); long balance = fredsBank.getBalance();
You can use the @Resource or @WebServiceRef annotations on a class. In this case, JNDI must be used to lookup the JAX-WS service or port; for example:@WebServiceRef(name=”service/FredsBankService”, type=FredsBankService”) public class J2EEClientExample { … … public static void main(String[] args) { … … InitialContext ctx = new InitialContext(); FredsBankService service =(FredsBankService)ctx.lookup("java:comp/env/service/FredsBankService"); FredsBank fredsBank = service.getFredsBankPort(); long balance = fredsBank.getBalance(); } … }
For more information on using the @WebServiceRef and @Resource annotations, see the specifications for JSR-109, JSR-224, JSR-250, and Java Platform Enterprise Edition 5 (Java EE 5).
As mentioned previously, when using annotations or JNDI to obtain instances of JAX-WS services and ports, do not instantiate the returned objects. Doing so results in an unmanaged client instance. The following example shows an example of incorrect usage:@WebServiceRef(name=”service/FredsBankService”) FredsBankService service; service = new FredsBankService(); // client becomes unmanaged.
For JAX-WS managed clients that are declared by the @WebServiceRef or @Resource annotation and for clients that are declared using service-ref entries in the client deployment descriptor, you can use the administrative console to supply the endpoint URL that the client uses. This specified URL overrides the endpoint URL in the WSDL document that is used by the client. To learn more about specifying this endpoint URL, see the configuring web services client bindings documentation.
- Unmanaged clients
Java Platform, Standard Edition (Java SE 6) clients that use the JAX-WS runtime environment to invoke web services and do not run in any Java EE container are known as unmanaged clients. A web services unmanaged client is a stand-alone Java client that can directly inspect a WSDL file and formulate the calls to the web service by using JAX-WS APIs. These clients are packaged as JAR files, which do not contain any deployment information.
- Managed clients
從 WebSphere Application Server 7.0 版和更新的版本開始,系統會掃描 Java EE 5 應用程式模組(Web 應用程式模組 2.5 版或更新版本,或是 EJB 模組 3.0 版或更新版本)中是否有註釋可識別 JAX-WS 服務和用戶端。 不過,為了效能考量,依預設,系統不會掃描 Java EE 5 之前的應用程式模組(Web 應用程式模組 2.4 版或更早版本,或 EJB 模組 2.1 版或更早版本)中是否有 JAX-WS 註釋。在 6.1 版 Feature Pack for Web Services 中,預設行為是在應用程式安裝期間,掃描 Java EE 5 之前的 Web 應用程式模組來識別 JAX-WS 服務,以及掃描 Java EE 5 之前的 Web 應用程式模組和 EJB 模組,來尋找服務用戶端。由於 WebSphere Application Server 7.0 版及更新版本的預設行為是不在安裝應用程式或啟動伺服器期間掃描 Java EE 5 之前的模組是否含有註釋,因此為了保留與舊版特性套件的舊版相容性,您必須在伺服器上配置 Web 應用程式保存檔 (WAR) 的 META-INF/MANIFEST.MF 中的 UseWSFEP61ScanPolicy 內容或 EJB 模組,或定義 Java 虛擬機器自訂內容 com.ibm.websphere.webservices.UseWSFEP61ScanPolicy,來要求在安裝應用程式及啟動伺服器期間進行掃描。如果要進一步瞭解註釋掃描,請參閱 JAX-WS 註釋資訊。
Procedure
Results
You have created and tested a web services client application.
What to do next
After you develop a web services application client, and the client is statically bound, the service endpoint used by the implementation is the one that is identified in the WSDL file that you used during the development process. During or after installation of the web services application, you might want to change the service endpoint. For managed clients, you can change the endpoint with the administrative console or the wsadmin scripting tool. For unmanaged JAX-WS web services clients, you can change the endpoint from within the client application.
You can additionally consider customizing your web services by implementing extensions to your web services client. Some examples of these extensions include sending and receiving values in SOAP headers or sending and receiving HTTP or Java Message Service (JMS) transport headers. To learn more about these extensions, read about implementing extensions to web services clients.