WS-I Attachments Sample Application 1.0 EA

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
      3.1 Container
      3.2 Database
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 the 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

This section explains the directory structure

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

3.0 Pre-Requisites

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

3.1 Container Configuration

3.1.1 Sun Java System Application Server 8.0 Platform Edition (recommended)

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 --host and --port options. 

3.1.2 Sun Java System Web Server 6.1

Configure the http.proxyHost and http.proxyPort properties for the container

1. On the administration page for the virtual server, click on the "Java" tab.
2. Select the "JVM Options" from the left panel.
3. Specify -Dhttp.proxyHost=<your-proxy-host> in the first empty text box next to "Add" and click on OK.
4. Specify -Dhttp.proxyPort=<your-proxy-port> in the first empty text box next to "Add" and click on OK.
5. Specify -Djava.awt.headless=true in the first empty box next to "Add" and click on OK. This will enable the headless operation for AWT images involved in the Catalog Web Service.
6. Click on "Apply" on the top-right corner of the administration page for the changes to take effect.

3.1.3 Tomcat

1. If Tomcat container is running, stop it.
2. In your conf/server.xml, set the unpackWARs attribute to true in the Engine element with the Host element whose host attribute is localhost.
   1. 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 TOMCAT_HOME/webapps directory by the war file name. To redeploy an app, the exploded directory needs to be removed from TOMCAT_HOME/webapps directory before starting the Tomcat container. 
3. If HTTP proxy host and port are not configured during Tomcat installation, configure the http.proxyHost and http.proxyPort properties for the container
   1. Add http.proxyHost=<your-proxy-host> on a new line to TOMCAT_HOME/conf/jwsdp.properties.
   2. Add http.proxyPort=<your-proxy-port> on a new line to TOMCAT_HOME/conf/jwsdp.properties.

3.2 Database configuration

Pointbase database is recommended when Sun Java System Application Server 8.0 Platform Edition is the chosen container. MySQL database is recommended when Sun Java System Web Server 6.1 or Tomcat is the chosen container. The JWSDP_HOME/wsi-sampleapp/wsi-server.war is configured to be used with the Pointbase database server. The steps to reconfigure the WAR file for MySQL database are given in section 3.2.2 below.

3.2.1 Pointbase database

1. A functional version of pointbase is available in AS_HOME/pointbase directory, where AS_HOME is the installation directory of Sun Java System Application Server 8.0 Platform Edition (SJSAS 8.0PE). This version of pointbase can be used under the licensing terms of SJSAS 8.0 PE.
2. Start the Pointbase database server
   1. Go to AS_HOME/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 AS_HOME/pointbase/tools/serveroption directory and invoke the startconsole.[sh | bat] script.
   2. If "Connect to Database" window opens up, select "Create New Database". If "Connect to Database" window does not open up, then select DBA menu item from the main menu, then select Create and then select New Database.
      1. Take the defaults for Driver, User and Password options.
      2. Change the URL to jdbc:pointbase:server://localhost/wsi.
      3. Hit OK.
   3. Click on File - Exit to leave the database connection window.
4. Copy the jar file containing the JDBC driver in the container
   • For Sun Java System Application Server container: Copy AS_HOME/pointbase/lib/pbclient.jar to AS_HOME/domains1/domain1/lib/ext directory.
   • For Sun Java System Web Server 6.1 container
     1. Edit the server.xml for the instance chosen during Java WSDP installation. Typically this file will be in https-<your-server-name>/config directory where <your-server-name> is the name of your server on which Sun Java System Web Server 6.1 is installed.
     2. Search for classpathsuffix attribute.
     3. Add the absolute path of the jar file at the end of the value of classpathsuffix attribute.
   • For Tomcat container: Copy the jar file in TOMCAT_HOME/common/lib.
5. If the app has been configured for the MySQL database earlier and now needs to be configured with the Pointbase database, then go to JWSDP_HOME/wsi-sampleapp/src directory and invoke the repackage-war target. Invoke the deploy.wsi-sampleapp.webapps target on the integration script for your container. This script is available in
   • JWSDP_HOME/jwsdp-shared/bin/jwsdponsjsas.[sh | bat] for Sun Java System Application Server
   • JWSDP_HOME/jwsdp-shared/bin/jwsdponsjsws.[sh | bat] for Sun Java System Web Server
   • JWSDP_HOME/jwsdp-shared/bin/jwsdpontomcat.[sh | bat] for Tomcat

   For instance for Sun Java System Application Server installed in /opt/SUNWappserver directory, this script is invoked as:
   
JWSDP_HOME/jwsdp-shared/bin/jwsdponsjsas.sh /opt/SUNWappserver deploy.wsi-sampleapp.webapps

3.2.2 MySQL database

MySQL database is recommended when Sun Java System Web Server 6.1 or Tomcat is the chosen container.

1. MySQL can be downloaded from www.mysql.com/downloads. A standard MySQL installation using the binary distribution is recommended.
2. Start the MySQL database server
   • On a Unix-like platform
     1. Go to MYSQL_HOME directory and invoke the /bin/mysqld_safe script, where MYSQL_HOME is the installation directory of MySQL database. As per MySQL documentation, mysqld_safe is the recommended way to start a mysqld server on Unix and NetWare. Refer to The mysqld_safe Server Startup Script for more details.
        • This script needs to be invoked from MYSQL_HOME and specifying the path as ./bin/mysqld_safe.
     2. Make sure that the database server is listening on port 3306. The port number can be found by invoking the ./bin/mysqladmin variables command from MYSQL_HOME directory and looking for the value of port variable. Otherwise you can change the port number by invoking the script as  ./bin/mysqld_safe --port=3306.
   • On a windows platform
     1. Go to MYSQL_HOME/bin directory and invoke the command mysqld --console. Refer to Installing MYSQL on Windows for more details.
     2. Make sure that the database server is listening on port 3306. The port number can be found by invoking the mysqladmin variables command from MYSQL_HOME/bin directory and looking for the value of port variable. Otherwise you can change the port number by specifying port=3306 on a new line in %WINDIR%/my.ini.
3. Create a database
   • On a Unix-line platform
     1. Go to MYSQL_HOME directory and invoke the ./bin/mysql script.
     2. This script needs to be invoked from MYSQL_HOME and specifying the a user name with database creation privilege as ./bin/mysql --user=root. root is a default user, you may choose an alternate user which has the permissions to create a database. This gives a mysql prompt.
   • On a Windows platform
     1. Go to MYSQL_HOME/bin directory and invoke mysql script. The default MySQL user in windows seems to have permission to create a database. You my choose an alternate user which has the permissions to create a database. If you happen to choose an alternate user, you need to modify JWSDP_HOME/wsi-sampleapp/etc/mysql.db.props file with the correct values for user and password fields. This gives a mysql prompt.
   • At the mysql prompt, enter create database wsi; command and hit Enter.
   • Type quit; on the mysql prompt to quit the script.
4. Download the JDBC driver (Connector/J) for MySQL from www.mysql.com/downloads/api-jdbc.html. The JDBC driver jar file is named after the pattern mysql-connector-java-<version>-<release>-bin.jar where <version> is the version number of the Connector/J and <release> indicates whether it's a stable, alpha or old release.
   • For Sun Java Systems Application Server 8.0 container: Copy the jar file in SJSAS_HOME/domains/domain1/lib/ext directory, if domain1 is the chosen domain.
   • For Sun Java System Web Server 6.1 container
     1. Edit the server.xml for the instance chosen during Java WSDP installation. Typically this file will be in https-<your-server-name>/config directory where <your-server-name> is the name of your server on which Sun Java System Web Server 6.1 is installed.
     2. Search for classpathsuffix attribute.
     3. Add the absolute path of the jar file at the end of the value of classpathsuffix attribute.
   • For Tomcat container: Copy the jar file in TOMCAT_HOME/common/lib.
5. Go to the JWSDP_HOME/wsi-sampleapp/src directory and invoke the repackage-war target as follows
   
   ant repackage-war -Ddatabase=mysql
6. Invoke the deploy.wsi-sampleapp.webapps target on the integration script for your container. This script is available in
   • JWSDP_HOME/jwsdp-shared/bin/jwsdponsjsas.[sh | bat] for Sun Java System Application Server
   • JWSDP_HOME/jwsdp-shared/bin/jwsdponsjsws.[sh | bat] for Sun Java System Web Server
   • JWSDP_HOME/jwsdp-shared/bin/jwsdpontomcat.[sh | bat] for Tomcat

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.1 or 3.2.2.

4.1 Invoking the Retailer client

1. Make sure etc/endpoints.props has the correct host and port information.
2. Invoke JWSDP_HOME/wsi-sampleapp/bin/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

1. You need to set http.proxyHost and http.proxyPort properties for your container to allow the container to be able to talk to UDDI Business Registry outside the firewall. Refer to section 3.1 for container specific configuration.
2. Invoke JWSDP_HOME/wsi-sampleapp/bin/run-query.[sh | bat] to invoke the client.
3. 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
4. run-query.[sh | bat] uses the default Configurator Web Service bundled with Java WSDP. 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 as described in the previous step. Search 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.
5. 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 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

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.

1. Make sure etc/endpoints.props has the correct host and port information.
2. Invoke JWSDP_HOME/wsi-sampleapp/bin/run-catalog.[sh | bat] to invoke the client. This will invoke the getCatalogWithImages and getProductDetails function from the Catalog Web Service. getCatalogWithImages return 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. Default behavior of run-catalog.[sh | bat] is to invoke getCatalogWithImages and getProductDetails for each product in the Catalog. If you need to invoke only getCatalogWithImages, you need to specify the following argument when invoking the script
   
   -Dcatalog.level=thumbnail
   
   If you need to invoke only getProductDetails, you need to specify the following argument when invoking the script
   
   -Dcatalog.level=details
4. run-catalog.[sh | bat] uses the default Catalog Web Service bundled with JWSDP. If you need to use another Catalog Web Service, you need to add the endpoint in etc/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 following argument when invoking the script
   
   -Dcatalog.endpoint=vendor
   
   where vendor needs to match the "vendor" string specified in JWSDP_HOME/wsi-sampleapp/etc/endpoints.props.

5.0 Building from the source

• Client
  1. Go to src directory and invoke ant client command. This will overwrite the existing wsi-client.jar in JWSDP_HOME/wsi-sampleapp/lib directory.
  2. Follow the instructions in 4.0 to run the client.
• Server
  1. Go to src directory and invoke ant server command. This will overwrite the existing wsi-server.war in JWSDP_HOME/wsi-sampleapp directory.
     • By default, the Pointbase database configuration file is bundled in the WAR file. If MySQL database configuration file needs to be bundled instead, add -Ddatabase=mysql property when invoking the ant target.
  2. Invoke deploy.wsi-sampleapp.webapps target on the integration script for your container. This script is available in
     • JWSDP_HOME/jwsdp-shared/bin/jwsdponsjsas.[sh | bat] for Sun Java System Application Server
     • JWSDP_HOME/jwsdp-shared/bin/jwsdponsjsws.[sh | bat] for Sun Java System Web Server
     • JWSDP_HOME/jwsdp-shared/bin/jwsdpontomcat.[sh | bat] for Tomcat

6.0 Configuring Logging

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

1. Edit JAVA_HOME/jre/lib/logging.properties file.
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 re-run the client.

7.0 Troubleshooting

1. Check that all the container- and database-specific pre-requisites are met.  
2. 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 the etc/endpoints.props file.
3. Make sure the database server is started before run-retailer script is invoked. If 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 JWSDP_HOME/wsi-sampleapp/etc/[mysql | pointbase].props. If you need to modify any of the database configuration properties, edit the .props file specific to your database and invoke ant repackage-war -Ddatabase=[pointbase | mysql] target from the JWSDP_HOME/wsi-sampleapp/src directory.  And then invoke the deploy.wsi-sampleapp.webapps target on the integration script for your container.
6. 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.
7. You can specify sample app endpoints from other vendors in the etc/endpoints.props file 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/retailer-config.xml. However if your endpoints are deployed inside firewall, then only Retailer Web Service hosted within the firewall can be mixed with the other endpoints installed outside firewall.
8. To view the SOAP request and response messages, turn 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 Retailer, Logging and Configurator clients as given below:
   • Retailer client SOAP request and response messages are available in the logs/retailer-soap-messages.txt.
   • Logging client SOAP request and response messages are available in the logs/logging-soap-messages.txt.
   • Configurator client SOAP request and response messages are available in the 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