WAS v8.5 > End-to-end paths > Web services

Implement static JAX-WS web services clients

We can develop static web services clients based on the Web Services for Java EE specification and the JAX-WS programming model.


Develop web services clients based on JAX-WS

Web services clients that can both access and invoke JAX-WS web services are developed based on the Web Services for Java EE specification. The application server supports EJB clients, Java EE application clients, JSP files and servlets that are based on JAX-WS. Web services clients based on the JAX-RPC specification can invoke JAX-WS based web services if the WSDL file complies with the 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 dynamic proxy client invokes a web service based on a service endpoint interface (SEI) provided. The JAX-WS dynamic proxy instances leverage the dynamic proxy function in the base Java SE Runtime Environment (JRE) 6. You must begin with a WSDL file if you are developing a static client.

In contrast, the Dispatch client API, javax.xml.ws.Dispatch, is an XML messaging-oriented client 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. We do not need a WSDL file if you are developing a dynamic client.

To develop web services clients based on JAX-WS, you must determine the client model that best suits the needs of the web service application. If we 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. However, 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. Read about implementing dynamic JAX-WS web services clients to learn how to develop dynamic web services clients.

Complete this task 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 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 clients

The application server supports both managed and unmanaged web services clients when using JAX-WS

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 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 JSP, or a session EJB. Web services managed clients use JSR 109 APIs and deployment information to look up and invoke a web service.

For the managed clients, we can use JNDI look up to perform service lookup, or we 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();

We 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. We can use these annotations instead of declaring service-ref entries in the client deployment descriptor. We can still use the client deployment descriptor to declare JAX-WS managed clients, similar to JAX-RPC managed clients. We 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. We 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: 

@WebServiceRef(name=”service/FredsBankPort”, value=FredsBankService.class)
FredsBank fredsBank;
Now within the class, the fredsBank field does not have to be initialized. We can use this field directly: 
long balance = fredsBank.getBalance();

We 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. We can use this field directly:

In addition to the @WebServiceRef annotation, we 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, we can now use the service field without instantiation; for example:

We 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, we can use the dmgr console to supply the endpoint URL the client uses. This specified URL overrides the endpoint URL in the WSDL document used by the client. To learn more about specifying this endpoint URL, see the configuring web services client bindings documentation.


Unmanaged clients

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 using JAX-WS APIs. These clients are packaged as JAR files, which do not contain any deployment information.

Starting with WebSphere Application Server v7.0 and later, Java EE 5 application modules (web application modules version 2.5 or above, or EJB modules version 3.0 or above) are scanned for annotations to identify JAX-WS services and clients.

However, pre-Java EE 5 application modules (web application modules version 2.4 or before, or EJB modules version 2.1 or before) are not scanned for JAX-WS annotations, by default, for performance considerations.

In the v6.1 Feature Pack for Web Services, the default behavior is to scan pre-Java EE 5 web application modules to identify JAX-WS services and to scan pre-Java EE 5 web application modules and EJB modules for service clients during application installation. Because the default behavior for WAS v7.0 and later is to not scan pre-Java EE 5 modules for annotations during application installation or server startup, to preserve backward compatability with the feature pack from previous releases, configure either the UseWSFEP61ScanPolicy property in...

...of a WAR file or EJB module or define the Java virtual machine custom property, com.ibm.websphere.webservices.UseWSFEP61ScanPolicy, on servers to request scanning during application installation and server startup.


Procedure

  1. Obtain the WSDL document for the web service to access.

    We can locate the WSDL from the services provider through email, through a URL, or by looking it up in a UDDI registry.

  2. Develop JAX-WS client artifacts from a WSDL file

    1. For static JAX-WS web services applications using the dynamic proxy API, develop client artifacts from a WSDL file using the wsimport command.

    2. (optional) Develop JAX-WS client-side deployment descriptors. We can optionally use the application-client.xml, web.xml, or ejb-jar.xml client-side deployment descriptors to augment or override binding information contained in annotations for JAX-WS web services.

  3. Complete the client implementation

    Write the client application code that is going to be used to invoke the Web service.

    See Chapter 4 of the JSR 109 specification.

    • If wer client application is going to be installed in a server, it must be contained in either a WAR module or an EJB module. Shared library files are not scanned for JAX-WS clients. Therefore, a shared library JAR file cannot be used as the container for a client application.

    • If wer client application creates a number of threads in the JSR 109 client, the metadata, including the WebSphere Application Server configuration, is not copied to the thread, and the Global Security Handler is not called.

  4. (Optional) Assemble a web services-enabled client JAR file into an EAR file

    Complete this step if you are developing a JAX-WS web services client that runs in the Java EE client container.

  5. (Optional) Assemble a web services-enabled client WAR file into an EAR file

    Complete this step if you are developing a JAX-WS web services client that runs in the Java EE web container.

  6. (Optional) Deploy the web services client application.

    Complete this step to deploy a JAX-WS web services client that runs in the Java EE client container.

  7. Test the web services-enabled client application.

    We can test an unmanaged client JAR file or a managed client application.


Results

You have created and tested a web services client application.

After you develop a web services application client, and the client is statically bound, the service endpoint used by the implementation is the one identified in the WSDL file that we 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, we can change the endpoint with the dmgr console or the wsadmin scripting tool. For unmanaged JAX-WS web services clients, we can change the endpoint from within the client application.

We can additionally consider customizing the web services by implementing extensions to the web services client. Some examples of these extensions include sending and receiving values in SOAP headers or sending and receiving HTTP or JMS transport headers.


Related

JAX-WS client programming model
Web services
JAX-WS
Implement dynamic JAX-WS web services clients
Change SOAP message encoding to support WSI-Basic Profile
Testing web services-enabled clients
Configure web services client bindings
Set up a development environment for web services
Example: Installing a web services sample with the console
Implement web services applications with JAX-WS
Implement web services applications from existing WSDL files with JAX-WS
Tasks: Implementing web services applications
Configure secure transmission of SOAP messages using WS-Security
Web services client to web container optimized communication
JAX-WS annotations
Artifacts used to develop web services
Map between Java language, WSDL and XML for JAX-WS applications
Web services specifications and APIs
http://www.ibm.com/developerworks/websphere/techjournal/0604_singh/0604
http://www.ibm.com/developerworks/websphere/techjournal/0606_singh/0606
http://www.ibm.com/developerworks/websphere/techjournal/0607_desprets/06


+

Search Tips   |   Advanced Search