Java^TM Webservices (JAX-WS) Ebay Example

Introduction

The Webservices Ebay example is an application that shows how to use the JAX-WS API. The example shows how to access Ebay services via their web service interface. To use this sample you must first register with Ebay and get the appId, certId, devId and authToken and put the appropriate values in the ebay.properties file. You can register at http://developer.ebay.com/developercenter/soap/ to get the keys. It is recommended to use the sandbox environment provided by Ebay to run the sample. First you need to create and validate a sandbox test account and then generate a single user authentication token. Also note at the time this sample was written and tested the version of eBaySvc.wsdl was 455. For convinience the wsdl file is bundled.

The JAX-WS Ebay example does not however implement the full fledged logic that such an application might have. It implements a subset of this logic which is sufficient to demonstrate common patterns and solutions used when implementing a web service and interface for an application with JAX-WS Technology.

---

Note: This example was developed using NetBeans 5.5 IDE. The instructions given in this document to build and run the example assume that you have at your disposal:

• either NetBeans 5.5 IDE and
• or Apache Ant 1.6.5

---

Table Of Contents:

[Generating the Java Documentation] [Overview of the Ebay Example] [API Documentation and Sources] [Running the Ebay Example] [Conclusion] [References]

Generating the Java Documentation

Before reading further, you will need to generate the Java Documentation for the example's sources.

The example has two parts to it - the client and the server. In the sample root directory there are two directories - EbayClient and EbayServer. Run the following command in both the directories

ant

Alternatively you can open the EbayClient and EbayServer project with the NetBeans IDE and generate the Javadoc from its Build menu.

Overview of the Ebay Example

The Ebay sample has two parts to it - EbayClient and the EbayServer.
• EbayClient demonstrates how you can use a webservice client to access an ebay service - in this case to lookup an item based on the item id. The client uses the eBaySvc.wsdl file to generate stubs and proxy classes by running the wsimport tool in the ebay.apis package that it then uses in the application to make calls to either the Ebay site or to the local server. The MainGUIApp class in the ebay.client package is the main class to run the example. The application is a swing application that lets you select which server to query and also set preferences for http proxy incase you are behind a firewall. There is also a JAX-WS handler in the ebay.client.handler package - RequesterCredentials. The Ebay wsdl uses additional headers that is defined in the binding section of the WSDL. This concept is currently not supported by the JAX-WS implementation and hence we insert the additional header using a JAX-WS protocol handler. We use the RequesterCredentials handler to get access to the entire soap message and then add the required soap headers to query the ebay web service.

  Note: When building the application you will see a lot of warnings like

  [exec] warning: cos-nonambig: "urn:ebay:apis:eBLBaseComponents"
                :eBayAuthToken and WC[##any] (or elements from their substitution 
                group) violate "Unique Particle Attribution". During validation 
                against this schema, ambiguity would be created for those two 
                particles

  when the wsimport tool is being executed. This is because the ebay wsdl has schema definitions that cause these warnings to be generated. Note however the example will run just fine.

• EbayServer demonstrates how you can build a service like ebay starting from a wsdl. In general though the recommended practice for building a service is to start from Java and use annotations to define the service and then use that service to generate a wsdl file for clients to use. However in this case since there might be a need to be able to access the service locally in the sample we are using the same wsdl to show how you can build the service as well. The eBaySvc.wsdl file is used to to generate stubs and proxy classes by running the wsimport tool in the ebay.apis package that it then uses in the server side application to serve up requests. The example uses the Java SE 6 light weight web server to host the endpoint. The Ebay class in the ebay.server package is the class that contains the item information. Note for the purpose of the example we have used a HashMap to store the information. The server side example also demonstrates how you can use JAX-WS for REST based web services. In Java SE 6 the web server does not have the capability to serve files from the file system. So we have implemented the ImageProvider service to serve up images using the REST style web services. The Main class is the main class of the application that starts up the two endpoints to serve up the requests. When using the client with the local server at this time the item id values supported are 1 or 9720685987, 2 or 9723025228, 3 or 9722594617

API Documentation and Sources

Once generated, the Javadoc of example classes can be found starting from dist/javadoc/index.html. and ../EbayServer/dist/javadoc/index.html.

You can view the sources in the src and ../EbayServer/srcsubdirectories.

Running the Ebay Example

To run the client you need to be in the EbayClient directory and execute the following commands:

ant run

Alternatively you can open the EbayClient project with the NetBeans IDE and right click on the EbayClient project and select Run project

Note: You can also run the EbayClient application directly from the java command line. Make sure to build the EbayClient jar first.
On Unix systems:

ant jar
cd dist
java -jar EbayClient.jar


On Windows systems:

ant jar
cd dist java -jar EbayClient.jar

If you want to run the EbayServer so that you can access the server side functionality as well on the local machine then you need to be in the EbayServer directory and execute the following commands:

ant run

Alternatively you can open the EbayServer project with the NetBeans IDE and right click on the EbayServer project and select Run project

Note: You can also run the EbayServer application directly from the java command line. Make sure to build the EbaySever jar first.
On Unix systems:

ant jar
cd dist
java -jar EbayServer.jar


On Windows systems:

ant jar
cd dist java -jar EbayServer.jar

Conclusion

In this document, we have presented an advanced JAX-WS example. We have shown how you can build a client to access a web service starting from a WSDL file. We have also demonstrated how to use Handler in the client to add additional information to messages. We have also demonstrated how to build a service for a corresponding wsdl and how to enable REST services using JAX-WS.

References

1. JAX-WS home page
2. JAX-WS java.net project
3. Java SE 6 Documentation Index: This document covers the Java^TM Platform, Standard Edition 6.