Developing and deploying Web services clients

You can develop Web services clients based on the Web Services for Java 2 Platform, Enterprise Edition (J2EE) specification and the supported Web services development programming models.

About this task

Developing Web services clients based on the JAX-WS programming model New or updated for this feature pack
Best practice Best practice: The WebSphere® Application Server Version 6.1 Feature Pack for Web Services extends the capabilities of this product to introduce support for the Java API for XML-Based Web Services (JAX-WS) 2.0 programming model. JAX-WS is the next generation Web services programming model complimenting the foundation provided by the Java API for XML-based RPC (JAX-RPC) programming model. Using the strategic JAX-WS programming model, development of Web services and clients is simplified through support of a standards-based annotations model. Although the JAX-RPC programming model and applications are still supported, take advantage of the easy-to-implement JAX-WS programming model to develop new Web services applications and clients. bprac

Web services clients that can both access and invoke a JAX-WS Web service are developed based on the Web Services for Java 2 Platform, Enterprise Edition (J2EE) specification. The Feature Pack for Web Services supports Enterprise JavaBeans (EJB) clients, J2EE application clients, JavaServer Pages (JSP) files and servlets. 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 Feature Pack for Web Services only supports unmanaged clients even when the unmanaged clients are running in a Java 2 Platform, Enterprise Edition (J2EE) container. Unmanaged clients are clients that do not use container managed services. These clients are packaged as Java archive (JAR) files which do not contain any JSR-109 Web Service client deployment information. Web services unmanaged clients that run in a J2EE container are responsible for the instantiation of services rather than the J2EE container managing the instantiation of services.

The JAX-WS Web service 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. 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 Runtime Environment Version 5.

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 service client. 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. After the proxies are created, the client application can invoke methods on these proxies just like a standard implementation of the service endpoint interfaces. The remainder of this article describes how to develop a static Web services client starting with a WSDL file.

To invoke Web services asynchronously using a static or dynamic JAX-WS client, determine if you will 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.

Developing Web services clients based on the JAX-RPC programming model
The Web services client programming model provides the guidelines for accessing Web services in a J2EE environment. You can develop Web services clients based on the Web Services for Java 2 Platform, Enterprise Edition (J2EE) specification and the Java API for XML-based remote procedure call (JAX-RPC) specification. The application server supports the following two types of basic JAX-RPC Web services clients:
  • Managed clients

    Web services for J2EE clients are defined by Java Specification Requirements (JSR) 109 and are known as managed clients because they run in a J2EE container. These clients are packaged as enterprise archive (EAR) files and contain components that act as service requesters. These components can be a J2EE 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, the service lookup is through Java Naming and Directory Interface (JNDI) lookup. 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 is an example of a context lookup that is JSR 109 compliant:

    InitialContext ctx = new InitialContext();
        FredsBankServiceLocator locator
    =(FredsBankService)ctx.lookup("java:comp/env/service/FredsBankService");
        FredsBank fb = locator.getFredsBank(url);
        long balance = fb.getBalance();  

    When you are instantiating a context lookup for a managed client, do not use new() for the service locator. Here is an example that is not JSR 109 compliant (new ServiceLocator):

    Properties prop = new Properties();
        InitialContext ctx = new InitialContext(prop);
        FredsBankServiceLocator locator = new FredsBankServiceLocator();
        FredsBank fb = locator.getFredsBank(url);
        long balance = fb.getBalance(); 

    Without the lookup() call, the client has no access to the deployment descriptor. The Web services security configuration is in the Web services deployment descriptor.

  • Unmanaged clients

    J2SE clients that use the JAX-RPC run time to invoke Web services and do not run in any J2EE 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 the JAX-RPC APIs directly. These clients are packaged as JAR files which do not contain any deployment information.

For a Java application to act as a Web service client, a mapping between the WSDL file and the Java application must exist. For JAX-RPC Web services, the mapping is defined by the Java API for XML-based RPC (JAX-RPC) specification. You can use a Java component to implement a Web service by specifying the component interface and binding information in the WSDL file and designing the application server infrastructure to accept the service request. This entire process is based on the Web Services for J2EE specification. The JAX-RPC specification defines the mapping between a WSDL file, Java code and XML Schema types.

Procedure

  1. Obtain the Web Services Description Language (WSDL) document for the Web service that you want to access.

    You can locate the WSDL from the services provider through e-mail, through a Uniform Resource Locator (URL) or by looking it up in a Universal Description, Discovery and Integration (UDDI) registry.

  2. Develop client artifacts from a WSDL file.
    • New or updated for this feature pack For static JAX-WS Web services applications using the dynamic proxy API, develop client artifacts from a WSDL file using the wsimport command.
    • For JAX-RPC Web service applications, develop client bindings from a WSDL file using the wsdl2java command-line tool. The information needed to invoke the Web service is generated, including the service endpoint interface and implementations, the generated service interface and the ibm-webservicesclient-bnd.xmi and ibm-webservicesclient-ext.xmi deployment descriptors.
  3. Complete the client implementation. Write your client application code that is used to invoke the Web service.

    New or updated for this feature pack The Feature Pack for Web Services provides Samples that demonstrate JAX-WS-based Web services using many of the new functions and standards supported in this Feature Pack. The Samples demonstrate the simple message exchange patterns using both synchronous and asynchronous invocation of Web services in SOAP 1.1 and SOAP 1.2 environments. The samples demonstrate the use of JavaBeans artifacts and static service endpoints and proxy-based clients. To learn more about these Samples, see the Samples readme located in the app_server_root/samples/lib/WebServicesSamples directory. Refer to the topic on installing the Samples using the administration console to learn how to install these Samples onto an application server that has been augmented with a Web services profile.

    You can review the JAX-RPC-based Web services sample, GetQuote client, in the WebServicesSamples application that is available in the Samples Gallery.

  4. (Optional) Assemble a Web services-enabled client Java archive (JAR) file into an enterprise archive (EAR) file. Complete this step if you are developing an unmanaged JAX-WS Web services client that runs in the J2EE client container or a managed JAX-RPC Web services client that runs in the J2EE client container.
  5. (Optional) Assemble a Web services-enabled client Web archive (WAR) file into an enterprise archive (EAR) file. Complete this step if you are developing an unmanaged JAX-WS Web services client that runs in the J2EE client container or a managed JAX-RPC Web services client that runs in the J2EE client container.
  6. (Optional) Configure the client deployment descriptor (JAX-RPC applications only). Complete this step if you are developing a managed JAX-RPC client.
  7. (Optional) Configure the ibm-webservicesclient-bnd.xmi deployment descriptor. (JAX-RPC applications only) Complete this step if you are deploying a managed JAX-RPC client that runs in the J2EE client container and you want to override the default client settings. See ibm-webservicesclient-bnd.xmi assembly properties for more information about the ibm-webservicesclient-bnd.xmi deployment descriptor.
  8. (Optional) Deploy the Web services client application. Complete this step to deploy an unmanaged JAX-WS Web services client that runs in the J2EE client container or a managed JAX-RPC Web services client that runs in the J2EE client container.
  9. Test the Web services-enabled client application. You can test an unmanaged client JAR file or a managed client application.

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.




In this information ...


Related concepts
New or updated for this feature pack JAX-WS

IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 31, 2013 1:23:07 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist&topic=twbs_devwbsclient
File name: twbs_devwbsclient.html