Multi Service Sample

Table of Contents

Overview

Affiliates Icon

This sample shows service composition using existing services. The MultiService sample wires to several existing samples which include Stock Quote, Async Hello World, Job Bank Service, and EJB Counter. It demonstrates wiring to services over the default binding, web services binding, and the ejb binding for both ejb 2.x and ejb 3.x services. The MultiService sample exposes one business service over the default binding and the web service binding that returns a JAXB object. The Client JSP, packaged in a WAR file, utilizes this business service exposed over the default binding.

Architectural Diagram

Prerequisites

  • You must have chosen to install the sample applications as part of your WebSphere base install process in order for the appropriate base samples to be available. If you do not see the <SCA_SAMPLE_HOME>\installableApps\WebServicesSamples.ear file available please reinstall the base application server with the option to install the sample applications.
  • This sample requires application security to be enabled.

    1. From the left navigation panel expand Security and select Global Security. Check the box marked Enable Application security.
    2. Click Apply at the bottom of the panel and then click the Save link at the top of the screen.
    3. You must restart you server for this change to take effect.
  • NOTE: This document will reference the location that these samples have been extracted to as <SCA_SAMPLE_HOME>.

Install Stock Quote sample

  1. The Stock Quote sample is located in the WebServicesSamples.ear under the samples directory (<SCA_SAMPLE_HOME>\installableApps). You can either install this ear file as an enterprise application through the admin console.
    1. From the left navigation panel of the Administrative console, expand Applications and select New Application and then New Enterprise Application.
    2. On the install panel, specify the Local file system option and enter the Full path or use the browse button to select the WebServicesSamples.ear file located in the <SCA_SAMPLE_HOME>/installableApps/WebServicesSamples directory. Click Next.
    3. On the next panel expand the plus sign marked "Choose to generate default bindings and mappings" and check "Generate Default Bindings" and click Next, and then Continue on the next page.
    4. Continue to click Next until the summary page and click Finish.
    5. Click the Save link at the top of the screen.
  2. After saving your configuration return to the screen under Applications->Application Types->WebSphere enterprise applications. Select the check box next to WebServicesSamples and then click on Start.
  3. If you deployed the WebServicesSample.ear which includes the Stock Quote web service outside of the localhost or on a non default port you will need to modify the wsdl included in the MultiService sample. The wsdl file (StockQuoteFetcher.wsdl) is located in the jar under the <SCA_SAMPLE_HOME>\MultiService\src\main\resources\server\WEB-INF directory. You will need to modify the following line in the wsdl file to reflect the correct hostname and port.

    <wsdlsoap:address location="http://localhost:9080/StockQuote/services/xmltoday-delayed-quotes"/>

    Example:

    <wsdlsoap:address location="http://scafp.websphere.ibm.com:9081/StockQuote/services/xmltoday-delayed-quotes"/>

Install Hello World Async Sample

  1. The hello world asynch sample is included as part of the WebSphere. The source and installable binaries are located in the samples directory. Follow the instructions in the readme.html under <SCA_SAMPLE_HOME>/helloworld-ws-asynch to install this sample. You do not need to install the client war for this sample. However it may be useful to install the client war to verify the hello world service is properly deployed.
  2. After you have completed the install for the Hello World Async sample verify that you have started both BLA's associated with this sample.

    Note: You must deploy the HelloWorldAsync sample in the same SCA domain as you plan to deploy the MultiService sample application on.

Install Resume Bank EJB from Job Bank sample

Use the Administrative Console to deploy the JobBank EJB target application.

The JobBank sample is included as part of WebSphere and is used in this sample. You only install the JobbankTargetEJBApp.ear from the <SCA_SAMPLE_HOME>/installableApps directory as an enterprise application since the rest of the JobBanks sample is not needed for the purposes of this MultiService sample.

  1. From the left navigation panel of the Administrative console, expand Applications and select New Application and then New Enterprise Application
  2. On the install panel, specify the Local file system option and enter the Full path or use the browse button to select the JobbankTargetEJBApp.ear file located in the <SCA_SAMPLE_HOME>/installableApps/ directory. Click Next.
  3. On the next panel expand the plus sign marked "Choose to generate default bindings and mappings" and check "Generate Default Bindings" and click Next, and then Continue on the next page.
  4. Continue to click Next until the summary page and click Finish.
  5. Click the Save link at the top of the screen.
  6. After saving your configuration return to the screen under Applications->Application Types->WebSphere enterprise applications. Select the check box next to the JobBanktargetEJB application and the click on Start.
Note: If you are not deploying this sample in a single server environment you will need to update to update the URI in the reference based on your configuration. You will need to update this information in your MultiService composite file, <SCA_SAMPLE_HOME>\MultiService\src\main\resources\server\META-INF\sca-deployables\default.composite.
<reference name="extEJBService">
    <interface.java interface="com.app.resumebank.ResumeBank"/>
    <binding.ejb uri="cell/clusters/<cluster-name>/ejb/com/app/resumebank/ResumeBankHome"/>
</reference>

or

<reference name="extEJBService">
    <interface.java interface="com.app.resumebank.ResumeBank"/>
    <binding.ejb uri="cell/nodes/<node-name>/servers/<server-name>/ejb/com/app/resumebank/ResumeBankHome"/>
</reference>

Install EJB3 Counter Sample

Install the following ear file as an enterprise application: EJB3CounterSample.ear. The file is located in <SCA_SAMPLE_HOME>/installableApps.

  1. From the left navigation panel of the Administrative console, expand Applications and select New Application and then New Enterprise Application
  2. On the install panel, specify the Local file system option and enter the Full path or use the browse button to select the EJB3CounterSample.ear file located in the <SCA_SAMPLE_HOME>/installableApps/ directory. Click Next.
  3. On the next panel expand the plus sign marked "Choose to generate default bindings and mappings" and check "Generate Default Bindings" and click Next, and then Continue on the next page.
  4. Continue to click Next until the summary page and click Finish.
  5. Click the Save link at the top of the screen.
  6. After saving your configuration return to the screen under Applications->Application Types->WebSphere enterprise applications. Select the check box next to the EJB3CounterSample application and the click on Start.
Note: If you are not deploying this sample in a single server environment you will need to update to update the URI in the reference based on your configuration. You will need to update this information in your MultiService composite file, <SCA_SAMPLE_HOME>\MultiService\src\main\resources\server\META-INF\sca-deployables\default.composite.
<reference name="ejbCounterService">
    <interface.java interface="om.ibm.websphere.ejb3sample.counter.RemoteCounter"/>
    <binding.ejb uri="cell/clusters/<cluster-name>/ejb/EJB3CounterSample/EJB3Beans.jar/StatelessCounterBean#com.ibm.websphere.ejb3sample.counter.RemoteCounter"/>
</reference>

or

<reference name="ejbCounterService">
    <interface.java interface="om.ibm.websphere.ejb3sample.counter.RemoteCounter"/>
    <binding.ejb uri="cell/nodes/<node-name>/servers/<server-name>/ejb/EJB3CounterSample/EJB3Beans.jar/StatelessCounterBean#com.ibm.websphere.ejb3sample.counter.RemoteCounter"/>
</reference>

Limitations

There are no noteable design limitations specific to this sample.

Build

Build Icon

Included are two options to build and deploy the sample application. You can:

  1. Build from the command line
  2. Build from Rational Application Developer (RAD)

Build Using the Command Line

Note: Be sure to make any modification to the composite or WSDL files before building the MultiService application. Review the above steps to check if you have deployed any of your sample applications outside the localhost or on non default ports.
  1. Open a command window and change to the <SCA_SAMPLE_HOME>\MultiService directory.
  2. Issue the following command to build the application

    <WAS_HOME>\profiles\<PROFILE_NAME>\bin\ws_ant.bat

    Example command:

    C:\WebSphere\AppServer\profiles\AppSrv01\bin\ws_ant.bat
  3. Verify that the build completes without error.
  4. The output of the build command can be found under the <SCA_SAMPLE_HOME>\MultiService\target directory. Verify that the following artifacts have been generated by the build:

    • MultiService.jar
    • MultiService.war

Build Using RAD

Also included in the sample directory is MultiService Project Interchange file for Rational Application Developer (RAD). If you have IBM Rational Application Developer for WebSphere Software 7.5.2 and IBM Rational Application Developer Assembly and Deployment Features 7.5.2 installed, you can open this Project Interchange file in RAD to build and deploy the MultiService sample.

  1. Open the MultiService project in RAD.
    1. If Start Rational Application Developer, using a new Workspace. Navigate File > Import > Other > Project Interchange. Then click Next.
    2. Click Browse. Select the file located at <SCA_SAMPLE_HOME>/MultiService/RAD/MultiServiceSample.zip . Click Open.
    3. Click Select All and then click Finish.
    4. Close the "Welcome" pane by clicking the X on the Welcome pane tab.

Install

Install Icon

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 MultiService 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

Included are two options to build and deploy the sample application. You can:

  1. Install from the Websphere Administrative Console
  2. Install from Rational Application Developer (RAD)

Install Using the Websphere Administrative Console

SCA MultiService Sample Application

  1. Use the Administrative Console to import MultiService.jar

    Note: As is noted above, you will need to modify the default.composite file in this asset before importing it if all of your applications are not deployed on the localhost and default ports.
    1. Log into the Administrative Console by navigating to http://localhost:9060/admin in a Web browser.
    2. From the left navigation panel of the Administrative console, expand Applications then Application Types and select Assets.
    3. Press the Import button, then browse to <SCA_SAMPLE_HOME>\MultiService\target and select the MuliService.jar file. Click Next using all the default settings until you reach the summary page and click Finish.
    4. Click the Save link at the top of the screen.
  2. Go to Applications->Application Types->Business-level applications and create a New Business-level Application called "MultiServiceBLA". Under Deployed Assets, Add->Add Asset, and select the MultiService.jar. Complete the installation using all the default settings and save your configuration.
  3. Next Go return to Applications->Application Types->Business-level applications, and select the new BLA that you just created, MultiServiceBLA, and click Start.

SCA MultiService Sample Client JSP

  1. Log into the Administrative Console by navigating to http://localhost:9060/admin in a Web browser.
  2. Install the MultiService client application.
    1. If you have not already enabled application security, from the left navigation panel of the Administrative Console, expand Security->Global Security and check "Enable Application security". Click OK and then click the Save link at the top of the screen. You must restart your server for this change to take effect. After you server has been restarted log back into the Administrative Console.
    2. From the left navigation panel of the Administrative console, expand Applications and then select New Application and select New Enterprise Application.
    3. On the install panel, specify the Local file system option and enter the Full path or use the browse button to select the MultiService.war file located in the <SCA_SAMPLE_HOME>/MultiService/target/ directory. Click Next.
    4. Choose the radio button marked Detailed and then expand the plus sign marked "Choose to generate default bindings and mappings" and check "Generate Default Bindings" and click next, and then Continue on the next page.
    5. Since the sample application is a WAR file, you need to specify the context root of the Web module in the WAR file. Skip ahead to the step titled Map context root for web modules and specify the context root as multiService and click Next.
    6. On the next panel titled "Map security roles to users or groups" select the AllAuthenticatedUsers checkbox and then choose 'All Authenticated in Application's Realm' under 'Map Special Subjects' dropdown.
    7. Select the Next button at the bottom of the panel
    8. 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.
    9. Verify in the admin console that the MultiService client has installed successfully.
    10. 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 MultiService_war and press Start.
    11. Verify that the MultiService client application has started. The application status for the MultiService_war should show a green arrow.
  3. Using a web browser open http://host:port/contextroot for example: http://localhost:9080/multiService.
    1. You will be prompted for a name and a stock symbol. Fill in the name text field with any name, and enter a valid stock symbol in the stock field and click Submit.
    2. If all you applications are deployed correctly you will see a response page that returns the following information:

      Greeting: Callback: Hola SCA User
      Authenticated Greeting: Callback: Hola SCA User You are logged in as: defaultWIMFleBasedRealm/wsadmin
      Symbol: IBM Price: 128.66
      Request count: 23
      Request Confirmation number: 102983337

Install Using RAD

Also included in the sample directory is MultiService Project Interchange file for Rational Application Developer (RAD). If you have IBM Rational Application Developer for WebSphere Software 7.5.2 and IBM Rational Application Developer Assembly and Deployment Features 7.5.2 installed, you can open this Project Interchange file in RAD to build and deploy the MultiService sample.

  1. Check the Servers view. Ensure that the Servers view is visible. If necessary, create a server instance.
    1. Select Window > Show View > Other > Server > Servers. The Servers view is displayed.
    2. Right-click in the Servers view and select New > Server. The New Server wizard is displayed.
    3. For server type, choose a WebSphere Application Server instance. Depending on your setup, accept the defaults or modify the Server's host name and Server name values.
    4. Click Next. The WebSphere Server Settings dialog is displayed. Depending on your WebSphere Application Server setup, if necessary, modify the values. Ensure that the WebSphere profile you choose is augmented for Service Component Architecture. Profiles can be augmented with the WebSphere Application Server Profile Management Tool. Note that installing the Service Component Architecture feature pack creates an augmented profile.
    5. Click Next. The WebSphere Server Settings dialog is displayed. Depending on your WebSphere Application Server setup, if necessary, modify the values. Ensure that the WebSphere profile you choose is augmented for Service Component Architecture. Profiles can be augmented with the WebSphere Application Server Profile Management Tool. Note that installing the Service Component Architecture feature pack creates an augmented profile.
    6. Click Finish. The server is displayed in the Servers view.
  2. Add the MultiService projects to the server instance
    1. Right-click your server in the Servers view. Select Add and Remove Projects. The Add and Remove Projects screen is displayed.
    2. Right-click your server in the Servers view. Select Add and Remove Projects. The Add and Remove Projects screen is displayed.
    3. Click the Add All button to add the MultiServiceEAR and MultiServiceSample projects to server. Click Finish. This deploys the JSP and SCA Composite to the server.

Running

Run Icon

Using a web browser open http://host:port/contextroot for example: http://localhost:9080/multiService.

  1. You will be prompted for a name and a stock symbol. Fill in the name text field with any name, and enter a valid stock symbol in the stock field and click Submit.
  2. If all you applications are deployed correctly you will see a response page that returns the following information:
Greeting: Callback: Hola SCA User
Authenticated Greeting: Callback: Hola SCA User You are logged in as: defaultWIMFleBasedRealm/wsadmin
Symbol: IBM Price: 128.66
Request count: 23
Request Confirmation number: 102983337

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 MultiService sample directory:

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

Manual uninstall

  1. From the left navigation panel of the Administrative console, expand Applications then Application Types and select Business-level Applications. You should see one Multi Service related BLA on this page, MultiServiceBLA. Click on MultiServiceBLA. Under Deployed assets check all the non Shared Library assets and click delete. These assets are usually marked as "asset" under the Type column.
  2. After the non shared library assets are removed, select all the shared library assets that are left under Deployed assets and delete them. Once all the assets are removed, click on the Save link at the top of the screen.
  3. Expand Applications then Application Types and select Business-level Applications. Select the MultiServiceBLA and click on delete and then click the Save link at the top of the screen.
  4. Next you will need to uninstall the Multi Service client war. Expand Applications then Application Types and select WebSphere Enterprise Applications. Select MultiService_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 MultiService application with input fields

Fill in the name text field with any name, and enter a valid stock symbol in the stock field and click Submit. you will see a response page that returns the following information:

Greeting: Callback: Hola SCA User
Authenticated Greeting: Callback: Hola SCA User You are logged in as: defaultWIMFleBasedRealm/wsadmin
Symbol: IBM Price: 128.66
Request count: 23
Request Confirmation number: 102983337