WebSphere software logo IBM Logo

JAX-WS Web Services Samples

These samples demonstrate JAX-WS web services. The samples show the basic implementation of one-way and two-way web services. Included in each sample is a servlet that exercises the service using a browser, and a sample using the Thin Client for JAX-WS with WebSphere Application Server that you can run from a command line.

Time required to set up and configure this sample

Approximately 15 minutes

Prerequisites for use

  1. WebSphere Application Server. This sample was tested most recently with Version 8.5 of the product.
  2. Stand-alone thin client. When installing WebSphere Application Server, be sure to include this optional feature. If you are using an existing installation that does not include the thin client, use IBM Installation Manager to modify the installation to include the thin client before proceeding.

Copyright license

COPYRIGHT LICENSE: This information contains sample code provided in source code form. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample code is written. Notwithstanding anything to the contrary, IBM PROVIDES THE SAMPLE SOURCE CODE ON AN "AS IS" BASIS AND IBM DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND ANY WARRANTY OR CONDITION OF NON-INFRINGEMENT. IBM SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR OPERATION OF THE SAMPLE SOURCE CODE. IBM HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS TO THE SAMPLE SOURCE CODE.

About this task

The following key phrases are associated with this sample: "web service", "JAX-WS"

The following overview includes usage scenarios that are associated with this sample.
Ping and Echo sample

The Ping and Echo sample illustrates simple JAX-WS services. The Ping sample demonstrates a one-way service transaction. A simple text string is sent from the service client to the service endpoint. The Echo sample demonstrates a two-way service transaction. A simple text string is sent from the service client to the service endpoint. The service prepends an identifier and returns the string to the client. The Echo sample also demonstrates the use of the synchronous programming model and the use of two modes of the asynchronous programming model.

You can choose either SOAP 1.1 or SOAP 1.2 as the transport option for the Ping and Echo samples.

The Ping and Echo sample uses many of the Java Platform, Enterprise Edition (Java EE) and WebSphere Application Server functions, including servlets and JavaServer Pages (JSP) technology.

MTOM sample

The MTOM sample illustrates the use of the SOAP Message Transmission Optimization Mechanism (MTOM) on the transport to send and receive binary files. SOAP bindings use the MTOM feature to optimize the transmission or format of how a SOAP message appears on the wire. The MTOM function selects and encodes portions of the SOAP message, and presents an XML Infoset to the SOAP application. Then, a file with the encoded binary data is sent from the service client to the service endpoint.

The MTOM sample uses many of the Java Platform, Enterprise Edition (Java EE) and WebSphere Application Server functions, including servlets and JavaServer Pages (JSP) technology.

Getting Started

To learn more about Java API for XML web Services (JAX-WS) web services, see the web Services documentation in the WebSphere Application Server Information Center.

The JAX-WS web Services Ping and Echo sample demonstrates simple message exchange patterns (MEP) using both a synchronous and asynchronous programming model. This sample supports both SOAP 1.1 and SOAP 1.2 and incorporates web services standards such as WS-Addressing (WS-A), WS-Reliable Messaging (WS-RM), and WS-Secure Conversation (WS-SC). Using this web Service sample, you can complete a broad range of interoperability tests. The sample demonstrates the use of static JAX-WS service endpoints, as well as dispatch and proxy-based clients.

For more information, see the WebSphere Application Server Beta Information Center.

Locating the source code
You can find the source code for the Ping and Echo client sample in subdirectories of the JaxWSServicesSamples/src/ directory. The subdirectory, SampleClientSei/src, contains the source code for the following client samples:
  • Ping and Echo application
  • Simple servlet client
  • Ping and Echo thin client
The message exchange patterns for the samples are described in the following section.
One-way request: Ping

The one-way request scenario demonstrates a one-way message exchange pattern to send a ping application message from a client to a service.

Two-way request and response: Sync Echo

The two-way request and response scenario demonstrates a two-way message exchange pattern to send an application message from a client to a service and receives an echo string response from the server on the same request and response channel.

Two-way request and response: Asynchronous Echo with Sync Communication

The two-way asynchronous request and response scenario demonstrates a two-way message exchange pattern that sends an echo string message from a client to a service and expects the echo string response from the server on the same request and response channel. Although this message exchange pattern is similar to the Sync Echo sample, this sample implements the JAX-WS asynchronous programming model. In this scenario, a request is made; however, the application can continue to do additional work. When a response is received, a callback handler routine is used to process the response. Over the wire, this sample is identical to the Sync Echo sample.

Two-way request and response: Asynchronous Echo with Async Communication

The two-way asynchronous request and response with asynchronous communication scenario demonstrates a two-way message exchange pattern to send an echo string message from a client to a service. The client expects the echo string response from the server on a different request and response channel. This sample implements the JAX-WS asynchronous programming model. In this scenario, a request is made to the service but the client application can continue to do additional work. When a response is received, a callback handler routine is then used to process the response. The client listens on separate channel to receive the response messages from a server initiated channel.

Procedure


Build the JaxWSServicesSamples application

  1. Identify the directory structure of the JaxWSServicesSamples samples.

    You do not have to build the JaxWSServicesSamples samples before using them. The following steps describe how to rebuild the JaxWSServicesSamples samples, with additional information for modifications.

    The JaxWSServicesSamples samples are located in the following compressed file directories:

    Table 1. JaxWSServicesSamples Compressed File Directory Structure
    Directory Description
    jaxWSServicesSamples/src/ Contains the sample source code for the Ping, Echo and MTOM samples.
    JaxWSServicesSamples/installableApps/ Contains the Java archive (JAR) files, and the JaxWSServicesSamples.ear file for samples. This directory is not modified if this sample is rebuilt.
    JaxWSServicesSamples/lib/ Contains the web archive (WAR) files, the Java archive (JAR) files, and the final JaxWSServicesSamples.ear file for samples. This directory is created when this sample is rebuilt.
    JaxWSServicesSamples/javadoc/ Contains the samples Javadoc documentation. This directory is updated when this sample is rebuilt.
    JaxWSServicesSamples/bld/ Contains the generated class files. These class files are used to generate the final JaxWSServicesSamples.ear file. This directory is created when this sample is rebuilt.
  2. Run the samples build script.

    To rebuild the JAX-WS WebServices sample EAR file, complete the following steps:

    1. Set the WAS_HOME environment variable to point to your WebSphere Application Server install directory.
      • Locate the WebSphere Application Server directory.
      • On UNIX operating systems, issue the command: 
        export WAS_HOME=directory
      • On Windows operating systems, issue the command: 
        set WAS_HOME=directory
      In each of these, replace 'directory' with the value for your WebSphere installation. For example, 
      export WAS_HOME=/opt/IBM/WebSphere/AppServer
    2. Change to the JaxWSServicesSamples directory where you extracted the sample. This directory contains build.xml which is used to build the sample.
    3. Run the samples build script.
      • On UNIX operating systems, run the following command: 
        scripts/buildsamples.sh
      • On Windows operating systems, run run the following command: 
        scripts\buildsamples.bat
    The sample is now built.

    The buildsamples scripts are located in the JaxWSServicesSamples/scripts directory. The scripts set the appropriate class path information and run the Ant build utility. The Ant utility reads the build.xml files, which describe how to build the samples. Refer to the Apache Ant web site for additional documentation on the Ant utility.

  3. Install and remove the JaxWSServicesSamples.ear file.
    • Located in the JaxWSServicesSamples/scripts directory is a file called install.jacl. Use wsdamin to install the sample as follows: 
      \WebSphere\AppServer70\bin\wsadmin.bat -conntype none -f	samplesMaster.jacl -command install -samples JaxWSServicesSamples
    • Scripts are provided in the operating-system specific directories:
      • installear: Available both as a Windows installear.bat file and as a UNIX installear.sh file. If you are using the default node and cell, no options are required.
      • uninstallear: Available both as a Windows uninstallear.bat file and as a UNIX uninstallear.sh file. If you are using the default node and cell, no options are required.

    4. Web Services Message Patterns

    The Ping and Echo samples are two simple JAX-WS web services.

    The Ping sample demonstrates a one-way operation. A simple string value is passed to the service. The client operation is complete after it has contacted the service. Two endpoints exist in the sample. One endpoint uses SOAP 1.1 and the other endpoint uses SOAP 1.2.

    The Echo sample demonstrates a two-way operation. A simple string value is passed to the service. The service prepends an identifier string value and returns this value back to the client. There are two endpoints in the sample. One endpoint uses SOAP 1.1 and the other endpoint uses SOAP 1.2. The Echo sample also demonstrates the synchronous and asynchronous programming models, as well as synchronous and asynchronous over-the-wire behavior.

    • Synchronous: The client waits for the service response.
    • Asynchronous with synchronous communication: The service client does not wait for the service response. A callback method is provided. When the service responds, the callback method is called to handle the response string. However, the communication on the wire is still synchronous.
    • Asynchronous with asynchronous communication: The service client does not wait for the service response. A callback method is provided. When the service responds, the callback method is called to handle the response string. The service contacts the client on a channel that is different from the channel that was used by the client to contact the service.
    Table 2. JaxWSServicesSamples Enpoints
    Sample service endpoints URI Description
    http://localhost:9080/WSSampleSei/PingService Ping service sample using SOAP 1.1
    http://localhost:9080/WSSampleSei/EchoService Ping service sample using SOAP 1.1
    http://localhost:9080/WSSampleSei/PingService12 Ping service sample using SOAP 1.2
    http://localhost:9080/WSSampleSei/EchoService12 Ping service sample using SOAP 1.2
    Note: Port 9080 is the default value; however, the port number is different if you install to a profile other than the AppSrv01 profile.

    Running the Ping and Echo sample

    Before you begin, you must verify that the application server is running before you start the clients.

    The Ping and Echo sample includes two services, Ping and Echo.

    The Ping sample demonstrates a one-way service transaction. The source for this sample is located in the JaxWSServicesSamples/src/SampleClientSei directory.

    The Echo sample demonstrates a two-way service transaction. The source for this sample is located in the JaxWSServicesSamples/src/SampleClientSei directory.

    To run the Ping and Echo client servlet from WebSphere Application Server, complete the following steps:

    1. Start the server.
    2. Point your browser at the client interface; for example, http://localhost:9080/wssamplesei/demo

    The Ping and Echo thin client sample is similar to the Ping and Echo client servlet. This sample accesses the same Ping and Echo web services beans, but it uses a Java archive (JAR) file that requires the Thin Client for JAX-WS with WebSphere Application JAR file in the class path.

    The WSSampleClientSei.jar file is located in the following directory: 
    JaxWSServicesSamples/lib/

    The Ping and Echo thin client sample creates a JAX-WS proxy for the Ping or Echo web service based on the parameters that you provide. The proxy then contacts the service endpoint with the message. The Echo sample waits for the response.

    In the following steps, the variable, app_server_root, refers to the application server installation root.

    To run the Ping and Echo thin client from a WebSphere Application Server, complete the following steps, based on your operating system:

    1. Start the server.
    2. Open a command prompt.
    3. Set the WAS_HOME environment variable. On Windows operating systems: 
      set WAS_HOME=c:\WebSphere\AppServer
      On operating systems such as AIX, Linux, and z/OS: 
      export WAS_HOME=/opt/IBM/WebSphere/AppServer
    4. Go to the JaxWSServicesSamples directory. On Windows operating systems: 
      cd JaxWSServicesSamples\scripts\windows
      On operating systems such as AIX and Linux: 
      cd JaxWSServicesSamples/scripts/unix
    5. Run the Ping and Echo thin client sample. On Windows operating systems: 
      runSampleSei.bat -h hostname -p port -f urlSuffix -m testMessage -s service -t timeout -w asyncwire -c count -1 -2
      On operating systems such as AIX, Linux, and z/OS: 
      ./runSampleSei.sh -h hostname -p port -f urlSuffix -m testMessage -s service -t timeout -w asyncwire -c count -1 -2
      On iSeries operating systems: 
      ./runSampleSei -h hostname -p port -f urlsuffix -m testMessage -s service -t timeout -w asyncwire -c count -1 -2
    The parameters are:
    Table 3. runSampleSei Options
    Option Description
    -h <hostname> Specifies the name of the host. The default is localhost.
    -p <port> Specifies the port number. The default value is 9080.
    -f <urlsuffix> Specifies the service endpoint context. The default is 
    /WSSampleSei/EchoService
    -m <message> Specifies the text of the message. The default is hello. If the message contains blanks, use quotation marks around the message.
    -c count Specifies the number of transactions to run. The default is 1.
    -1 Specifies to use SOAP 1.1. The default is SOAP 1.1.
    -2 Specifies to use SOAP 1.2.
    The following example illustrates a successful run of the Ping and Echo client on the Windows operating system: 
    runSampleSei.bat -p 9081
Jan 12, 2011 7:01:00 PM com.ibm.ws.ssl.config.SSLConfigManager
INFO: ssl.disable.url.hostname.verification.CWPKI0027I
>> CLIENT: SEI Async to http://localhost:9081/WSSampleSei/EchoService
[WAShttpAsyncResponseListener] listening on port 4733
>> CLIENT: SEI Async invocation complete.
>> CLIENT: SEI Async response is: JAX-WS==>>HELLO
    To learn more about how the sample client and application work, see the Ping and Echo technotes or view the Java source code.

    For more information about web services clients, see the documentation on developing and deploying web services clients in the WebSphere Application Server Information Center.

    Enabling Reliable Messaging & Security

    Policy set scripts
    Policy sets are used to enable quality of service (QoS) such as ReliableMessaging and SecureConversation. Policy sets that are attached to an application define the quality of service for that application. A set of scripts are provided to enable the policy sets for WS-ReliableMessaging (WS-RM), WS-SecureConversation (WS-SC) and WS-I Reliable Secure Profile (RSP). RSP is a composition of both WS-RM and WS-SC. These scripts are provided as examples. You can also enable Policy sets using the administrative console. These scripts are designed to work with the sample applications only. The following tables describe the Policy set sample scripts.

    Table 4. Scripts for the Windows operating system
    Filename Description
    enableRMQoS.bat Enable WS-ReliableMessaging Version 1.1
    enableRM1QoS.bat Enable WS-ReliableMessaging Version 1.0
    enableSCQoS.bat Enable WS-SecureConversation
    enableRSPQoS.bat Enable WS-ReliableMessaging and WS-SecureConversation
    enableWSAQoS.bat Enable WS-Addressing
    disableRMQoS.bat Disable WS-ReliableMessaging Version 1.1
    disableRM1QoS.bat Disable WS-ReliableMessaging Version 1.0
    disableSCQoS.bat Disable WS-SecureConversation
    disableRSPQoS.bat Disable WS-ReliableMessaging and WS-SecureConversation
    disableWSAQoS.bat Disable WS-Addressing
    Table 5. Scripts for operating systems such as AIX, Linux, and z/OS
    Filename Description
    enableRMQoS.sh Enable WS-ReliableMessaging Version 1.1
    enableRM1QoS.sh Enable WS-ReliableMessaging Version 1.0
    enableSCQoS.sh Enable WS-SecureConversation
    enableRSPQoS.sh Enable WS-ReliableMessaging and WS-SecureConversation
    enableWSAQoS.sh Enable WS-Addressing
    disableRMQoS.sh Disable WS-ReliableMessaging Version 1.1
    disableRM1QoS.sh Disable WS-ReliableMessaging Version 1.0
    disableSCQoS.sh Disable WS-SecureConversation
    disableRSPQoS.sh Disable WS-ReliableMessaging and WS-SecureConversation
    disableWSAQoS.sh Disable WS-Addressing
    Table 6. Scripts for the i5/OS operating system
    Filename Description
    enableRMQoS Enable WS-ReliableMessaging Version 1.1
    enableRM1QoS Enable WS-ReliableMessaging Version 1.0
    enableSCQoS Enable WS-SecureConversation
    enableRSPQoS Enable WS-ReliableMessaging and WS-SecureConversation
    enableWSAQoS Enable WS-Addressing
    disableRMQoS Disable WS-ReliableMessaging Version 1.1
    disableRM1QoS Disable WS-ReliableMessaging Version 1.0
    disableSCQoS Disable WS-SecureConversation
    disableRSPQoS Disable WS-ReliableMessaging and WS-SecureConversation
    disableWSAQoS Disable WS-Addressing
    Use the following steps to run the reliable messaging scripts on the Windows operating system. You can run the all of the scripts in a similar manner based on your operating system.
    1. Open a command prompt using the Start menu: Click Start-> Run. Enter cmd.
    2. Change to the JaxWSServicesSamples/bin directory. For example: 
      cd C:\samples\JaxWSServiceSamples\bin
    3. Set the WAS_HOME environment variable. On Windows operating systems: 
      set WAS_HOME=c:\WebSphere\AppServer
      On operating systems such as AIX, Linux, and z/OS: 
      export WAS_HOME=/opt/IBM/WebSphere/AppServer
    4. Run the reliable messaging scripts.
      • To run the enable reliable messaging scripts, enter the command: 
        enableRMQos.bat
      • To run the disable reliable messaging scripts, enter the command: 
        disableRMQos.bat
    5. (Optional) Specify your profile, cell, node or server name when you run the reliable messaging or security scripts. The enable and disable scripts for reliable messaging and security have four optional parameters:
      • profile: application server profile
      • cell: application server cell
      • node: application server node
      • server: application server name
      6. The following example demonstrates how to run the Enable WS-ReliableMessaging script with the optional profile, cell, and node parameters specified: 
      enableRMQoS.bat AppSrv02 MyServerNode01Cell MyServerNode01
      The following example demonstrates how to run the Disable WS-ReliableMessaging script with the optional profile, cell, and node parameters specified: 
      disableRMQoS.bat AppSrv02 MyServerNode01Cell MyServerNode01
    6. Configure additional parameters on the command line as needed. If your server has administrative security enabled, then you must provide the user ID and password or the script fails, for example: 
      ./enableRMQoS.sh -user myuserid -password mypassword
    7. Ensure the sample applications start correctly. If you receive a warning message, the sample applications might have started incorrectly. Use the administrative console to stop and then restart the sample applications.

      8. To test the Ping and Echo thin client sample with the QoS policy sets, follow these guidelines.

      1. Apply the quality of service (QoS) that you want to test to the sample applications as indicated in the Policy Set Scripts section.
      2. Edit the runSampleSei script for your operating system.
      3. To add the WS-I RSP and SecureConversation policies, add the following statement to include the path to the Java Authentication and Authorization (JAAS) login file. On Windows operating systems: 
        set JAASLOGIN=-Djava.security.auth.login.config=<profile_root>/properties/wsjaas_client.conf
        On operating systems such as AIX, Linux, and z/OS: 
        export JAASLOGIN=-Djava.security.auth.login.config=<profile_root>/properties/wsjaas_client.conf
        The profile_root indicates the server directory where your profile is located, for example: 
        set JAASLOGIN=-Djava.security.auth.login.config=C:/IBM/WebSphere/profiles/AppSrv02/properties/wsjaas_client.conf
      4. Change the class path statement. On Windows operating systems: 
        set CLASSPATH=%THIN_JAR%;./WSSampleClientSei.jar;.
        On operating systems such as AIX, Linux, and z/OS: 
        export CLASSPATH=${THIN_JAR}:./WSSampleClientSei.jar:.
        Note: The period (.) is included at the end of the class path statement. The period is included so the policy set loading code finds the META-INF directory. Do not omit the period.
      5. Add <JAASLOGIN> and -DUSER_INSTALL_ROOT="<profile_root>" to the Java command. On Windows operating systems: 
        java %JAASLOGIN% -DUSER_INSTALL_ROOT= "<profile_root>" -cp "%CLASSPATH%" com.ibm.was.wssample.sei.cli.SampleClient %*
        On operating systems such as AIX, Linux, and z/OS: 
        java ${JAASLOGIN} -DUSER_INSTALL_ROOT="<profile_root>" -cp "${CLASSPATH} " com.ibm.was.wssample.sei.cli.SampleClient $@
      6. Create a directory named META-INF in the directory where the version of the script is located. For example 
        JaxWSServicesSamples/scripts/unix/META-INF
      7. Copy the PolicySets directory from the profile_root/config/cells/CELL_NAME/ directory to the META-INF directory.
      8. Copy the bindings subdirectory and the clientPolicyAttachment.xml file from the profile_root/config/cells/CELL_NAME/applications/JaxWSServicesSamples.ear/deployments/JaxWSServicesSamples/META-INF directory to the META-INF directory.
      9. Copy the entire bindings subdirectory and its contents; for example, SecureConversationClientBinding or RAMP_client_default_bindings.
      10. Change to the directory with the script and run the sample.

Results

The following illustration shows the correctly running Ping and Echo sample:

The running Ping and Echo sample



The following illustration shows the correctly running MTOM sample:

The running MTOM sample

Related tasks
Related information