WS-I Supply Chain Management Sample Application 1.0

The latest updates to this document are in the online documentation posted on our web site.

1.0 Introduction
2.0 Directory Structure
3.0 Pre-Requisites
4.0 Invoking the service
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]. Technical design and implementation details of this sample application are documented in Supply Chain Management Architecture document [3].

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. In the real world, a Manufacturer would have to order the component parts from its suppliers. For simplicity in this application, it is assumed this is a manual process which is supported through the use of fax. Each use case includes a logging call to a logging facility in order to monitor the activities of the services.

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.

There is 1 Retailer, 1 Logging Facility, 3 Warehouses, 3 Manufacturers and 1 Configurator, and thus a total of 9 Web Services.

This document explains the Sun's implementation of WS-I Sample Supply Chain Management Application.

2.0 Directory Structure

This section explains the directory structure

bin	Scripts to invoke the retailer and configurator clients
docs	index.html
etc/config	Configuration files required by JAX-RPC tools
etc/wsdl	WSDL descriptions for the Web Services
lib	Supporting jar files
src	Source code
wsi-server.war	WAR file with all the Web Service endpoints
logs	SOAP request and response message files and generated results

3.0 Pre-Requisites

Before any of the sample app Web Service can be invoked, you need to ensure

• Tomcat server is not running.
• unpackWARs attribute for "localhost" host in "Catalina" Engine in JWSDP_HOME/conf/server.xml is set to "true".
  • This is a container-wide setting and will impact other applications deployed in this container as well. Enabling this setting explodes the content of the war file in JWSDP_HOME/webapps directory by the war file name. To redeploy an app, the exploded directory needs to be removed from JWSDP_HOME/webapps directory before starting Tomcat container. 
• Pointbase database server is running.  Refer to www.pointbase.com to download an evaluation version of Pointbase database. Choose "Pointbase Embedded - Server Option" while downloading the evaluation version.
• Pointbase client jar file (typically named pbclientXX.jar, where XX refers to pointbase version number without ".") is copied in JWSDP_HOME/common/lib.
• A user with the username "PBPUBLIC" and password "PBPUBLIC" exists in the database with rights to create tables and insert data. This is the default user in pointbase database as of now but may change in future versions.

Once the database is running, you need to create a database with the URL "jdbc:pointbase:server://localhost/wsi" by invoking startconsole.[sh | bat] script bundled with pointbase release. At the time of JWSDP 1.3 release going public, pointbase 4.6 is the latest version available on www.pointbase.com. Database creation instructions may differ for a later pointbase release.

4.0 Invoking the service

Make sure Tomcat server is up and running before invoking any of the services.

4.1 Invoking the Retailer client

• Make sure etc/endpoints.props has the correct host and port information.
• Invoke run-retailer.[sh | bat] to invoke the client. This will invoke the getCatalog function from the RetailerService and places the various pre-defined orders to the Retailer Web Service.

4.2 Invoking the Configurator client

• You need to set http.proxyHost and http.proxyPort properties in JWSDP_HOME/conf/jwsdp.properties to the proxy host and port entries so that they specify the system on your network through which you access the Internet. This is required for the JWSDP container to be able to talk to UDDI Business Registry outside the firewall.  
• Invoke run-query.[sh | bat] to invoke the client
• Default behavior of run-query.[sh | bat] is to contact UDDI business registry and generate the endpoints information dynamically. However Configurator Web Service also maintains all endpoints information in a local cache accessible by specifying the following argument when invoking the script
  
  -Dconfigurator.refresh=false 
  
  Specifying this option will not invoke the public UDDI business registry and instead provide you with endpoints information from local cache. This cache is also updated every time UDDI registry is contacted for getting the list of endpoints.
• run-query.[sh | bat] uses the default Configurator Web Service bundled with JWSDP. If you need to use another Configurator Web Service, you need to specify the following argument when invoking the script
  
  -Dconfigurator.endpoint=<ANOTHER_CONFIGURATOR_ENDPOINT>
  
  To obtain other configurator endpoints, configure server-side logging to CONFIG logging level and set "configurator.refresh" to "true". Search server-side logs for "Configurator" keyword and the endpoint address is available in next CONFIG log entry.
• If both -Dconfigurator.endpoint and -Dconfigurator.refresh options are specified, then endpoints information is retrieved in the following manner:

  configurator.refresh	configurator.endpoint	How endpoints are generated
  true	Not specified	Configurator Web Service hosted on JWSDP talks to UDDI registry
  false	Not specified	Local cache from Configurator Web Service hosted on JWSDP
  true	Specified	Remote endpoint talks to UDDI registry
  false	Specified	Remote endpoint's local cache

   

5.0 Building from the source

• Client
  • Go to src directory and invoke ant client command. This will overwrite the existing wsi-client.jar in JWSDP_HOME/wsi-sampleapp/lib directory.
  • Follow the instructions in 4.0 to run the client.
• Server
  • Go to src directory and invoke ant server command. This will overwrite the existing wsi-server.war in JWSDP_HOME/wsi-sampleapp directory.
  • You need to (re)start Java WSDP container explicitly.

6.0 Configuring Logging

You can change the default level of logging for the sample app on the client and server side as follows: 

• Server-side logging: To change the default logging level on server-side (INFO) to a different level, you need to modify wsi-server.war{WEB-INF/conf/logging.properties} file. Follow the steps mentioned below to change the logging level.
  • Extract the contents of the war file in a temporary directory
  • Change the last line in WEB-INF/conf/logging.properties file to 
    
    com.sun.wsi.scm.level=LEVEL
    
    where LEVEL is one of the seven logging levels mentioned above
  • Repackage the war file with the modified logging.properties file
  • Restart the Tomcat server
    
• Client-side logging: To change the default logging level on client-side (INFO) to a different level, change the last line in etc/logging.properties file to
  
  com.sun.wsi.scm.level=LEVEL
  
  where LEVEL is one of the seven logging levels mentioned above

7.0 Troubleshooting

1. All the endpoints are configured in etc/endpoints.props file. The default endpoints are configured for host "localhost" and port "8080". If your application is deployed at a different port, then ensure that these are reflected correctly in etc/endpoints.props.
2. Make sure database server is started before run-retailer script is invoked. If database is started after the script is invoked, you need to restart the JWSDP container.
3. Make sure database is running on the correct host and port and appropriate database has already been created. Refer to section 3.0 for more details.
4. Database related properties are stored in wsi-server.war{WEB-INF/conf/db.props} file. If your database server is running at a different port, change db.url property accordingly. The format of the database URL is "jdbc:pointbase:server://localhost:{port}/wsi" where :{port} may not be specified if it is the default port.
5. If any of the sample app endpoints is outside firewall, you need to specify http.proxyHost and http.proxyPort properties in JWSDP_HOME/conf/jwsdp.properties so that they specify the system on your network through which you access the Internet.
6. You can specify sample app endpoints from other vendors in etc/endpoints.props and create different configurations, comprising of endpoints from different vendors, in etc/vendor-config.xml.  Each of these configurations will be used to place the orders specified in etc/order-config.xml. However if your endpoints are deployed inside firewall, then only Retailer Web Service hosted within the firewall can be mixed with other endpoints installed outside firewall.
7. To view the SOAP request and response messages, turn the logging level to FINE. Refer to section 6.0 on how to configure logging. SOAP request and response messages are available for 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 JWSDP_HOME/logs.

8.0 References

1. WS-I
2. Supply Chain Management Sample Application 1.0 Use Case Model Board Approval Draft
3. Supply Chain Management Sample Application 1.0 Architecture Board Approval Draft
4. Java Logging APIs