JavaTM Web Services WS-I Supply Chain Management Sample Application 1.0


Samples Index WS-I Member Logo



WS-I Supply Chain Management Sample Application 1.0


This document describes the WS-I Supply Chain Management Sample Application 1.0 as deployed in the Sun Java System Application Server 8.1.

This document contains the following sections:

1.0 Introduction
2.0 Directory structure
3.0 Prerequisites
      3.1 Container configuration
      3.2 Database configuration
4.0 Invoking the service
      4.1 Retailer
      4.2 Configurator
      4.3 Catalog
5.0 Building from the source
6.0 Configuring logging
7.0 Troubleshooting
8.0 References

 

1.0 Introduction

The Web Services Interoperability Organization (WS-I) [1] is an organization committed to promoting interoperability among Web Services based on common, industry-accepted definitions and related XML standards support. Towards this end, the WS-I organization is producing a set of deliverables that is intended to assist developers in creating and deploying interoperable Web Services. WS-I Sample Application, one of the deliverables from WS-I, demonstrates the reality of practical application of Web Services technologies to solve real business needs.

WS-I Sample Application is defined as a sample Supply Chain Management application. The use case design of this sample application is defined in Supply Chain Management Use Case Model [2] and Use Cases for Attachments Sample Applications 1.0 [3] . Technical design and implementation details of this sample application are documented in Supply Chain Management Architecture document [4] and Technical Architecture for Attachments Sample Applications 1.0 [5].

The application being modeled is that of a Retailer offering consumer electronic goods to Consumers; a typical B2C model. To fulfill orders, the Retailer has to manage stock levels in Warehouses. When an item in stock falls below a certain threshold, the Retailer must restock the item from the relevant Manufacturer's inventory; a typical B2B model. In order to fulfill a Retailer's request, a Manufacturer may have to execute a production run to build the finished goods. Each use case includes a logging call to a logging facility in order to monitor the activities of the services.

Retailer can also out-source the cataloging capabilities to a Catalog service that provides operations to access the catalog of products. The Catalog enables a consumer to browse it's contents and retrieve additional information about individual items. The consumer can then order the products from the Catalog which can then be packaged into an order and sent to a Retailer.

Optionally, there is a Configurator Web Service that lists all of the implementations registered in the UDDI registry for each of the Web Services in the sample application.

The 1 Retailer, 1 Logging Facility, 3 Warehouses, 3 Manufacturers, and 1 Configurator Web Service are designed and implemented as part of WS-I Supply Chain Management Sample Applications 1.0 FCS. 1 Catalog Web Service is designed and implemented as part of WS-I Attachments Sample Applications 1.0. It demonstrates application of Basic Profile 1.1 [6], Simple SOAP Binding Profile 1.0 [7], and Attachments Profile 1.0 [8] to a real-life scenario.

This document explains Sun's implementation of WS-I Sample Supply Chain Management Application 1.0 FCS and WS-I Attachments Sample Applications 1.0 EA.

2.0 Directory structure

All paths are relative to <install_dir>/samples/webservices/apps/wsi1.1, where <install_dir> is the installation directory of the Sun Java System Application Server 8.

This section explains the directory structure.

docs

index.html, this file

src/conf/config

Configuration files required by the JAX-RPC tools, including the deployment descriptors to assemble the application compliant with the JSR 109 (J2EE Web Services)

src/conf/wsdl

WSDL descriptions for the Web Services. Remote WSDL files, located at wsi.org

src/conf/wsdl.local

WSDL descriptions for the Web Services. Local WSDL files

src/java

Source code

wsi-server.ear

EAR file with all the Web Service endpoints. JSR 109 compliant

logs

Generated results and SOAP request and response message files

3.0 Prerequisites

Before any of the sample application Web Services can be invoked, you need to configure the container and database of your choice as described below.

3.1 Container configuration: Sun Java System Application Server 8

Start the Application Server. Configure the http.proxyHost and http.proxyPort properties for the container by giving the following command:

asadmin create-jvm-options --user <admin_user> --password <admin_password> -Dhttp.proxyHost=<your_proxy_host>:-Dhttp.proxyPort=<your_proxy_port>

If the Application Server is not running on the standard host and port, then you need to specify the --host and --port options.

You can also set the http.proxyHost and http.proxyPort properties in the main build.xml file, and then type asant set-proxy-host in the main directory of the application.

3.2 Database configuration: PointBase

The pre-built EAR file wsi-server.ear provided is configured to be used with the PointBase database server.

  1. A functional version of PointBase is available in the <install_dir>/pointbase directory. This version of PointBase can be used under the licensing terms of the Application Server.
  2. Start the PointBase database server:
    1. Go to the <install_dir>/pointbase/tools/serveroption directory and invoke the startserver.[sh | bat] script.
    2. Make sure that the database server is listening on port 9092. The port number is displayed when the script is invoked. Otherwise you can change the port number by modifying the script to add /port:9092 after com.pointbase.net.netServer.
  3. Create a database:
    1. Go to the AS_HOME/pointbase/tools/serveroption directory and invoke the startconsole.[sh | bat] script.
    2. If the "Connect to Database" window opens, select "Create New Database". If the "Connect to Database" window does not open, then select the DBA menu item from the main menu, then select Create and then select New Database.
      1. Accept the defaults for the Driver, User and Password options.
      2. Change the URL to jdbc:pointbase:server://localhost/wsi.
      3. Click OK.
    3. Click on File -> Exit to leave the database connection window.

4.0 Invoking the service

Make sure that the container and the database server configured above are running before invoking any of the services. The chosen database server will be running if you have performed step 2 in Section 3.2.

4.1 Invoking the Retailer client

The Retailer client acts as a consumer of the electronic goods and places pre-defined orders (defined in src/conf/retailer-config.xml) to the Retailer Web Service. The Retailer Web Service then invokes the warehouse and manufacturer Web Service to fulfill the supply chain model defined in Section 1.0 above. The orders are defined such that the various combinations of retailer, warehouse and manufacturer are being invoked. The set of endpoints is defined in src/conf/endpoints.props, and the combination of endpoints is defined in src/conf/vendor-config.xml.
  1. Make sure src/conf/endpoints.props has the correct host and port information.
  2. In the main directory of the application, type asant run-retailer to invoke the client. This will invoke the getCatalog function from the RetailerService and place the various pre-defined orders to the Retailer Web Service.

4.2 Invoking the Configurator client

The Configurator client queries a public UDDI Business Registry for the WS-I sample application endpoints implemented by all the vendors which have a peer-to-peer relationship with WS-I business entity and displays them.
  1. You need to set the http.proxyHost and http.proxyPort properties for your container to allow the container to be able to talk to the UDDI Business Registry outside the firewall. Refer to Section 3.1 for container specific configuration.
  2. The Configurator Web Service performs tasks that require the modification of the default security policy of the server. Make sure to add the following grant clause to the <install_dir>/domains/<domain_name>/config/server.policy file and restart the server before you invoke this Web service:
    // Permissions required by the WSI sample application
    grant codeBase "file:${com.sun.aas.installRoot}/lib/jaxr-impl.jar" {
            permission java.security.AllPermission;
    };
  3. Before running the Configurator Web Service, you need to place the <install_dir>/lib/jaxr-implp.jar file at the beginning of the classpath of the server. To achieve this, you can set the server.classpath.prefix property in the main build.xml file to <install_dir>/lib/jaxr-implp.jar and then type asant set-server-classpath-prefix in the main directory of the application. Be warned that this command will restart the server. Also, before setting the server.classpath.prefix property and running the above command, you should run asant get-server-classpath-prefix to verify if you need to include any other JAR files that were already in the server classpath prefix.
  4. Type asant run-query to invoke the client.
  5. The default behavior of this service is to contact the UDDI business registry and generate the endpoints information dynamically. However, the Configurator Web Service also maintains all endpoint information in a local cache accessible by modifying the following property of the main build.xml file before invoking the service:

    configurator.refresh=false

    Specifying this option will not invoke the public UDDI business registry and will instead provide you with endpoint information from the local cache. This cache is also updated every time the UDDI registry is contacted for getting the list of endpoints.
  6. asant run-query uses the default Configurator Web Service bundled with this application. If you need to use another Configurator Web Service, you need to modify the main build.xml file before invoking the service:

    configurator.endpoint=<ANOTHER_CONFIGURATOR_ENDPOINT>

    To obtain other configurator endpoints, configure server-side logging to the CONFIG logging level and set configurator.refresh to true as described in the previous step. Search the server-side logs for "Configurator" keyword, and the endpoint address is available in the corresponding CONFIG log entry. Refer to Section 6.0 for details on how to configure logging.
  7. If both the configurator.endpoint and -Dconfigurator.refresh options are specified, then endpoint information is retrieved in the following manner:
    configurator.refresh configurator.endpoint How endpoints are generated
    true Not specified Configurator Web Service talks to the UDDI registry
    false Not specified Local cache from the Configurator Web Service
    true Specified Remote endpoint talks to the UDDI registry
    false Specified Local cache from the remote endpoint

4.3 Invoking the Catalog client

The Catalog client queries the Catalog Web Service, which simulates an out-sourced cataloging capability that is used by the Retailer Web Service. It provides operations to access the catalog of products. The Catalog enables a consumer to browse its contents and retrieve additional information about individual items. In a larger context, the products that the consumer orders from the Catalog can be packaged into an order and sent to a Retailer.

The set of Catalog endpoints is defined in src/conf/endpoints.props.
  1. Make sure src/conf/endpoints.props has the correct host and port information.
  2. In the main directory of the application, type asant run-catalog to invoke the client. This will invoke the getCatalogWithImages and getProductDetails function from the Catalog Web Service. getCatalogWithImages returns attachment references of thumbnail images for each product in the catalog. getProductDetails provides additional details about each product, a larger product image, and a product spec sheet. The spec sheet and picture are conveyed as SOAP attachments.
  3. The default behavior of asant run-catalog is to invoke getCatalogWithImages and getProductDetails for each product in the Catalog. If you need to invoke only getCatalogWithImages, you need to modify the following property in the main build.xml file of the application before invoking the service:

    catalog.level=thumbnail

    If you need to invoke only getProductDetails, you need to modify the following property before invoking the service:

    catalog.level=details
  4. asant run-catalog uses the default Catalog Web Service bundled with this application. If you need to use another Catalog Web Service, you need to add the endpoint in src/conf/endpoints.props in the form

    vendor.catalog=ENDPOINT_ADDRESS

    where ENDPOINT_ADDRESS specifies the location of the new Catalog Web Service and vendor can be replaced by the name of the Web Service provider. Then the new Catalog Web Service can be used by specifying the modifying this property of the main build.xml file of the application before invoking the service:

    catalog.endpoint=vendor

    where vendor needs to match the "vendor" string specified in src/conf/endpoints.props.

5.0 Building from the source

By default this application is built using WSDL files that have been locally cached. It is recommended that you build the application using the WSDL files located at wsi.org. To do that, you must set the following two properties of the main build.xml file in the following way:

<property name="wsdl.home" value="${etc.home}/wsdl"/>
<property name="wsdl.location" value="remote"/>

When using the remote WSDL files, if the HTTP proxy host and port are not already configured, configure the http.proxyHost and http.proxyPort properties in the main build.xml file of the application appropriately before building from the source.

6.0 Configuring logging

This application utilizes the Java Logging API [9]. By default, the sample application has its logging level set to INFO. The following levels are available, in ascending order of granularity, and are used in the application as shown below.
Logging Level Usage
SEVERE Server-side or client-side exception
WARNING Non-blocking error conditions
INFO (default) Basic flow of application
CONFIG Logging entries from the Logging Facility
FINE SOAP request and response messages
FINER Entry and exit points of primary methods
FINEST Intermediate steps from the primary methods, if any

To change the default logging level (INFO) on the server and client sides to a different level:

  1. Edit the JAVA_HOME/jre/lib/logging.properties file used by the server.
  2. Add the following on a new line:

    com.sun.wsi.scm.level=LEVEL

    where LEVEL is one of the seven logging levels mentioned above.
  3. Restart the container and rerun the client.

7.0 Troubleshooting

  1. Check that all the container- and database-specific prerequisites are met.
  2. All the endpoints are configured in the file src/conf/endpoints.props. The default endpoints are configured for host "localhost" and port "8080". If your application is deployed at a different port, then make sure that these are reflected correctly in the src/conf/endpoints.props file.
  3. Make sure the database server is started before the run-retailer script is invoked. If the database is started after the script is invoked, you need to restart the container.
  4. Make sure the database is running on the correct host and port and the appropriate database has already been created. Refer to section 3.2 for more details.
  5. Database related properties are stored in src/conf/pointbase.props. If you need to modify any of the database configuration properties, edit this file and then rebuild and redeploy the application as explained above.
  6. If any of the sample application endpoints is outside your firewall, you need to make sure that the access to the proxy host is appropriately set up.
  7. You can specify sample application endpoints from other vendors in the src/conf/endpoints.props file and create different configurations, comprised of endpoints from different vendors, in src/conf/vendor-config.xml. Each of these configurations will be used to place the orders specified in src/conf/retailer-config.xml. However if your endpoints are deployed inside a firewall, then only the Retailer Web Service hosted within the firewall can be mixed with the other endpoints installed outside the firewall.
  8. To view the SOAP request and response messages, set the logging level to FINE and restart the container. Refer to Section 6.0 on how to configure logging. SOAP request and response messages are available for the Retailer, Logging and Configurator clients as given below:
    • Retailer client SOAP request and response messages are available in logs/retailer-soap-messages.txt.
    • Logging client SOAP request and response messages are available in logs/logging-soap-messages.txt.
    • Configurator client SOAP request and response messages are available in logs/configurator-soap-messages.txt.

    Server-side log messages are available in the corresponding logs directory of your container.

8.0 References

  1. WS-I
  2. Supply Chain Management Sample Application 1.0 Use Case Model Board Approval Draft
  3. Use Cases for Attachments Sample Applications 1.0 (Editor's Draft - not publicly available yet)
  4. Supply Chain Management Sample Application 1.0 Architecture Board Approval Draft
  5. Technical Architecture for Attachments Sample Applications 1.0 (Editor's Draft - not publicly available yet)
  6. Basic Profile 1.1 Working Group Draft
  7. Simple SOAP Binding Profile 1.0 Working Group Draft
  8. Attachments Profile 1.0 Working Group Draft
  9. Java Logging APIs