| JavaTM Web Services WS-I Supply Chain Management Sample Application 1.0 |
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/configConfiguration 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/wsdlWSDL descriptions for the Web Services. Remote WSDL files, located at wsi.org
src/conf/wsdl.localWSDL descriptions for the Web Services. Local WSDL files
src/javaSource code
wsi-server.earEAR file with all the Web Service endpoints. JSR 109 compliant
logsGenerated 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.proxyHostandhttp.proxyPortproperties 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
--hostand--portoptions.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.earprovided is configured to be used with the PointBase database server.
- A functional version of PointBase is available in the
<install_dir>/pointbasedirectory. This version of PointBase can be used under the licensing terms of the Application Server.- Start the PointBase database server:
- Go to the
<install_dir>/pointbase/tools/serveroptiondirectory and invoke thestartserver.[sh|bat] script.- 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:9092aftercom.pointbase.net.netServer.- Create a database:
- Go to the
AS_HOME/pointbase/tools/serveroptiondirectory and invoke thestartconsole.[sh|bat] script.- If the "Connect to Database" window opens, select "Create New Database". If the "Connect to Database" window does not open, then select the
DBAmenu item from the main menu, then selectCreateand then selectNew Database.
- Accept the defaults for the Driver, User and Password options.
- Change the URL to
jdbc:pointbase:server://localhost/wsi.- Click OK.
- 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 insrc/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 insrc/conf/endpoints.props, and the combination of endpoints is defined insrc/conf/vendor-config.xml.
- Make sure
src/conf/endpoints.propshas the correct host and port information.- In the main directory of the application, type
asant run-retailerto invoke the client. This will invoke thegetCatalogfunction 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.
- You need to set the
http.proxyHostandhttp.proxyPortproperties 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.- The Configurator Web Service performs tasks that require the modification of the default security policy of the server. Make sure to add the following
grantclause to the<install_dir>/domains/<domain_name>/config/server.policyfile 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;
};
- Before running the Configurator Web Service, you need to place the
<install_dir>/lib/jaxr-implp.jarfile 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.jarand 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.- Type
asant run-queryto invoke the client.- 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.xmlfile 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.asant run-queryuses the default Configurator Web Service bundled with this application. If you need to use another Configurator Web Service, you need to modify the mainbuild.xmlfile before invoking the service:
configurator.endpoint=<ANOTHER_CONFIGURATOR_ENDPOINT>
To obtain other configurator endpoints, configure server-side logging to theCONFIGlogging level and setconfigurator.refreshtotrueas described in the previous step. Search the server-side logs for "Configurator" keyword, and the endpoint address is available in the correspondingCONFIGlog entry. Refer to Section 6.0 for details on how to configure logging.- If both the
configurator.endpointand-Dconfigurator.refreshoptions 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 insrc/conf/endpoints.props.
- Make sure
src/conf/endpoints.propshas the correct host and port information.- In the main directory of the application, type
asant run-catalogto invoke the client. This will invoke thegetCatalogWithImagesandgetProductDetailsfunction from the Catalog Web Service.getCatalogWithImagesreturns attachment references of thumbnail images for each product in the catalog.getProductDetailsprovides additional details about each product, a larger product image, and a product spec sheet. The spec sheet and picture are conveyed as SOAP attachments.- The default behavior of
asant run-catalogis to invokegetCatalogWithImagesandgetProductDetailsfor each product in the Catalog. If you need to invoke onlygetCatalogWithImages, you need to modify the following property in the mainbuild.xmlfile of the application before invoking the service:
catalog.level=thumbnail
If you need to invoke onlygetProductDetails, you need to modify the following property before invoking the service:
catalog.level=detailsasant run-cataloguses the default Catalog Web Service bundled with this application. If you need to use another Catalog Web Service, you need to add the endpoint insrc/conf/endpoints.propsin the form
vendor.catalog=ENDPOINT_ADDRESS
whereENDPOINT_ADDRESSspecifies the location of the new Catalog Web Service andvendorcan 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 mainbuild.xmlfile of the application before invoking the service:
catalog.endpoint=vendor
wherevendorneeds to match the"vendor"string specified insrc/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 mainbuild.xmlfile 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.proxyHostandhttp.proxyPortproperties in the mainbuild.xmlfile of the application appropriately before building from the source.
- To build both the client and the server components, go to the main directory of the application and invoke the
asant corecommand. This will create the JSR 109 compliantwsi-server.earWeb service.- Client
- Go to the main directory and invoke the
asant clientcommand.- Follow the instructions in Section 4.0 to run the client.
- Server
- Go to the main directory and invoke the
asant servercommand. This will create a newwsi-server.earfile in thebuilddirectory (the pre-built EAR file is preserved).- To deploy the newly created EAR file, type
asant deploy.- Before deploying the newly created wsi-server.ear file, follow the instructions in item 6 of Before Working With Samples.
6.0 Configuring logging
This application utilizes the Java Logging API [9]. By default, the sample application has its logging level set toINFO. The following levels are available, in ascending order of granularity, and are used in the application as shown below.
Logging Level Usage SEVEREServer-side or client-side exception WARNINGNon-blocking error conditions INFO(default)Basic flow of application CONFIGLogging entries from the Logging Facility FINESOAP request and response messages FINEREntry and exit points of primary methods FINESTIntermediate steps from the primary methods, if any To change the default logging level (
INFO) on the server and client sides to a different level:
- Edit the
JAVA_HOME/jre/lib/logging.propertiesfile used by the server.- Add the following on a new line:
com.sun.wsi.scm.level=LEVEL
whereLEVELis one of the seven logging levels mentioned above.- Restart the container and rerun the client.
7.0 Troubleshooting
- Check that all the container- and database-specific prerequisites are met.
- 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 thesrc/conf/endpoints.propsfile.- Make sure the database server is started before the
run-retailerscript is invoked. If the database is started after the script is invoked, you need to restart the container.- 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.
- 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.- 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.
- You can specify sample application endpoints from other vendors in the
src/conf/endpoints.propsfile and create different configurations, comprised of endpoints from different vendors, insrc/conf/vendor-config.xml. Each of these configurations will be used to place the orders specified insrc/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.- 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
- WS-I
- Supply Chain Management Sample Application 1.0 Use Case Model Board Approval Draft
- Use Cases for Attachments Sample Applications 1.0 (Editor's Draft - not publicly available yet)
- Supply Chain Management Sample Application 1.0 Architecture Board Approval Draft
- Technical Architecture for Attachments Sample Applications 1.0 (Editor's Draft - not publicly available yet)
- Basic Profile 1.1 Working Group Draft
- Simple SOAP Binding Profile 1.0 Working Group Draft
- Attachments Profile 1.0 Working Group Draft
- Java Logging APIs