Webservices "Ebay" Example

#
JavaTM 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/src`subdirectories.

## 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 JavaTM Platform, Standard Edition 6.