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/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
andhttp.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.
- 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.- Start the PointBase database server:
- Go to the
<install_dir>/pointbase/tools/serveroption
directory 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:9092
aftercom.pointbase.net.netServer
.- Create a database:
- Go to the
AS_HOME/pointbase/tools/serveroption
directory 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
DBA
menu item from the main menu, then selectCreate
and 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.props
has the correct host and port information.- In the main directory of the application, type
asant run-retailer
to invoke the client. This will invoke thegetCatalog
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.
- You need to set the
http.proxyHost
andhttp.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.- 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;
};
- 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.- Type
asant run-query
to 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.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.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 mainbuild.xml
file before invoking the service:
configurator.endpoint=<ANOTHER_CONFIGURATOR_ENDPOINT>
To obtain other configurator endpoints, configure server-side logging to theCONFIG
logging level and setconfigurator.refresh
totrue
as described in the previous step. Search the server-side logs for "Configurator" keyword, and the endpoint address is available in the correspondingCONFIG
log entry. Refer to Section 6.0 for details on how to configure logging.- 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 insrc/conf/endpoints.props
.
- Make sure
src/conf/endpoints.props
has the correct host and port information.- In the main directory of the application, type
asant run-catalog
to invoke the client. This will invoke thegetCatalogWithImages
andgetProductDetails
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.- The default behavior of
asant run-catalog
is to invokegetCatalogWithImages
andgetProductDetails
for each product in the Catalog. If you need to invoke onlygetCatalogWithImages
, you need to modify the following property in the mainbuild.xml
file 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=details
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 insrc/conf/endpoints.props
in the form
vendor.catalog=ENDPOINT_ADDRESS
whereENDPOINT_ADDRESS
specifies the location of the new Catalog Web Service andvendor
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 mainbuild.xml
file of the application before invoking the service:
catalog.endpoint=vendor
wherevendor
needs 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.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
andhttp.proxyPort
properties in the mainbuild.xml
file 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 core
command. This will create the JSR 109 compliantwsi-server.ear
Web service.- Client
- Go to the main directory and invoke the
asant client
command.- Follow the instructions in Section 4.0 to run the client.
- Server
- Go to the main directory and invoke the
asant server
command. This will create a newwsi-server.ear
file in thebuild
directory (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 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:
- Edit the
JAVA_HOME/jre/lib/logging.properties
file used by the server.- Add the following on a new line:
com.sun.wsi.scm.level=LEVEL
whereLEVEL
is 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.props
file.- 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.- 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.props
file 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