Candy Store Sample

Table of Contents

Overview

This sample demonstrates the flexibility and agility of an SCA application as it is extended using SOA principles. The Candy Store sample swaps different implementations for components and exposes services over different bindings with minimal administration or configuration. This sample makes use of the default binding, web service binding, and the ejb binding and shows the use of the recursive model, and authentication and authorization over the default binding.

The CandyStore sample is a collection of composites which show the progression of a sample store application. The composites and implementations in the CandyStore.jar use a bottom up approach to development. The implementation classes in this jar are used throughout the sample and are exported and imported for reuse through contribution files. The first five composite files described below are meant to be deployed independently from all other composites and are ported from the Tuscany Fruit Store application. The other composite files are to be used in conjunction with the composites in the CandyStoreLooseSupplier.jar, CandyStoreRecursiveSupplier.jar, and the CandyStoreTopDown.jar which uses a top down development approach. Each composite shows some reuse of previous examples and builds upon them. Below is a short description of each composite and how they relate to each other:

The first five composites below are part of the CandyStore.jar.

  • store.composite (StoreComposite)
    The StoreComposite uses the default binding to wire together several components. This is the most basic composite in the sample. The Store component wires to a Candy Catalog and a Shopping Cart which holds the items that the user has chosen until checkout. The Catalog wires to a Currency Converter component to store and return the item prices in the correct currency.
  • store-merger.composite(StoreMergerComposite)
    The StoreMergerComposite builds on the previous composite by wiring to another Catalog component called FruitsCatalog over the Web Service binding. The Catalog implementation is now changed to merge the original Candy Catalog and the new Fruit Catalog. However, the catalog interface that is used by the store to get a list of items in the catalog is left unchanged.
  • store-db.composite (StoreDBComposite)
    The StoreDBComposite is nearly the same as the StoreMergerComposite except that now the ShoppingCart is backed by a Derby database. The implementation for the StoreShoppingCart component is changed to point to a new implementation, ShoppingCartTableImpl, which stores the item data in the database instead of a HashMap.
  • store-supplier.composite (StoreSupplierComposite)

    The StoreSupplierComposite shows how the Candy and Fruit stores can be merged together as in the StoreMergerComposite and be a supplier for other online stores. In this case the Catalog and ShoppingCart expose their services over the web service binding for other online stores to exploit. The shopping cart in this composite is implemented using a database backend. In the diagram below the client JSP is deployed in a WAR, and uses the SCA API to obtain a reference to the Store component and utilize the services it provides.

    Architectural Diagram 1
  • store-eu.composite (StoreEUComposite)
    The StoreEUComposite shows one can provide a store solution in another geography and changes the StoreCatalog to wire to Currency Converter, StoreCandyCatalog, and the FruitsCatalog over the Web Service binding. The catalog components also change the currencycode property to "EUR" to convert the item prices to the correct currency.

These second set of composites is in the CandyStoreLooseSupplier.jar.

  • store-supplier-catalog.composite (StoreSupplierCatalogComposite)
    The StoreSupplierCatalogComposite shows how the catalog related components in the candy store can be deployed in a separate composite. This allows the store catalog to be updated without stopping and redeploying the entire store application. Similar to the StoreSupplierComposite, the StoreSupplierCatalogComposite exposes the Catalog service over the web service binding.
  • store-supplier-catalog-sca.composite (StoreSupplierCatalogSCAComposite)
    This is not a deployable composite. It is called recursively from the StoreSupplierCatalogOuterComposite described below. The StoreSupplierCatalogSCAComposite is based on the previous catalog composite, however, we have removed the web service binding from the StoreSupplier catalog component.
  • store-supplier-secure-shoppingcart.composite (StoreSupplierSecureShoppingCartComposite)
    The StoreSupplierSecureShoppingCartComposite demonstrates the use of policy set attachments for authentication and authorization over the default binding and web service binding. It shows how personal information such as that contained in a customer's shopping cart can be secured.
  • store-supplier-shoppingcart.composite (StoreSupplierShoppingCartComposite)
    The StoreSupplierShoppingCartComposite shows how all the shopping cart related components in the candy store can be deployed in a separate composite. This allows the stores shopping cart to be updated independently from the rest of the application. The shopping cart is exposed over the default binding and web service binding.
  • store-supplier-store.composite (StoreSupplierStoreComposite)

    The StoreSupplierStoreComposite is based on the StoreSupplierComposite from the CandyStore.jar, however we have only included the StoreComponent in this composite. The other components referenced in this composite are to be stopped and started independently.

    The diagram below shows how the Store component wires to the components in the other composites. Each of the components below can be deployed and run independent of each other. This allows different components to be swapped out without restarting the entire application. The shopping cart in this scenario is implemented using a database backend. In the diagram below the client JSP is deployed in a WAR, and uses the SCA API to obtain a reference to the Store component and utilize the services it provides.

    Architectural Diagram 2
  • store-supplier-store-JPA.composite (StoreSupplierStoreJPAComposite)

    The StoreSupplierStoreJPAComposite is based on the previous composite, StoreSupplierStoreComposite. We have replaced the shopping cart reference to utilize the EJB binding. This composite requires that there is an EJB implementation of the shopping cart database deployed and running. We have provided this implementation in the CartEAR.ear.

The third set of composites are located in the CandyStoreRecursiveSupplier.jar. This jar reuses components from our previous jar such as the catalog and shopping cart.

  • store-supplier-catalog-inner.composite (StoreSupplierCatalogInnerComposite)

    The StoreSupplierCatalogInnerComposite is not a deployable composite. Instead it exists purely to demonstrate the use of the recursive model using "implementation.composite". This composite promotes the Catalog service over the web service binding.

  • store-supplier-catalog-outer.composite (StoreSupplierCatalogOuterComposite)

    The StoreSupplierCatalogOuterComposite shows the use of the recursive model in our sample. The StoreSupplierCatalog component within this composite uses "implementation.composite" to use the StoreSupplierCatalogSCAComposite as an implementation.

  • store-supplier-catalog-outer-autowire.composite (StoreSupplierCatalogOuterAutoWireComposite)

    The StoreSupplierCatalogOuterComposite shows the use of the recursive model in our sample. The StoreSupplierCatalog component within this composite uses "implementation.composite" to use the StoreSupplierCatalogInnerComposite as an implementation.

The following two composites are located in the CandyStoreTopDown.jar. The contents of this jar were developed starting from a WSDL document to demonstrate a top down approach.

  • store-supplier-topdown.composite (StoreSupplierTopDownComposite)

    The StoreSupplierTopDownComposite exposes the StoreService over the default binding and web service binding. The interfaces and JAXB objects exposed over these binding are all generated from WSDL.

  • store-supplier-JPA-topdown.composite (StoreSupplierJPATopDownComposite)

    The StoreSupplierJPATopDownComposite shows the use of the ejb binding to wire to a shopping cart implemented using EJB 3.0 and JPA. The rest of the composite is based on the StoreSupplierTopDownComposite.

    The diagram below shows how the Store component wires to the components in the other composites. Each of the components below can be deployed and run independent of each other. This allows different components to be swapped out without restarting the entire application. The shopping cart in this scenario is implemented using a EJB 3.0 stateless session bean, and the StoreService component wires to the EJB module over the EJB binding. In this scenario we are using an EJB and the Java Persistence API to handle any interactions with our database rather than in a direct implementation of an SCA component. In the diagram below the client JSP is deployed in a WAR, and uses the SCA API to obtain a reference to the Store component and utilize the services it provides.

    Architectural Diagram 3

A Note About This Sample

The CandyStore sample is not like a typical sample in which one simply installs an application and views the successful execution of the sample code. Instead, this sample is intended to walk the user through a series of processes (outlined above) to demonstrate how easy and seamless those processes are. As such, both this document and the time it will take to work through it entirely are lengthier than is typical.

It is recommended that the user follow this document step by step in order to better understand how an SCA application can evolve.

Prerequisites

  • This sample application requires that you have the WebSphere Application Server installed.
  • You must also have application security enabled to exercise all the functionality shown in this sample.
    1. Start your server.
    2. Log into the Administrative Console by navigating to http://localhost:9060/admin in a Web browser.
      NOTE: If the default Admin port is not 9060 for your application server profile, the URL above should include the port number for your installation.
    3. 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.
  • NOTE: This document will reference the location that these samples have been extracted to as <SCA_SAMPLE_HOME>.

Limitations

This sample limited to running with one client. If multiple clients try to shop at the same time they will interfere with each others shopping carts.

Build

CandyStore Application

Setup and compile the Candy Store Service application.

  1. Open a command window and change to the <SCA_SAMPLE_HOME>\CandyStore\candystoreservice directory.
  2. Issue the following command to build the application:
    <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.
  4. The output of the build command can be found under the <SCA_SAMPLE_HOME>\CandyStore\candystoreservice\target directory. Verify that the following artifacts have been generated by the build:
    <SCA_SAMPLE_HOME>\CandyStore\candystoreservice\target\classes (Location of .class files)
    <SCA_SAMPLE_HOME>\CandyStore\candystoreservice\target\generated (Location of generated Java source)
  5. Verify that the CandyStore.jar BLA module has been generated in the <SCA_SAMPLE_HOME>\CandyStore\candystoreservice\target\ directory.

CandyStoreLooseSupplier and CandyStoreRecursiveSupplier Applications

Setup and compile the Candy Store Service application. You will notice there are no java source files bundled in this portion of the sample because all the implementation classes are imported using the contribution.xml file.

  1. Before you build this application you may need to modify some of the source code to match the correct usernames for certain applications that you will be deploying.
  2. Part of this samples uses authentication and authorization over the default and web service bindings. In order for a user to access the Shopping Cart component in the example demonstrating SCA security, you must add a valid username to the ibm-application-bnd.xml file, located <SCA_SAMPLE_HOME>\CandyStore\candystoreloosesupplier\ src\main\resources\META-INF\. For the purposes of this sample you can add the user name that you use to log in to the Administrative Console.

    For example, to add user sca_user to role1 the ibm-application-bnd.xml should be modified as follows.

    <security-role name="role1">
    	<user name="wsadmin"/>
    	<user name="sca_user"/>
    </security-role>
  3. Part of this sample uses the ejb binding to wire to and EJB 3.0 application that is deployed from an EAR file. You must determine which host you plan on deploying this application to, and the bootstrap port of the server. The default host and port are localhost:2809. If you will be deploying the EJB 3.0 application to a different host or port you will need to modify the following file before building your application: <SCA_SAMPLE_HOME>\CandyStore\candystoreloosesupplier\src\main\resources\META-INF\store-supplier-store-JPA.composite.

    There are two lines in the above file which contain this line:

    <binding.ejb uri="corbaname:iiop:localhost:2809/NameServiceServerRoot#ejb/EJB3ShoppingCartEAR/EJB3ShoppingCart.jar/StatelessCartBean#soa.sca.samples.candystore.ejb3.RemoteCart"/>

    Replace the address and port with the address and port for you server. For example, if your hostname is http://myserver.ibm.com and your bootstrap port is 2811 the two references would look like the following:

    <reference name="shoppingCart">
    	<interface.java interface="soa.sca.samples.candystore.Cart" />
    	<binding.ejb uri="corbaname:iiop:http://myserver.ibm.com:2811/NameServiceServerRoot#ejb/EJB3ShoppingCartEAR/EJB3ShoppingCart.jar/StatelessCartBean#soa.sca.samples.candystore.ejb3.RemoteCart"/>
    </reference>
    <reference name="shoppingTotal">
    	<interface.java interface="soa.sca.samples.candystore.Total" />
    	<binding.ejb uri="corbaname:iiop:http://myserver.ibm.com:2811/NameServiceServerRoot#ejb/EJB3ShoppingCartEAR/EJB3ShoppingCart.jar/StatelessCartBean#soa.sca.samples.candystore.ejb3.RemoteCart"/>
    </reference>
  4. Open a command window and change to the <SCA_SAMPLE_HOME>\CandyStore\candystoreloosesupplier directory.
  5. Issue the following command to build the application

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

    Example command:

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

    Verify that the build completes without error.

  6. Verify that the CandyStoreLooseSupplier.jar BLA module has been generated in the <SCA_SAMPLE_HOME>\CandyStore\candystoreloosesupplier\target\ directory.
  7. Open a command window and change to the <SCA_SAMPLE_HOME>\CandyStore\candystorerecursivesupplier directory.
  8. Issue the following command to build the application

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

    Example command:

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

    Verify that the build completes without error.

  9. Verify that the CandyStoreReursiveSupplier.jar BLA module has been generated in the <SCA_SAMPLE_HOME>\CandyStore\candystorerecursivesupplier\target\ directory.

CandyStore Client Application

Build and package the CandyStore client application:

  1. Open a command window and change to the <SCA_SAMPLE_HOME>\CandyStore\candystoreclient directory.
  2. Issue the following command to build the application:

    <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.
  4. Verify that the output WAR file, CandyStore-client.war, is found under the <SCA_SAMPLE_HOME>\CandyStore\candystoreclient\target\ directory.

CandyStore Top Down Application

Generate the needed classes from the provided WSDL and compile the Candy Store Top Down application. This portion of the sample uses the wsimport ant task to generate Java classes from a WSDL document. The generated classes will include services, fault objects, and JAXB objects. The build.xml under <SCA_SAMPLE_HOME>\CandyStore\candystoreservice-topdown\build.xml shows how to use wsimport in a top down approach.

  1. Before you build this application you may need to modify some of the source code to match the correct hostnames and ports for certain applications that you will be deploying.
  2. Part of this sample uses the ejb binding to wire to and EJB 3.0 application that is deployed from an EAR file. You must determine which host you plan on deploying this application to, and the bootstrap port of the server. The default host and port are localhost:2809. If you will be deploying the EJB 3.0 application to a different host or port you will need to modify the following file before building your application: <SCA_SAMPLE_HOME>\CandyStore\candystoreservice-topdown\src\main\resources\META-INF\store-supplier-JPA-topdown.composite.

    There are two lines in the above file which contain this line:

    <binding.ejb uri="corbaname:iiop:localhost:2809/NameServiceServerRoot#ejb/EJB3ShoppingCartEAR/EJB3ShoppingCart.jar/StatelessCartBean#soa.sca.samples.candystore.ejb3.RemoteCart"/>

    Replace the address and port with the address and port for you server. For example, if your hostname is http://myserver.ibm.com and your bootstrap port is 2811 the two references would look like the following:

    <reference name="shoppingCart">
    	<interface.java interface="soa.sca.samples.candystore.Cart" />
    	<binding.ejb uri="corbaname:iiop:http://myserver.ibm.com:2811/NameServiceServerRoot#ejb/EJB3ShoppingCartEAR/EJB3ShoppingCart.jar/StatelessCartBean#soa.sca.samples.candystore.ejb3.RemoteCart"/>
    </reference>
    <reference name="shoppingTotal">
    	<interface.java interface="soa.sca.samples.candystore.Total" />
    	<binding.ejb uri="corbaname:iiop:http://myserver.ibm.com:2811/NameServiceServerRoot#ejb/EJB3ShoppingCartEAR/EJB3ShoppingCart.jar/StatelessCartBean#soa.sca.samples.candystore.ejb3.RemoteCart"/>
    </reference>
  3. After making the above modifications open a command window and change to the <SCA_SAMPLE_HOME>\CandyStore\candystoreservice-topdown directory.
  4. Issue the following command to build the application

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

    Example command:

    C:\WebSphere\AppServer\profiles\AppSrv01\bin\ws_ant
  5. Verify that the build completes without error.
  6. The output of the build command can be found under the <SCA_SAMPLE_HOME>\CandyStore\candystoreservice-topdown\target directory. Verify that the following artifacts have been generated by the build:

    <SCA_SAMPLE_HOME>\CandyStore\candystoreservice-topdown\target\classes (Location of .class files)
    <SCA_SAMPLE_HOME>\candystoreservice-topdown\target\generated (Location of generated Java source)
  7. Verify that the CandyStoreTopDown.jar BLA module has been generated in the <SCA_SAMPLE_HOME>\CandyStore\candystoreservice-topdown\target\ directory.
  8. In your command window change to the <SCA_SAMPLE_HOME>\CandyStore\candystoreJPAcart directory.
  9. Issue the following command to build the application:

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

    Example command:

    C:\WebSphere\AppServer\profiles\AppSrv01\bin\ws_ant
  10. Verify that the build completes without error.
  11. Verify that the CartEAR.ear module has been generated in the <SCA_SAMPLE_HOME>\CandyStore\candystoreJPAcart\target\ directory.

CandyStore TopDown Client Application

To build and package the CandyStore application:

  1. Open a command window and change to the <SCA_SAMPLE_HOME>\CandyStore\candystoreclient-topdown directory.
  2. Issue the following command to build the application:

    <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.
  4. Verify that the output WAR file, CandyStore-TopDown-client.war, is found under the <SCA_SAMPLE_HOME>\CandyStore\candystoreclient-topdown\target\ directory.

Install

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 Candy Store 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

CandyStore Application

This section describes how to install both the CandyStore service and CandyStore client applications.

  1. Start the WebSphere Application Server if it is not already started.
    1. Open a command window and issue the following command:

      cd <WAS_HOME>\profiles\<PROFILE_NAME>\bin

      Example command:

      cd C:\WebSphere\AppServer\profiles\AppSrv01\bin
    2. Issue the startServer command

      startServer server1
  2. Create the CandyStore data source using the Administrative console.
    1. Log into the Administrative Console by navigating to http://localhost:9060/admin in a Web browser.
      NOTE: If the default Admin port is not 9060 for your application server profile, the URL above should include the port number for your installation
    2. Enter a username and password if required and press Log in.
  3. Optional: You are using a Derby database for part of this application. Create a new Derby JDBC provider if one does not already exist.
    1. From the left navigation panel of the Administrative console, expand Resources > JDBC and click on JDBC Providers.
    2. On the JDBC Provider page select Node=<NODE_NAME>, Server=server1 from the scope drop down list before creating a new JDBC provider.
    3. Still on the JDBC Provider page, click New to create a new JDBC Provider.
    4. Select Derby from the Database type drop down list.
    5. Select Derby JDBC Provider from the Provider type drop down list.
    6. Select Connection pool data source from the Implementation type drop down list
    7. Set the name to Derby JDBC Provider (which is the default). When you repeat this step for EUDB, set the name to Derby JDBC Provider as well.
    8. Click Next and on the Summary page click Finish.
    9. Click the Save link at the top of the JDBC Provider page to save your changes.
  4. Create a new data source for use in the CandyStore application.
    1. From the left navigation panel of the Administrative console, expand Resources > JDBC and click on Data sources.
    2. On the Data Sources page, select Node=<NODE_NAME>, Server=server1 from the scope drop down list.
    3. Still on the Data Sources page, click New to create a new Data Source.
    4. Enter StoreUSDB for the Data source name.
    5. Enter USDB for the JNDI name.
    6. Click Next.
    7. For the JDBC Provider, choose select an existing one and select the Derby JDBC Provider from the drop down list.
    8. Click Next.
    9. On the database specific properties page enter the path to the USDB directory located in <SCA_SAMPLE_HOME>\CandyStore\StoreUSDB
    10. Uncheck the Use this data source in container managed persistence (CMP) check box and click Next, until you get to the summary panel.
    11. Click Finish on the summary panel.
    12. Click the Save link at the top of the Data sources page to save your changes.
    13. Once the changes are saved, check the box next to StoreUSDB in the list of Data sources, and click the Test Connection button. Verify that you see a message that the test was successful
    14. Repeat step 4 to create a datasource for the StoreEUDB database. You will need to use a Data source name of StoreEUDB and a JNDI name of EUDB and a database path to the EUDB directory located in <SCA_SAMPLE_HOME>\CandyStore\StoreEUDB
    15. You must restart your server in order for these changes to take effect.
  5. Use the Administrative Console to import CandyStore.jar, CandyStoreLooseSupplier.jar, CandyStoreRecursiveSupplier.jar, and CandyStoreTopDown.jar.
    1. Open and 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 ApplicationTypes and select Assets.
    3. Press the Import button, then browse to <SCA_SAMPLE_HOME>\CandyStore\candystoreservice\target\ and select the CandyStore.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, and return to Applications and select Assets.
    5. Press the Import button, then browse to <SCA_SAMPLE_HOME>\CandyStore\candystoreloosesupplier\target\ and select the CandyStoreLooseSupplier.jar file. Click Next using all the default settings until you reach the summary page and click Finish.
    6. Click the Save link at the top of the screen, and return to Applications and select Assets.
    7. Press the Import button, then browse to <SCA_SAMPLE_HOME>\CandyStore\candystorerecursivesupplier\target\ and select the CandyStoreRecursiveSupplier.jar file. Click Next using all the default settings until you reach the summary page and click Finish.
    8. Click the Save link at the top of the screen, and return to Applications and select Assets.
    9. Press the Import button, then browse to <SCA_SAMPLE_HOME>\CandyStore\candystoreservice-topdown\target\ and select the CandyStoreTopDown.jar file. Click Next using all the default settings until you reach the summary page and click Finish.
    10. Click the Save link at the top of the screen, and return to Applications and select Assets.
  6. Use the Administrative Console to deploy the EJB 3.0 Shopping Cart application.
    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 CartEAR.ear file located in the <SCA_SAMPLE_HOME>/CandyStore/candystoreJPAcart/target/ 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. 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 EJB3ShoppingCartEAR and press Start.
  7. Use the Administrative Console to create the Business-level Applications that will run the SCA composites.
    1. From the left navigation panel of the Administrative console, expand Applications and select Application Types and then Business-level Applications and click on New.
    2. Fill in CandyStoreBLA for name and click Apply.
    3. Click the Save link at the top of the screen.
    4. Return to Applications and select Business-level Applications and click on New.
    5. Fill in CandyStoreServiceBLA for name and click Apply.
    6. Click the Save link at the top of the screen.

CandyStore Client Application

  1. Log into the Administrative Console
    1. In a web browser, navigate to http://localhost:9060/admin. and log in to the Administrative Console.
      NOTE: If the default Admin port is not 9060 for your application server profile, the URL above should include the port number for your installation
  2. Install the Candy Store client application from the Administrative Console
    1. From the left navigation panel of the Administrative console, expand Applications and select New Application. Then select 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 CandyStore-client.war file located in the <SCA_SAMPLE_HOME>/CandyStore/candystoreclient/target/ 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. Since the sample application is a WAR file, you need to specify the context root of the Web module in the WAR file. On the "Map context roots for Web modules" page specify the Context root as candyStore.
    5. Select the Next button at the bottom of the panel
    6. 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.
    7. Verify in the admin console that the CandyStore client has installed successfully.
    8. 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 CandyStore-client_war and press Start.
    9. Verify that the CandyStore-client application has started. The application status for the CandyStore-client_war should show a green arrow.
  3. Install the CandyStore Top Down 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 CandyStoreTopDown-client.war file located in the <SCA_SAMPLE_HOME>/CandyStore/candystoreclient-topdown/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 candyStoreTopDown 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 CandyStoreTopDown 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 CandyStoreTopDown-client _war and press Start.
    11. Verify that the CandyStoreTopDown-client application has started. The application status for the CandyStoreTopDown-client _war should show a green arrow.

Configure Web Services Policy Sets

  1. Use wsadmin scripting to create a new provider policy set binding.
    1. Open a wsadmin command window from <WAS_HOME>\profiles\<PROFILE_NAME>\bin\

      Example command:

      wsadmin.bat -lang jython -username myusername -password mypassword
    2. Enter the following wsadmin commands:

      AdminTask.copyBinding('[-sourceBinding "Provider sample" -newBinding LTPA]')
      arg = '[-policyType WSSecurity -bindingLocation -attributes [ [application.securityinboundbindingconfig.caller_999.calleridentity.uri http://www.ibm.com/websphere/appserver/tokentype] [application.securityinboundbindingconfig.caller_999.name LTPA] [application.name application] [application.securityinboundbindingconfig.caller_999.order 1] [domain global] [application.securityinboundbindingconfig.caller_999.calleridentity.localname LTPAv2] [application.securityinboundbindingconfig.caller_999.jaasconfig.configname system.wss.caller] ] -attachmentType application -bindingName "LTPA" -bindingScope domain]'
      AdminTask.setBinding(arg)
      AdminConfig.save()

Running

Candy Store Applications

  1. Use the Administrative Console to add the proper composites to your Business-level Applications.
    1. From the left navigation panel of the Administrative console, expand Applications then Application Types and select Business-level Applications.
    2. Click on CandyStoreBLA.
    3. Under Deployed Assets click on Add and choose Add Asset. Select CandyStore.jar and click Continue.
    4. You should see several composites on this page. Select {http://soa.sca.samples.candystore/}StoreComposite click Continue. Click Next until the last panel and then click Finish.
    5. Click the Save link at the top of the screen, and return to Applications and select Application Type and then Business-level Applications. Select the CandyStoreBLA checkbox and click on Start.
    6. Open a browser window and enter the following URL: http://localhost:9080/candyStore
      NOTE: If the default HTTP transport port is not 9080 for your application server profile, the URL above should include the port number for your installation.
  2. Verify that you see the CandyStore page with a list of items in the catalog and an empty shopping cart in your browser.
    1. Choose an item and add it to your shopping cart. Then add more items and empty your shopping cart.
    2. Verify that the items you choose are being added to your shopping cart and displaying the total cost.
    3. Add more items to your cart and click on Checkout.
    4. Verify that you are on the checkout page, Checkout.jsp, and the shopping cart is the list of items you selected. Your will shopping cart be emptied once you choose checkout.
  3. How to run the other composites in the CandyStore.jar
    1. From the left navigation panel of the Administrative console, expand Applications and then Application Types and select Business-level Applications.
    2. Select CandyStoreBLA checkbox and click Stop.
    3. Click on CandyStoreBLA and select the composite checkboxes marked with a type of asset and click on Delete, and click OK on the next screen. Then click on Save at the top of the screen.
    4. On the Business-level Applications screen click on the CandyStoreBLA. If there are any assets listed with a type of Shared library select those checkboxes and click on Delete, and click OK on the next screen. Then click on Save at the top of the screen.
      NOTE: If there are multiple assets that need to be removed from a BLA the assets must always be removed before the shared libraries.
    5. Go to Applications and select Applicaton Types and then Business-level Applications. Then click on CandyStoreBLA.
    6. Under Deployed Assets click on Add and choose Add Asset. Select CandyStore.jar and click Continue.
    7. Select the {http://soa.sca.samples.candystore/}StoreMergerComposite and click Continue. Note that you cannot select multiple assets at the same time. You must add them one at a time. Click Next until the last panel and then click Finish.
    8. Click the Save link at the top of the screen, and return to Applications and select Application Types and then Business-level Applications. Select the CandyStoreBLA checkbox and click on Start.
    9. Again, verify that you can see the CandyStore page with a list of items and that you can use the Add to Cart and Checkout buttons.
    10. Repeat the above steps under "How to run the other composites in the CandyStore.jar" and deploy and start the following composites and test them.

      • {http://soa.sca.samples.candystore/}StoreMergerComposite
      • {http://soa.sca.samples.candystore/}StoreDBComposite
      • {http://soa.sca.samples.candystore/}StoreSupplierComposite
      • {http://soa.sca.samples.candystore/}StoreEUComposite
  4. In order to verify that certain services are exposed over the Web Service binding you can check to see if you can view the wsdl definition in your browser. Below is a breakdown of the wsdl's you should be able to view depending on which composite you have deployed.

Candy Store Looser Supplier Composites

  1. Use the Administrative Console to add the proper composites to your Business-level Applications to show the use of the import and export features in a contribution file and the ability to loosely couple different components in an SCA application.
    1. From the left navigation panel of the Administrative console, expand Applications then Application Types and select Business-level Applications.
    2. Next click on CandyStoreServiceBLA.
    3. Under Deployed Assets click on Add and choose Add Asset. Select CandyStoreLooseSupplier.jar and click Continue.
    4. You should see several composites on this page. Select {http://soa.sca.samples.candystore/} StoreSupplierStoreComposite and click Continue. Click Next until the last panel and then click Finish.
      NOTE: When adding composites which have dependencies on imported packages or namespaces the assets will automatically be added as a shared library to your BLA. For example, when adding the above composite a shared library with a name similar to CandyStore_0001.jar will be added to your BLA.
    5. Click the Save link at the top of the screen, and return to Applications and select Application Types and then Business-level Applications. Select the CandyStoreServiceBLA checkbox and click on Start.
    6. Next you will need to change the composites that are deployed in the CandyStoreBLA. You must remove any composites that already exist in this BLA. Use the previous section, Candy Store Applications Step (4), titled "How to run other composites in the CandyStore.jar" as a reference on how to deploy and start the following composites.

      NOTE: When adding multiple composites please do not select multiple assets to add them all at the same time. You must add each asset one at a time.
      • {http://soa.sca.samples.candystore/}StoreSupplierCatalogComposite located in the CandyStoreLooseSupplier.jar
      • {http://soa.sca.samples.candystore/}StoreSupplierShoppingCartComposite located in the CandyStoreLooseSupplier.jar
    7. After saving your changes and starting your Business-level Applications open a browser window and enter the following URL: http://localhost:9080/candyStore
      NOTE: If the default HTTP transport port is not 9080 for your application server profile, the URL above should include the port number for your installation.
    8. Verify that you can see the CandyStore page with a list of items and that you can use the Add to Cart and Checkout buttons.
  2. Use the Administrative Console to deploy the composites that show the use of the EJB binding and JPA.
    1. You will need to change the composites that are deployed in the CandyStoreBLA and CandyStoreServiceBLA . You must remove any composites in these BLA's that are not listed below. Use the previous section, Candy Store Applications Step (4), titled "How to run other composites in the CandyStore.jar" as a reference on how to deploy and start the following composites:
    2. In the CandyStoreBLA remove all composites except for the following:

      {http://soa.sca.samples.candystore/}StoreSupplierCatalogComposite located in the CandyStoreLooseSupplier.jar

    3. In the CandyStoreServiceBLA remove the current composite and add the following composite:

      http://soa.sca.samples.candystore/}StoreSupplierStoreJPAComposite located in the CandyStoreLooseSupplier.jar

    4. After saving your changes and starting your Business-level Applications open a browser window and enter the following URL: http://localhost:9080/candyStore
      NOTE: If the default HTTP transport port is not 9080 for your application server profile, the URL above should include the port number for your installation.
    5. Verify that you can see the CandyStore page with a list of items and that you can use the Add to Cart and Checkout buttons.

Top Down version of the Candy Store application

  1. Use the Administrative Console to add the proper composites to your Business-level Applications.
    1. From the left navigation panel of the Administrative console, expand Applications then Application Types and select Business-level Applications.
    2. Next click on CandyStoreServiceBLA.
    3. You will need to change the composites that are deployed in the CandyStoreServiceBLA . You must remove the any composites in these BLA's that are not listed below. Use the previous section, Candy Store Applications Step (4), titled "How to run other composites in the CandyStore.jar" as a reference on how to deploy and start the following composites:

      {http://soa.sca.samples.candystore/}StoreSupplierTopDownComposite located in the CandyStoreTopDown.jar

    4. Next you will need to change the composites that are deployed in the CandyStoreBLA. You must remove any composites that already exist in this BLA. Use the previous section, Candy Store Applications Step (4), titled "How to run other composites in the CandyStore.jar" as a reference on how to deploy and start the following composites:

      • {http://soa.sca.samples.candystore/}StoreSupplierCatalogComposite located in the CandyStoreLooseSupplier.jar
      • {http://soa.sca.samples.candystore/}StoreSupplierShoppingCartComposite located in the CandyStoreLooseSupplier.jar
    5. After saving your changes and starting your Business-level Applications open a browser window and enter the following URL: http://localhost:9080/candyStoreTopDown
      NOTE: If the default HTTP transport port is not 9080 for your application server profile, the URL above should include the port number for your installation.
    6. When loading this page in your browser you will be prompted for a user name and password. Use the same login information that you used to log in to the Administrative console or any other user that you have created. You may need to restart your browser or clear your browser cache to be prompted for a username and password.
    7. Verify that you can see the CandyStore page with a list of items and that you can use the Add to Cart and Checkout buttons.
  2. Use the Administrative Console to deploy the composites that show the use of the recursive model.
    1. You will need to change the composites that are deployed in the CandyStoreBLA. You must remove the any composites in this BLA that are not listed below. Use the previous section, Candy Store Applications Step (4), titled "How to run other composites in the CandyStore.jar" as a reference on how to deploy and start the following composites:
      • {http://soa.sca.samples.candystore/}StoreSupplierCatalogOuterComposite located in the CandyStoreRecursiveSupplier.jar
      • {http://soa.sca.samples.candystore/}StoreSupplierShoppingCartComposite located in the CandyStoreLooseSupplier.jar
    2. After saving your changes and starting your Business-level Applications open a browser window and enter the following URL: http://localhost:9080/candyStoreTopDown
      NOTE: If the default HTTP transport port is not 9080 for your application server profile, the URL above should include the port number for your installation.
    3. Verify that you can see the CandyStore page with a list of items and that you can use the Add to Cart and Checkout buttons. When loading this page in your browser you will be prompted for a user name and password. Use the same login information that you used to log in to the Administrative console or any other user that you have created. You may need to restart your browser or clear your browser cache to be prompted for a username and password.
  3. Use the Administrative Console to deploy the composites that show the use of the authentication and authorization using policy sets.
    1. You will need to change the composites that are deployed in the CandyStoreBLA. You must remove any composites in this BLA that are not listed below. Use the previous section, Candy Store Applications Step (4), titled "How to run other composites in the CandyStore.jar" as a reference on how to deploy and start the following composites:
      • {http://soa.sca.samples.candystore/}StoreSupplierCatalogOuterComposite located in the CandyStoreRecursiveSupplier.jar
      • {http://soa.sca.samples.candystore/}StoreSupplierSecureShoppingCartComposite located in the CandyStoreLooseSupplier.jar
    2. After saving your changes and starting your Business-level Applications open a browser window and enter the following URL: http://localhost:9080/candyStoreTopDown
      NOTE: If the default HTTP transport port is not 9080 for your application server profile, the URL above should include the port number for your installation.
    3. Verify that you can see the CandyStore page with a list of items and that you can use the Add to Cart and Checkout buttons. You may need to restart your browser or clear your browser cache to be prompted for a username and password. You should only be able to access the shopping cart if you are logged in with a user that falls under role1. This is the username that was added in section 1.1 titled "Inspect and build the CandyStore application". If you log in as a different user than what is listed under role1 you will see failed authorization message.
  4. Use the Administrative Console to deploy the composites that show the use of the EJB binding and JPA and also the use of the autowire feature.
    1. You will need to change the composites that are deployed in the CandyStoreBLA and CandyStoreServiceBLA . You must remove the any composites in these BLA's that are not listed below. Use the previous section, Candy Store Applications Step (4), titled "How to run other composites in the CandyStore.jar" as a reference on how to deploy and start the following composites:
    2. In the CandyStoreBLA remove all composites except for the following:
      • {http://soa.sca.samples.candystore/}StoreSupplierCatalogOuterAutoWireComposite located in the CandyStoreRecursiveSupplier.jar
    3. In the CandyStoreServiceBLA remove the current composite and add the following composite:
      • http://soa.sca.samples.candystore/}StoreSupplierJPATopDownComposite located in the CandyStoreTopDown.jar
    4. After saving your changes and starting your Business-level Applications open a browser window and enter the following URL: http://localhost:9080/candyStoreTopDown
      NOTE: If the default HTTP transport port is not 9080 for your application server profile, the URL above should include the port number for your installation.
    5. Verify that you can see the CandyStore page with a list of items and that you can use the Add to Cart and Checkout buttons. Use the same login information that you used to log in to the Administrative console or any other user that you have created. You may need to restart your browser or clear your browser cache to be prompted for a username and password.

Uninstall

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 CandyStore 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 two Candy Store related BLAs on this page, CandyStoreBLA and CandyStoreServiceBLA. Click on CandyStoreServiceBLA. 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 CandyStoreServiceBLA and click on delete and then click the Save link at the top of the screen.
  4. Expand Applications then Application Types and select Business-level Applications and repeat the above three steps with the CandyStoreBLA.
  5. Next you will need to uninstall the Candy Store client wars. Expand Applications then Application Types and select WebSphere Enterprise Applications. Select CandyStore-client_war and click on Uninstall. After the client application has been removed click on the Save link at the top of the screen.
  6. Repeat the previous two steps (4 and 5) to now remove the CandyStoreTopDown-client_war client application.

User's Guide

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

Candy Store screenshot with empty shopping cart

You can:

  • Choose an item and add it to your shopping cart. Then add more items and empty your shopping cart.
  • Verify that the items you choose are being added to your shopping cart and displaying the total cost.
  • Add more items to your cart and click on Checkout.
  • Verify that you are on the checkout page, Checkout.jsp, and the shopping cart is the list of items you selected. Your will shopping cart be emptied once you choose checkout.

Adding items to the cart looks like this:

Candy Store screenshot with full shopping cart

When you check out, you should see a page like this:

Candy Store checkout page screenshot