eBay SDK for Java (JAX-WS) Readme

Please note the following important information:

This is the Readme for the JAX-WS eBay SDK for Java.
Support for the Axis 1.1 eBay SDK for Java has been discontinued.
Before using a version of the SDK, please read the most recent version of this Readme file, available at the Java Developer Center.
Upgrades to an SDK version should always be done in a test environment.
Testing for the SDK includes testing with IBM JDK 1.5. Some components may be incompatible with IBM JDK 1.5. If you are using IBM JDK 1.5, copy all JAR files from SDKIntallDir\externalLib\jaxp-1.4.2 into the application's classpath. Please post issues with IBM JDK 1.5 in the Java SDK Forum.
Point releases, unlike full releases, do not go through the typical, full rounds of quality assurance. Point releases for Linux are not regularly tested before release. Point releases include bug fixes and updates to the wrapper classes.
The most recent full SDK release is this eBay SDK 639 for Java Full Release.
You can download SDK releases from the eBay SDK for Java download page.
For Trading API versions released after your current version, please read the Trading API Release Notes (which contain tables showing schema changes that occur every two weeks).
The eBay SDK for Java only supports JDK 1.5 and releases later than JDK 1.6.0_03. If you are using a version of JDK 1.6 that was released before Update 3 of JDK 1.6, either update to the latest JDK 1.6 version or:
- Copy SDKIntallDir/externalLib/jaxws-ri-2.1.4/jaxws-api.jar to JDK6_HOME/jre/lib/endorsed
- Copy SDKInstallDir/externalLib/jaxws-ri-2.1.4/jaxb-api.jar to JDK6_HOME/jre/lib/endorsed
  Note: You may have to create the destination folder.

Contents
Release Information for the eBay SDK for Java
Installation Instructions
General Information for the eBay SDK for Java

Release Information for the eBay SDK for Java

Important: Changes to the Trading API affect the SDK. For example, in schema version 499, deprecated objects in the schema were deleted, creating backward incompatibility. See the Trading API Release Notes for ongoing updates to the schema (including occasional removals of schema elements). Please also see Versioning Strategy and Deprecated Objects.

SDK Version 639 for Java Full Release

SDK Version 631 for Java Full Release

SDK Version 623 for Java Point Release

SDK Version 615 for Java Full Release

SDK Version 603 for Java Point Release

SDK Version 595 for Java Full Release

SDK Version 581 for Java Beta Release

SDK Version 575 for Java Beta Release

SDK Version 561 and Subsequent Point Releases

Previous SDK Releases

SDK Version 639 for Java Full Release

This release is compatible with eBay's 639 Trading WSDL, and contains support for the following new features:

Simplified Java attributesDemo Sample

The Java attributesDemo sample has been simplified. This sample simulates a simple sell your item(SYI) flow, it shows how to use eBay API/SDK to:

Handle item attributes/specifics.
Handle eBay meta-data such as listing type/duration, payment methods, shipping service, etc.
Cache eBay meta-data on local driver.

For detailed architecture and call flow of the sample, please refer to the readme in the sample folder.

Setting Up JavaSDK in Eclipse

The eclipse project files for JavaSDK have been updated, all absolute references (library, source, jdk) have been changed to relative references, now all projects can be imported into eclipse environment without additional reference updates.

For instructions about how to setup JavaSDK in Eclipse, please refer to the DevEnvReadme in SDK root folder.

SDK Version 631 for Java Full Release

This release is compatible with eBay's 631 Trading WSDL, and contains support for the following new features:

New Helper Class for HTTP Proxy Settings

A new class, SdkProxySelector.java, is included in this release for those who access the eBay API using a proxy server and want to configure the proxy settings programmatically. For examples of usage, please refer to the apiCallsDemo sample.

New DetailsDownloader Helper Class

The new DetailsDownloader.java, helper class shows you how to cache eBay details locally.

Most Calls Can Be Made with Tokens Only

With the exception of, GetTokenStatus, RevokeToken, GetSessionID, and FetchToken, all SDK API calls can now be made with an eBay API developer token (instead of full eBay API developer credentials.)

SDK Version 623 for Java Point Release

This release is compatible with eBay's 623 Trading WSDL, and there are no new features.

SDK Version 615 for Java Full Release

This release is compatible with eBay's 615 Trading WSDL, and contains support for the following new features:

Support for the AddFixedPriceItem Family of Calls

Four new classes, AddFixedPriceItem.java, ReviseFixedPriceItem.java, RelistFixedPriceItem.java and AddFixedPriceItem.java, have been added in this release. These classes can be used as single calls within a Java method, or they can be used within data files in the Large Merchant Services solution.

SDK Version 603 for Java Point Release

This release is compatible with eBay's 603 Trading WSDL, and contains support for the following new features:

New Helper Classes

Two new helper classes, CategoriesDownloader.java and FeaturesDownloader.java, have been added in this release. The CategoriesDownloader.java class caches eBay Category information to a local disk. The FeaturesDownloader.java class caches the eBay Category Feature information to a local disk. Using these classes, you can access category information without repeatedly making GetCategory and GetCategoryFeatures requests.

Updated AttributesDemo Samples to Cache Meta-data

The AttributesDemo sample has been updated to take advantage of the new helper classes, so that you can see how to cache the eBay categories and features in a local repository.

eBayAccount Class Returned

The eBayAccount class was removed as part of a code clean-up in Release 595. It has been added back into the code for this release. It is also available as a downloadable patch for Release 595.

SDK Version 595 for Java Full Release

This release is compatible with eBay's 595 Trading WSDL, and contains support for the following new features:

Migrating from Axis 1.1 to JAX-WS

In this release, the eBay SDK for Java has been migrated from Axis 1.1 to JAX-WS for use with production code. We recommend that you upgrade your production applications from the Axis version of the eBay SDK for Java to the JAX-WS version. For more information, please see Migrating to the JAX-WS eBay SDK for Java.

UploadSiteHostedPicture

Since the classes in the eBay Picture Service (EPS) have been replaced by the UploadSiteHostedPictures Trading API (XML) call, the Java SDK now supports the UploadSiteHostedPictures call. Because this is a Trading API call, you will need to provide an eBay developer authorization token (that you obtain with your application keys) when making this call.

The UploadSiteHostedPictures call is the only call in the Trading API that doesn't support SOAP. Therefore, you need to use the following (XML) endpoints (Gateway URLs):

For the Sandbox, use: https://api.sandbox.ebay.com/ws/api.dll
For Production, use: https://api.ebay.com/ws/api.dll

In addition, it is important that you use these endpoints for both the production and sandbox environments. The addresses for both environments must be consistent because you will need to update the authorization token in your ApiContext class before switching from one platform to the other (Trading API (XML) and SDK servers use different authorization keys.)

You can still use the EPS libraries with this release, but they will eventually be discontinued, so we recommend that you migrate to the newer call as soon as you can. The UploadSiteHostedPictures call enables you to upload files in image formats such as JPG by including a binary attachment after the XML input, as part of the request. The call returns SiteHostedPictureDetails.FullURL, which must be stored by your application (for associating the picture using the Item.PictureDetails.PictureURL field of AddItem, ReviseItem, or RelistItem).

For more information, please see the following:

UploadSiteHostedPictures in the Input/Output Reference
Sample UploadSiteHostedPictures Call in the Knowledge Base

Selling Manager Pro (SMP) calls are supported in this release.

Support for ProPay

This release also includes support for the ProPay payment method. ProPay is a third party application that allows small businesses to accept credit cards. For more information about ProPay, see www.ProPay.com. For more information about accepted eBay payment methods, see BuyerPaymentMethodCodeType in the Trading Call Reference.

Updates to SDK Samples

An updated JSP attributeDemo sample includes return policy information that is integrated with the rest of the Item details, instead of being posted on a separate page. It also includes a dynamic lookup feature for Shipping Service, Payment Methods, Listing Type, and Listing Duration. This sample demonstrates the usage of eBay Custom Item Specifics with the Trading API GetCategoryFeatures and GetCategorySpecifics calls.

Some SDK samples have been updated based on recent API features. Please note that for Return Policy and for the requirement to specify shipping, some samples contain hard-coded fields. Therefore, if you want to change the target site used in the sample, you must integrate GetCategoryFeaturesCall and GeteBayDetailsCall into the sample. For important information, see the Trading API Release Notes and the eBay Trading Web Services section of the Developer Documentation Center.

Documentation of Recent API Features

For important information about the latest API features, including new requirements for listings, please see the Trading API Release Notes and the eBay Trading Web Services section of the Developer Documentation Center.

Removal of Legacy XML Classes

As of this release, all legacy XML classes and calls have been removed. The new UploadSiteHostedPictures call is the only remaining XML call.

SDK Version 581 for Java Beta Release

Migrating from Axis 1.1 to JAX-WS

In this second Beta release, the eBay SDK for Java has been migrated from Axis 1.1 to JAX-WS. For more information, please see Migrating to the JAX-WS eBay SDK for Java (Beta Release).

Documentation of Recent API Features Available

Recent API Feature Updates

The eBay SDK for Java contains updated wrapper classes, updated test cases, and other updates that facilitate your use of recent API features. Changes include updates to user token retrieval and deprecation of eBay Express.

Updates to SDK Samples

Some SDK samples are updated based on recent API features. Please note that for Return Policy and for the requirement to specify shipping, some samples contain hard-coded fields. Therefore, if you want to change the target site used in the sample, you must integrate GetCategoryFeaturesCall and GeteBayDetailsCall into the sample. For important information, see the Trading API Release Notes and the eBay Trading Web Services section of the Developer Documentation Center.

SDK Version 575 for Java Beta Release

Migration from Axis 1.1 to JAX-WS

In this release, the eBay SDK for Java has been migrated from Axis 1.1 to JAX-WS. This migration includes changes to the SDK core classes, wrapper classes, samples, and test cases. Stubs and datatypes are now generated with the wsimport tool under the JAX-WS standard, and this process is automated as before by using Ant (the name of the buildfile is build.xml). For more information, please see Migrating to the JAX-WS eBay SDK for Java.

SDK Version 561 and Subsequent Point Releases

SDK Version 561 Was Based on Axis 1-1

SDK version 561, and earlier SDK versions, were based on Axis 1-1.

Handling of Unrecognized Data Values

A new StubModifier tool is used to handle unrecognized enum values received in a SOAP response. The tool post-processes the stubs generated by Apache Axis WSDL2Java. The tool contains the StubModifier class, located in ...\source\Tools\StubModifier\src\tools\webservices\wsdl\stubutil\StubModifier.java.

User Authentication Improvements

The eBay SDK for Java includes the user-authentication improvements released with Trading API version 557. For information about these improvements, see the Release Notes for version 557 of the Trading API and see Authentication and Authorization.

The SDK changes include 3 new wrapper classes (GetSessionIDCall, GetTokenStatusCall, and RevokeTokenCall) and new FetchTokenCall functionality. Please use the new FetchTokenCall functionality in your application. The apiCallsDemo and signinRedirect samples are updated with the new FetchTokenCall functionality. Additionally, the apiCallsDemo is updated to show uses of GetTokenStatusCall and RevokeTokenCall.

Documentation of Recent API Features Available

For information about the latest API features, please see the Trading API Release Notes and the eBay Trading Web Services section of the Developer Documentation Center.

Previous Java SDK Releases

For information about previous versions, see the Axis 1.1 Java SDK Readme.

Installation Instructions

Please note that upgrades to an SDK should always be done in a test environment and fully tested before used in production.

Download the zip file for the version of the eBay SDK for Java that you are using (JDK 1.5 or JDK 1.6).

Note the location of the zip file you downloaded, but before extracting the file, create the following folder: C:\eBayJavaSDK.

Within C:\eBayJavaSDK, create an "SDKInstallDir" folder to contain the SDK files. You could name that folder according to the Trading API version of the SDK you are installing. For example, for the SDK for Trading API version 575, you could name the folder eBayJavaSDK575.

Go the location of the zip file you downloaded (noted in step 3), and extract the zip file into the SDKInstallDir folder you created in step 4.

To build the SDK, see Building the SDK.(If you're using an Integrated Development Environment (IDE), you do not need to build the SDK, you just need to set the paths to point to the correct libraries and files. See C:\eBayJavaSDK\SDKInstallDir\DevEnvReadme.htm for more information for configuring an IDE)

General Information for the eBay SDK for Java

Development Requirements

Post-Installation Configuration

Included in the eBay SDK for Java

WSDL Locations

WSDL Updates

Supported Client Environments

Development Requirements

J2SE 5.0 (JDK 1.5.x) or Java SE 6 (JDK 1.6.x).
Apache ANT -- Download from http://ant.apache.org/; Ant version 1.6.x or higher is required for all JDKs used with this release.
JAX-WS RI (Reference Implementation) 2.1.4 -- The version downloaded to SDKInstallDir (the installation directory) at ..\SDKInstallDir\externalLib\jaxws-ri-2.1.4\ is the standard (non-customized) version available at the official JAX-WS RI website. You must compile the beta release with this version of the JAX-WS RI. See Installation Instructions for more information about the installation directory.
For more information on supported client environments, please see Supported Client Environments.
It is recommended that you use the latest Eclipse integrated development environment (IDE) for the migration, although you can use any IDE for this release that supports the client environments above. Project files for Eclipse are provided in the installation directory. Please see ..\SDKInstallDir\DevEnvReadme.htm for instructions on using these included project files with Eclipse after installing the JAXB release.
(optional) Jakarta Tomcat 5.5, if you wish to build the Java Server Pages (JSP) samples.

Post-Installation Configuration

Note:

Update and run setenv.bat(int ..\SDKInstallDir\)is necessary only if you want to build the SDK source or run SDK samples from the command line (in a command window).

Modify and run the ..\SDKInstallDir\setenv.bat file as follows:

After upgrading to Apache Ant 1.6.x, or higher, modify the ..\SDKInstallDir\setenv.bat file by adding the bin directory of your ANT installation to the PATH environment variable.
Modify the ..\SDKInstallDir\setenv.bat file so that the JAVA_HOME environmental variable is set to either the JDK 1.5.x or JDK 1.6.x directory.
(Optional) If you have installed Jakarta Tomcat, set the TOMCAT_HOME environment variable in ..\SDKInstallDir\setenv.bat to the Jakarta Tomcat location. This step is required only if you wish to run the included JSP samples using Tomcat.
Make sure to run ..\SDKInstallDir\setenv.bat from a command window.

If you are using the Fedora 8 operating system, install the following patches in order to use the Swing/AWT-based samples in the SDK:

SDK-Related Links

Building the SDK

In this section, you will use an ANT project file, build.xml, to do the following:

Create source code from an eBay WSDL.
Compile SDK source code.
Create .jar files (such as ebaysdkcore.jar and ebaycalls.jar) for SDK libraries.

Note:

Building SDK is necessary only for advanced users who have added customization to the SDK source or need to synchronize the source with a new version of eBay Web Services Definition Language(WSDL).

To build the SDK, use the following steps:

Review and follow all the steps in the Installation Instructions

In a command window, change the directory to the SDKInstallDir described in the Installation Instructions

In SDKInstallDir, follow the instructions in Post-Installation Configuration to change 'JAVA_HOME' in the 'setenv.bat' file according to your local JDK installation, then run 'setenv.bat' in command line.

In the same command window, in SDKInstallDir, run the following command: ant build,
(for a list of available ant tasks, run: ant help)

When a new WSDL is available, advanced users can use it to update the SDK:
1. Read the Trading API Release Notes. The Release Notes contain changes for Trading API versions released after your current version. The Release Notes are located at the Developer Documentation Center.
2. Download the new WSDL(see WSDL Locations) you want to use to SDKInstallDir\wsdl folder.
3. At a command prompt, from ...\SDKInstallDir, run the following command:
  ant build

Documentation

For the Trading Web Services API Guide, the Trading API Release Notes, and other API documentation (such as the Input/Output Reference and information about API versions), please see the Java Developer Center.
For the Library Reference (javadoc), which includes documentation for the classes in the SDK, please see the following folder: ...\SDKInstallDir\docs\LibRef.
SDK-related items containing sample code are available in the Knowledge Base, e.g. Uploading local pictures using Java SDK.

Known Issues

If your eBay SDK for Java application uses GetCategoriesCall to retrieve categories, make sure you set aside a large amount of memory for the Java virtual machine. If the application incurs Out of Memory errors, you should increase the amount of memory dedicated to the JVM.
Since the wsimport tool cannot generate 'RecipientRelationCodeType' as a Java Enum type from the eBay WSDL, use Java 'String' type instead whenever a 'RecipientRelationCodeType' is expected.

Included in the eBay SDK for Java

lib: jar files for eBay SDK for Java:
- ebaysdkcore.jar: the core library
- ebaycalls.jar: the API wrapper library
- eps.jar: the eBay Picture Service library
- attributes.jar: the eBay Attributes API library
- helper.jar: the helper library used in the SDK
externalLib: JAX-WS RI library files. You must compile the SDK with version 2.1.4 of Sun JAX-WS RI.
documentation: Library Reference (javadoc). Note: Also see the documentation at the following location: http://developer.ebay.com/help/docs/.
samples: samples for the eBay SDK for Java. See the samples readme for details.
source: source code of the eBay SDK for Java.
- source/core contains the source code for ebaysdkcore.jar
- source/apiCalls: source code for ebaycalls.jar
- source/attributesLib: source code for attributes.jar
- source/helper: source code for helper.jar
- source/SanityTest: source code for Sanity Test Framework

WSDL Locations

The WSDL is located at http://developer.ebay.com/webservices/Version/ebaySvc.wsdl.

Version in the URL means latest or it means a numerical version of a WSDL release (see the top of the particular WSDL file).

In the case of Version meaning latest, the WSDL is the latest released version (http://developer.ebay.com/webservices/latest/ebaySvc.wsdl). If Version in the URL means a numerical version of the WSDL, Version is a number (for example, http://developer.ebay.com/webservices/445/ebaySvc.wsdl).

Hypothetically, if the latest release of the WSDL were 449, you would find that WSDL version at both http://developer.ebay.com/webservices/latest/ebaySvc.wsdl and at http://developer.ebay.com/webservices/449/ebaySvc.wsdl.

WSDL Updates

Each version of the eBay SDK for Java is based on a specific WSDL version of the eBay Trading API. eBay updates its WSDL file regularly. Advanced users can use more recent fields and calls by updating the code stubs in their SDK with a more recent WSDL file than the one delivered with the SDK.
Please note that WSDL updates should always be done in a test environment because WSDL updates can prevent you from using some of the wrapper classes delivered with the SDK. If you update your SDK with a WSDL that contains updated input fields for requests (that is, updated request types), you will need to manually update the affected wrapper classes or use the affected request objects directly, without wrappers.
To update the code stubs in your SDK with a more recent WSDL file, please see related instructions in Building the SDK.

Supported Client Environments

eBay has tested the eBay SDK for Java using the following client environments:

Sun JAX-WS RI 2.1.4
Java 2 Standard Edition 1.5 and 1.6 on:
- Windows 2000
- Windows XP Service Pack 2
- Fedora 8 (Linux-Based)

Note: You can use any integrated development environment (IDE) with the eBay SDK for Java, as long as it supports the above environments.