Async HelloWorld Web Service Sample

Table of Contents

Overview

Affiliates Icon

This sample has three installables, the client helloworld-ws-client-asynch.war and two services the helloworld-ws-asynchclient.jar and the helloworld-ws-asynch.jar. The client using a JSP obtains an SCA composite context and invokes the HelloWorldRemotable service over a SCA default binding. This component then invokes the AsynchTranslatorService service over a Web Services binding. Once the AsynchTranslatorService is invoked, it does a callback back to its client. The original client JSP waits for 5 seconds for the callback to complete and then calls the HelloWorldRemotable service again to get and display the callback result. If the callback fails the client displays a failure message. The client JSP programmatically creates a reference to the HelloWorldRemotable service which is packaged in the helloworld-ws-asynchclient.jar. This HelloWorldRemotable service has a reference to the AsynchTranslatorService service which is packaged in the helloworld-ws-asynch.jar. An SCA service exposed over the Web Services binding is always packaged as a jar. An SCA reference can be packaged in a jar or a war. An SCA reference that implements a callback over the Web Services binding must be packaged in a jar. Callback references using the Web Services binding are exported as a service.

This sample is based upon the helloworldws-async and helloworldwsclient-async samples contained within Tuscany.

Architectural Diagram

Prerequisites

  • This sample application requires that you have the WebSphere Application Server installed.
  • NOTE: This document will reference the location that these samples have been extracted to as <SCA_SAMPLE_HOME>.

Limitations

The README at the level of all the SCA samples contains the statement:

This environment provides the ability to build, package, and install SCA sample applications in a single server configuration.

This means that the deployment target for the applications comprising this sample should be a single server, not a cluster. Furthermore, on the z/OS platform, the target server should be configured to limit the number of servant JVMs to a single one.

Otherwise the instance of the component receiving the callback may not turn out to be the same component instance receiving the invocations of either of the getHello(name) or getmsg() calls from the front-end JSP. This could cause the getmsg() call made by the front-end JSP to return unexpected results.

The annotation @Scope("COMPOSITE") does result in the SCA runtime creating only a single component instance per-JVM. However, the SCA runtime does not guarantee which JVM hosting this component will receive the callback. It does not guarantee that the JVM hosting the component instance the callback goes to will be the same one as the JVM hosting the component instance that the forward call(s) from the front-end JSP are made upon.

Build

Build Icon

Compile and build the installable artifacts using the provided ANT build script.

  1. Open a command window and change to the <SCA_SAMPLE_HOME>\helloworld-ws-asynch directory.
  2. Issue the following command to build the artifacts: {WAS_HOME}\profiles\{PROFILE_NAME}\bin\ws_ant
    Example command: C:\WebSphere\AppServer\profiles\AppSrv01\bin\ws_ant
  3. Verify that the build completes without error and the following atrifacts have been created in <SCA_SAMPLE_HOME>\helloworld-ws-asynch\target

    helloworld-ws-client-asynch.war
    helloworld-ws-asynchclient.jar
    helloworld-ws-asynch.jar

Install

Install Icon

Start WebSphere Application Server.

Automated install: To quickly and easily install this sample and bypass the manual steps following, you can use the automated install. Run the following command from the Hello World Async sample directory:

<WAS_HOME>\profiles\<PROFILE_NAME>\bin\ws_ant install
<WAS_HOME>\profiles\<PROFILE_NAME>\bin\ws_ant start
NOTE: If the default port number for SOAP is not 8880 for your application server profile, please update the SOAP port number value in <SCA_SAMPLE_HOME>\common\manage-app.xml to match your profile.

Manual install

Install the Async Hello World client application from the Administrative Console

From the left navigation panel of the Administrative console, expand Applications and select New Application. Then select New Enterprise Application.

On the install panel, specify the Local file system option and enter the Full path or use the browse button to select the helloworld-ws-client-asynch.war file located in the <SCA_SAMPLE_HOME>/helloworld-ws-asynch/target/ directory. Click Next, and then Continue until you reach the "Map context roots for Web modules" page.

Since the sample application is a WAR file, you need to specify the context root of the Web module in the WAR file. Specify the Context root as helloWorldAsync.

Select the Next button at the bottom of the panel.

For the remaining install panels, select the defaults by clicking Next until you reach the final panel. Click Finish to complete the installation of the sample application.

Verify in the admin console that the application has installed successfully.

Once the application is installed, save the changes by clicking on the Save link. The application will appear in the list of applications and its initial status will be stopped (Status of Red).

Expand Applications then Application Types and select WebSphere enterprise applications. Check the box next to helloworld-ws-client-asynch_war and press Start.

Verify that the application has started. The application status for the helloworld-ws-client-asynch_war should show a green arrow.

Install and start the helloworld-ws-asynchclient.jar through the command line using the wsadmin BLA commands. First open a command window and issue the following command

<WAS_HOME>\profiles\<PROFILE_NAME>\bin\wsadmin

Example command:

C:\WebSphere\AppServer\profiles\AppSrv01\bin\wsadmin

Once wsadmin starts, issue the following commands:

$AdminTask createEmptyBLA {-name myhelloWorldClient}
$AdminTask importAsset {-source <SCA_SAMPLE_HOME>\helloworld-ws-asynch\target\helloworld-ws-asynchclient.jar -storageType FULL}
$AdminTask addCompUnit {-blaID myhelloWorldClient -cuSourceID helloworld-ws-asynchclient.jar}
$AdminConfig save
$AdminTask startBLA {-blaID myhelloWorldClient}

You can replace the "myhelloWorldClient" with any name of your choice.

Install and start the helloworld-ws-asynch.jar through the command line using the wsadmin BLA commands. The required commands are:

$AdminTask createEmptyBLA {-name myhelloWorld}
$AdminTask importAsset {-source <SCA_SAMPLE_HOME>\helloworld-ws-asynch\target\helloworld-ws-asynch.jar -storageType FULL}
$AdminTask addCompUnit {-blaID myhelloWorld -cuSourceID helloworld-ws-asynch.jar}
$AdminConfig save
$AdminTask startBLA {-blaID myhelloWorld}

You can replace the "myhelloWorld" with any name of your choice.

Note: You can optionally choose to install these through the administration console.

Running

Run Icon

Using a web browser open http://host:port/contextRoot for example: http://localhost:9080/helloWorldAsync

Specific to your environment:

  • host: Hostname where the server is located
  • port: Port for WebSphere application server host
  • contextRoot: Context root which you installed helloworld-ws-client-asynch.war

Uninstall

Uninstall Icon

Automated uninstall: To quickly and easily uninstall this sample and bypass the manual steps following, you can use the automated uninstall. Run the following command from the Hello World WS sample directory:

<WAS_HOME>\profiles\<PROFILE_NAME>\bin\ws_ant uninstall

Manual uninstall

To uninstall the SCA service (jar's)

Uninstall the helloworld-ws-asynchclient.jar and helloworld-ws-asynch.jar files through the command line using the wsadmin BLA commands. First open a command window and issue the following command:

<WAS_HOME>\profiles\<PROFILE_NAME>\bin\wsadmin

Example command:

C:\WebSphere\AppServer\profiles\AppSrv01\bin\wsadmin

Once wsadmin starts, issue the following commands:

$AdminTask stopBLA {-blaID myhelloWorldClient}
$AdminTask deleteCompUnit {-blaID myhelloWorldClient -cuID helloworldwsclient}
$AdminTask deleteAsset {-assetID helloworld-ws-asynchclient.jar}
$AdminTask deleteBLA {-blaID myhelloWorldClient}
$AdminTask stopBLA {-blaID myhelloWorld}
$AdminTask deleteCompUnit {-blaID myhelloWorld -cuID helloworldws}
$AdminTask deleteAsset {-assetID helloworld-ws-asynch.jar}
$AdminTask deleteBLA {-blaID myhelloWorld}
$AdminConfig save

Note: you can optionally choose to uninstall these through the administration console.

To uninstall the SCA client (war)

From the left navigation panel of the Administrative console, expand Applications then Application Types and select WebSphere enterprise applications. Select helloworld-ws-client-asynch_war and click on Uninstall. After the client application has been removed click on the Save link at the top of the screen.

User's Guide

When you run the sample you should see a page that looks like this:

Screenshot of helloworld application with name input

When you press the submit button the browser will perform an asynchronous call and display the resulting message to confirm that the call completed successfully:

Screenshot of helloworld application with callback response