eBay SDK for Java Readme

Please note the following important information about the SDK:

Before using a version of the SDK, please read the most recent version of this Readme file, available at the Java Developer Center.
Upgrades should always be done in a test environment.
Testing for the SDK includes testing with IBM JDK 1.5, but some components may be incompatible with IBM JDK 1.5. Please post issues with IBM JDK 1.5 in the Java SDK Forum.
All SDK releases are now delivered as zip files and there is no installer. After reviewing the Release Information for the eBay SDK for Java, please see the Installation Instructions.
The most recent full SDK release is the eBay SDK 561 for Java Full Release.
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.
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).
Starting with the July release, the eBay SDK for Java will only support JDK 1.5 and JDK 1.6. We will drop support for JDK 1.4, since Sun has deprecated JDK 1.4.
If you are currently using JDK 1.4, we strongly recommend that you to update your JDK.

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 561 and Subsequent Point Releases

SDK Version 549 and Subsequent Point Releases

SDK Version 523 and Subsequent Point Releases

SDK Version 511 and Subsequent Point Releases

SDK Version 503 for Java Point Release

SDK Version 495 for Java Full Release

SDK Version 485 and Subsequent Point Releases

SDK Version 479 and Subsequent Point Releases

SDK Version 471 and Subsequent Point Releases

SDK Version 465 and Subsequent Point Releases

SDK Version 459 and Subsequent Point Releases

SDK Version 447

SDK Version 1.2.0

SDK Version 561 and Subsequent Point Releases

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.

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 features of the API.

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.

SDK Version 549 and Subsequent Point Releases

Attributes Library Supports Sitewide Attribute Sets

The Attributes Library in the SDK now supports downloading and rendering sitewide characteristic sets. This enables you to include sitewide attributes in listings.

On many sites, you use sitewide attribute sets to fill in an item's Return Policy fields, the Item Condition field, or both. Some categories may support zero, one, or both of these sets (as indicated in each sitewide set's "exclude list").

The changes described here assume you are already familiar with the Attributes Library. (For information about working with the Attributes Library, see The Attributes API.)

In the IAttributesMaster interface and AttributesMaster class, the renderHtmlForCategories() method has been removed. Instead, these new methods have been defined:

getItemSpecificAttributeSetsForCategories() for retrieving (standard) characteristic sets that are mapped to each specified category.
getSiteWideAttributeSetsForCategories() for retrieving sitewide characteristic sets that are mapped to each specified category.
getReturnPolicyAttributeSet() method for extracting the Return Policy characteristic set from the array of sitewide sets. (If you are using eBay's Item Specifics SYI XSL stylesheet, the return policy needs to be rendered on a separate page.)
joinItemSpecificAndSiteWideAttributeSets() for creating an array of all the standard and sitewide characteristic sets (e.g., Item Condition) that will be rendered together (not including Return Policy).

In the AttributesMaster class, the renderHtml() method has been updated to support rendering Return Policy fields (using eBay's XSL stylesheet). This method checks whether the data is for a return policy, and adds the pageId attribute to the SelectedAttributes node if it is.

A few helper methods have been added to or modified in IAttributesXmlProvider and AttributesXmlDownloader:

getMultipleCSXmlText() returns a String instead of a Document object. This is convenient when you want to work with a string (e.g., for logging the response).
getMultipleCSXml() returns a Document object.
downloadXml() has been overloaded to take an array of attribute sets instead of an array of IDs. (This is convenient if you don't want to extract the attribute set IDs first.)

A few helper methods have also been added to ICategoryCSProvider and CategoryCSDownloader:

getSiteWideCharSetsAttrIds() gets an array of sitewide characteristic set IDs that are mapped to the specified category. (In CategoryCSDownloader, this method is used by downloadCategoryCS().)
getVCSIdMap() gets the characteristic set IDs that are mapped to the specified category (as a Map).
getVCSIdArray() gets the characteristic set IDs as an array. (In CategoryCSDownloader, this method uses getVCSIdMap().)

Note: In a few cases, the Item Condition attribute may appear twice when you render standard and sitewide data for a category. Please inform eBay if this occurs. This occurs when a category is mapped to a standard characteristic set that defines an Item Condition attribute locally, and the category is also mapped to a sitewide Item Condition characteristic set. To avoid unexpected results, the seller should either use the local Item Condition defined in the standard set, or you should make sure the same value is used for both when you list the item.

Here are a few cases that may be helpful when you're testing sitewide attributes in the Sandbox:

Site ID 77 (Germany), category 156939
Mapped to:
- Standard set: 3029 (Backofen & Herde), with local Zustand (condition) attribute (10244)
- Sitewide set: 2136 (Return Policy)
Site ID 77 (Germany), category 18459
Mapped to:
- Standard set: 2997 (Briefmarken - Stamps)
- Sitewide set: 1950 (Artikelzustand - Item Condition)
- Sitewide set: 2136 (Return Policy)
Site ID 0 (US), category 48514
Mapped to:
- Standard set: 2034 (Camcorders), with local Condition attribute (10244)
- Sitewide set: 2135 (Return Policy)
Site ID 212 (Poland), category 9861
Mapped to:
- Standard set: 4896 (Samochody osowe), with local Stan (condition) attribute (10244)
- No sitewide set (3830 Item Condition set is returned but excludes this category)

For an example of new and existing functionality in the Attributes Library, see the existing samples\attributesDemo sample and the Readme file for that sample.

Releases Now Delivered Only as Zip Files (No Installer)

Unlike past SDK releases, all SDK releases now are delivered as zip files. There is no installer. For more information, see the Installation Instructions.

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 features of the API.

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.

SDK Upgraded with JAR files for XML and XPath Utilities

The SDK has been upgraded with externalLib\axis-1_1\xalan.jar and externalLib\axis-1_1\serializer.jar, for use by source\core\src\com\ebay\sdk\util\XmlUtil.java and source\core\src\com\ebay\sdk\util\XPathUtil.java.

SDK Version 523 and Subsequent Point Releases

Attributes Library Enhanced

The Attributes Library now gives you the option to store attribute metadata locally, and only download updates for a site if a newer version exists on the site. Each provider includes one or more get methods for this purpose. In the downloader classes that implement the provider interfaces, these methods check to see what version of the metadata is already stored locally and compare it to the version on the site. If the version on the site is different, or if the metadata isn't stored locally, these get methods download the appropriate metadata from the site and store it in the local file system.

These are the filename conventions (where version is the metadata version, not the request version):

XSL file	site.version.attrxsl
Category-to-CS mappings (all categories)	site.ALL.version.catcs
Category-to-CS mappings (one category)	site.categoryID.version.catcs
Attributes CS (all sets)	site.ALL.version.attrcs
Attributes CS (one or more sets)	site.CSIdHashcode.version.attrcs

For example, if you retrieve a full attribute metadata XML file from the UK site (without specifying a particular CSId), and the attribute system version is 8005, the filename would be: UK.ALL.8005.attrcs.

If you retrieve attribute metadata for one or more CSIds, the downloader creates a hashcode for the set (the sum of the IDs), and uses that value in the filename.

The downloader saves these files in the location where the application is launched. For example, if you are using Apache Tomcat, this could be the bin folder or the $CATALINA_HOME folder, depending on how you launch the application. If you are using a desktop application, this could be in the folder where the application is located.

Important: You can delete these locally stored files, but if you edit or rename them, your application may fail.

Alternatively, each provider includes download methods to enable you to force a full download of the metadata without checking the version. In the downloader classes, these methods store the metadata in memory only.

For information about working with the Attributes Library, see The Attributes API. For a sample that uses the functionality in the Attributes library, see C:\Program Files\eBay\SDKInstallDir\samples\attributesDemo and the Readme file for that sample.

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 features of the API.

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.

SDK Version 511 and Subsequent Point Releases

Changes to Download Location and to Documentation

The eBay SDK for Java no longer is available in the Community Codebase. Instead, it is available on the eBay SDK for Java download page. The 511 version includes the 511 javadoc.

For information about the latest API features, please see the Trading API Release Notes and the Trading Web Services API Guide at the Java Developer Center. The Trading Web Services API Guide replaces the eBay SDK for Java Guide.

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 features of the API.

No Wrapper Class Currently Available for the UploadSiteHostedPictures Call

Schema version 513 introduced a new XML API call (UploadSiteHostedPictures) for uploading pictures for listings. Availability of this call in the SOAP API is planned for a future date, to be announced. Until this call is available in the SOAP API, no wrapper class will be available for this call in the SDK.

Deletions of Deprecated Fields and Calls

Many deprecated calls and fields were deleted in WSDL version 499. Due to the large number of deletions, SDK Version 511 is not backward compatible.

Helper Class Available for GetCategoryFeaturesCall

You can use a helper class (...\SDKInstallDir\source\helper\src\com\ebay\sdk\helper\GetCategoryFeaturesHelper.java) to store the response data of GetCategoryFeaturesCall in memory. The helper class behaves similarly to the GetCategoryFeatures API call. For an example of how to use the GetCategoryFeatures helper class, please see the following sample: ...\SDKInstallDir\source\SanityTest\src\test\ebay\sdk\helper\GetCategoryFeaturesHelperTests.java.

Removal of Three Samples

The following samples (formerly under the samples folder) have been removed from the SDK, but are available in previous SDK versions: databaseSample, eBaySales, and eBaySalesDesktop.

For Use On Linux: dos2unix Change Needed for Samples

If you install the SDK on Linux and try to run the consoleAddItem sample (in the samples folder), use the dos2unix command on the run.sh file before running the sample. The same step is required for the consoleViewItem sample.

SDK Version 503 for Java Point Release

Deletions of Deprecated Fields and Calls

Due to a large number of deletions from version 499 of the schema, this SDK version is not backward compatible. Deprecated calls and fields were deleted on schema version 499.

For information about SDK changes, please see the javadoc installed in the C:\Program Files\eBay\SDKInstallDir\docs\LibRef folder. Additional information about schema deletions is in the Deprecated Objects page in the Input/Output Reference. Please also read the eBay Schema Versioning Strategy page.

Recent API Feature Updates

This SDK point release contains updated wrapper classes and other updates that facilitate your use of new API features. The following features, described in the Trading API Release Notes, are among the API features included in this SDK release:

Retreiving Product Information and Listings. You can use GetProductsCall to retrieve basic product information (such as product titles, stock photos, and Item Specifics), as well as buying guides, reviews, and active items.
Applying Discounts Across Listings. You can temporarily reduce the prices of listed items using the Promotional Price Display feature. The feature enables sellers to apply a time-based discount across many Store Inventory and fixed-price listings.

Update to Shipping Discount Profiles Feature on API Version 505

In the Shipping Discount Profiles feature, changes to WSDL elements were made on API version 505. To use the Shipping Discount Profiles feature, please update your SDK to WSDL version 505 or later.

Method Fixed in GetCategoriesCall

Formerly, use of the getAllCategories method of the GetCategoriesCall wrapper class would result in a setting of the US category site ID in all cases. The wrapper class has been fixed to enable the correct category site ID to be set.

Database Sample Not Compatible with SDK Version 503 Point Release

The database sample (C:\Program Files\eBay\SDKInstallDir\samples\databaseSample) cannot be used with the version 503 point release of the SDK.

SDK Version 495 for Java Full Release

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 features of the API.

GetMyeBayCall Removed

The GetMyeBayCall wrapper class has been removed from the SDK due to deprecation of the underlying request/response elements in the schema. For more information about deprecated elements, please see the Versioning Strategy and Versioning Summary. Additionally, the GetMyeBay code has been removed from the Sanity Test suite and from the apiCallsDemo sample.

References to SiteHostedPicture and VendorHostedPicture Removed

The PictureDetails field replaced the SiteHostedPicture and VendorHostedPicture fields in the API. Therefore, references to SiteHostedPicture and VendorHostedPicture have been removed from the SDK. For information about when the PictureDetails field replaced the SiteHostedPicture and VendorHostedPicture fields, please see the Versioning Summary.

Eclipse Project Files Provided

If you choose the Eclipse environment for development with the eBay SDK for Java, you can use Project files provided with the SDK. For more information, please see the following: C:\Program Files\eBay\SDKInstallDir\DevEnvReadme.htm.

New and Updated Samples

The samples in the eBay SDK for Java now include a signinRedirect sample that generates a token for an end user. The new sample is located at C:\Program Files\eBay\SDKInstallDir\samples\signinRedirect. Additionally, four dialog boxes, including dialog boxes for use of GetCartCall and SetCartCall, have been added to the apiCallsDemo sample (C:\Program Files\eBay\SDKInstallDir\samples\apiCallsDemo).

SDK Version 485 and Subsequent Point Releases

Control Payload Logging

You can use the new ExceptionFilter class to specify several types of logging. The ExceptionFilter class enables you to log exceptions, error codes, or HTTP status codes.

This new logging feature makes logging more useful and reduces the size of your logs. You can choose to log specific exceptions, specific API error codes, and specific HTTP status codes.

For an example of how to use the new ExceptionFilter class, please see the following sample: C:\Program Files\eBay\SDKInstallDir\source\SanityTest\src\com\ebay\sdk\sanitytest\testcases\SOAPError.java.

For more information and more sample code, please see the following Knowledge Base article: Enabling exception-based payload logging using the JAVA SDK.

Changes to Axis and to Core SDK Files for Performance Reporting

New enhancements can help you determine the time needed for each phase of a SOAP API call (client-side phases for encoding and decoding, network-transport phases, and server-side phase). The enhancements were made to Axis (C:\Program Files\eBay\SDKInstallDir\externalLib\axis-1_1\axis.jar) and to core SDK source files.

For an example of how to use the enhancements, see the PerfTest sample (C:\Program Files\eBay\SDKInstallDir\source\PerfTest), which, along with the Axis jar file, has been modified in this release. The changes to the PerfTest sample include removal of the HTTPSenderWithMetricsLogging class because metrics logging is now part of the customized Axis jar file delivered with the SDK.

Please note that a customized version of the Axis jar file must be used with the eBay SDK for Java. If you download or otherwise obtain a version of Axis 1.1, then you must follow the instructions in the source\axis_customization\axis_1_1 folder to build Axis 1.1.

AddMemberMessage Removed from WSDL

AddMemberMessage was removed from the WSDL on version 481. As previously announced, this call has been replaced by AddMemberMessageAAQToPartner, AddMemberMessageRTQ, and AddMemberMessagesAAQToBidder. For information about schema changes, please see the Trading API Release Notes (which contain tables showing the schema changes that occur every two weeks) at the Developer Documentation Center.

SDK Version 479 and Subsequent Point Releases

Improvement of Sanity Test Suite

The reliability of the Sanity Test suite (under the Source\SanityTest folder) has been improved. You can use the Sanity Test suite for simple testing after you change code in the SDK.

SDK Version 471 and Subsequent Point Releases

GetCharitiesCall Wrapper Class Fix

The GetCharitiesCall wrapper class has been fixed to no longer throw an exception based on whether an OverrideRequest property was set.

AddItem UUID Fix

In previous releases of the eBay SDK for Java, a request error could occur when AddItemCall.newUUID generated a UUID for use by your application. The request error occurred when the UUID included a '-' character generated by AddItemCall.newUUID. In the current release, this request error should not occur because AddItemCall.newUUID was changed to prevent generation of a '-' character.

StoresFixedPrice Tag To Be Obsolete

The StoresFixedPrice tag, currently available for international sites, will soon be obsolete. The 471 API schema released in late July contained additions to ItemTypeFilterCodeType that apply to searches with GetSearchResults and GetCategoryListings. The additions to ItemTypeFilterCodeType must be used instead of the StoresFixedPrice tag. For more information, please see the API Release Notes (which contain tables showing schema changes that occur every two weeks) at the Developer Documentation Center.

SDK Version 465 and Subsequent Point Releases

Fix for IncludeFinalValueFee Input Property

Bugs have been fixed involving GetSellerTransactionsCall and GetAttributesXSLCall. Specifically, in GetSellerTransactionsCall, the IncludeFinalValueFee input property now properly determines whether to include final value fees in the response. In GetAttributesXSLCall, a null value no longer is returned when no detail level is specified.

Retry for HTTP errors

You can use the CallRetry class in the SDK to set up retry for calls in cases of 400- to 500-series HTTP errors (that is, HTTP application errors 400-499 and 501-599 from a web server). This addition to the CallRetry class includes a Get method and a Set method for a new exception (SdkHttpException) to capture such errors.

Patch for Change Affecting GetMemberMessagesRequestType

A patch has been incorporated into the SDK based on the change (with the 463 WSDL version) in the datatype of the StartCreationTime and EndCreationTime elements of GetMemberMessagesRequestType. The patch includes wrapper class updates in which java.util.Calendar replaces java.util.Date.

Change Affecting GetMemberMessagesRequestType

The 463 WSDL version introduced a backward-incompatible change in the datatype of the StartCreationTime and EndCreationTime elements of GetMemberMessagesRequestType; the elements are now based on xs:dateTime, not xs:date.

SDK Version 459 and Subsequent Point Releases

Upgrade to J2SE 1.5

The eBay SDK for Java is updated for compatibility with J2SE 1.5.x (JDK 5.0). This enables applications to use more Java features and to benefit from improved performance. If you use J2SE 1.5.x (JDK 5.0), you must use Apache ANT 1.6 or later. For more information, see Post-Installation Configuration.

Changes to WSDL Elements Previously Based on ShippingServiceCodeType and ListingDurationCodeType

Due to changes to WSDL elements previously based on ShippingServiceCodeType and ListingDurationCodeType, SDK version 459 is backward-incompatible. Subsequent SDK releases are not backward-compatible with SDK versions based on a pre-457 WSDL version.

Integration Library Sample Renamed

The sample formerly called "integrationLibrary" and the folder containing it have been renamed to "databaseSample."

SDK Version 447

Default Detail Level Changed

The default detail level has changed. This has a major impact on the data returned by calls that use detail levels, such as GetItemCall. Previous versions of the eBay SDK for Java set a default detail level of ReturnAll. Now, no detail level is set; the value is left as null. For general information about detail levels, see the latest Trading Web Services API Guide at the Developer Documentation Center

APISchemaBasedXMLPoster Class

The APISchemaBasedXMLPoster class enables you to post Trading API messages to the eBay API. Such messages comply with the Trading API but do not use a SOAP envelope or SOAP posting conventions (such as site ID in the URL). Note that the APISchemaBasedXMLPoster class does not support pure SOAP messages using a SOAP envelope or eBay SOAP API HTTP protocol conventions.

Sanity Test Suite for Simple Testing

You can use the Sanity Test suite for simple testing after you change code in the SDK. The source files are installed with the SDK. For information about running the Sanity Test suite, see Post-Installation Configuration.

More Information Provided About Runtime Exceptions

Based on customization of the version of Axis 1.1 delivered with the eBay SDK for Java, more information is provided by the SDK about exceptions during runtime. Now, information is provided about the tag involved.

SDK Version 1.2.0

HTTP Compression

When you use the ApiCall class to execute a request to the eBay API, HTTP compression is on by default. A customized version of the Axis 1.1 library (axis.jar) is included in the SDK to provide the HTTP compression and improve the performance of Axis 1.1. The HTTP compression reduces the size of response data from the API by, on average, 90 percent. HTTP compression is especially advantageous for calls such as GetCategories that return large amounts of data. To turn HTTP compression off, call ApiCall.setEnableCompression and set the value to false.

Thread Safety in ApiCall Class

Using the ApiCall class of this eBay SDK for Java release to pass a SOAP API request object is the recommended thread-safe best practice for a Java application using the SOAP API. Additionally, doing so makes any Java application run in a thread-safe manner.

Performance Enhanced for Obtaining and Caching Bindings

Performance enhancements, related to obtaining and caching bindings, have been implemented.

Installation Instructions

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

Decide which eBay SDK for Java download you will use (choose the zip file for Java Development Kit (JDK) 1.5.x or 1.4.x).

These instructions assume JDK 1.5.x, so if you download JDK 1.4.x, then throughout this document, please replace "1.5" with "1.4" and replace "15" with "14".

Please note that if you use JDK 1.5.x, you must use Apache ANT 1.6 or later.

Download the zip file for the version of the eBay SDK for Java that you chose in step 1.

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 549, you could name the folder eBayJavaSDK549.

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.

General Information for the eBay SDK for Java

Development Requirements

Development Environments and Compatibility

Post-Installation Configuration

Included in the eBay SDK for Java

WSDL Locations

WSDL Updates

Supported Client Environments

Development Requirements

J2SE 1.5 (JDK 5.0) or J2SE 1.4 (see Post-Installation Configuration)
(If you prefer to use J2SE 1.3, you must first install the JSSE extension. For more information, see below.)
Apache ANT -- Download from http://ant.apache.org/; Ant version 1.7 is required for the attributesDemo sample. If you use J2SE 1.5.x (JDK 5.0), you must use Apache ANT 1.6 or later.
Apache Axis 1.1 -- A customized version is included in this installation. You must compile the eBay SDK for Java with the version of the axis.jar file delivered with the eBay SDK for Java. If you download or otherwise obtain a version of Axis 1.1, then you must follow the instructions in the source\axis_customization\axis_1_1 folder to build Axis 1.1.
(optional) Jakarta Tomcat, if you wish to build the JSP samples.

Development Environments and Compatibility

Please note that updates to applications using new WSDL versions should always be done in a test environment.
In some cases, SDK releases are not backward-compatible with previous SDK versions. For example, SDK version 459 is not backward-compatible. Additionally, in schema version 499, deprecated objects in the schema were deleted, creating backward incompatibility. Please see the Trading API Release Notes for ongoing updates to the schema (including occasional removals of schema elements).
If you use Eclipse to run the samples delivered with the SDK, Eclipse version 3.2 is required. For information about using the Eclipse project files provided with the SDK, please see the following: ...\SDKInstallDir\DevEnvReadme.htm
Every SDK release uses the eBay SOAP API and is based on a WSDL version. For example, the eBay SDK 459 for Java used the eBay SOAP API and contained the wrapper classes available in the 459 WSDL.
Information about Compatibility Levels is available in the API documentation at the following location:
http://developer.ebay.com/help/docs/

Post-Installation Configuration

Install Apache ANT if it is not installed. Add the bin directory of your ANT installation to the PATH environment variable. If you use J2SE 1.5.x (JDK 5.0), you must use Apache ANT 1.6 or later.
(If you prefer to use JDK 1.3 rather than 1.5.x or 1.4.x, you must first install the JSSE extension. For more information, see below.)
Set the JAVA_HOME environmental variable to the J2SE 1.5.x directory, or the directory of a different JDK version (1.3 or 1.4).
To facilitate your use of the SDK, you may want to add the following two values (or values appropriate to your JDK version) to the PATH environment variable, in this order: [j2sdk 1.5.x home directory]\bin and [j2sdk 1.5.x home directory]\jre\bin. You may want to add a path similar to the following to your CLASSPATH environment variable: [j2sdk 1.5.x home directory]\jre\lib\jsse.jar.
If you have installed Jakarta Tomcat, set the TOMCAT_HOME environment variable to the Jakarta Tomcat location.
In the eBay SDK for Java installation directory, run the following command:
ant -buildfile sdkCodeGen.xml
Ant uses sdkCodeGen.xml to create SDK source code (stubs) from a WSDL (by default, the WSDL delivered with the SDK). Ant modifies the stubs with the StubModifier tool (see ...\source\Tools\StubModifier\src\tools\webservices\wsdl\stubutil\StubModifier.java). Ant also uses sdkCodeGen.xml to compile all the SDK source code and create .jar files (ebaysdkcore.jar and ebaycalls.jar) for the SDK libraries.
Advanced users can update the SDK as described in the WSDL Updates section below.
Based on your current configuration and your development plans, decide whether to download the following third-party components. All components you decide to download should be put in folders under the externalLib folder:
- If you prefer to use J2SE 1.3.x, you must install the JSSE 1.0.3 library (and modify the appropriate run.xml and build.xml files to point to that library). If you are using J2SE 1.3.x, the JSSE 1.0.3 library is needed to connect to eBay using HTTPS. You can install JSSE 1.0.3 from the following location: http://java.sun.com/products/jsse/index-103.html
- To use the Sanity Test Framework (under the source/SanityTest folder) for simple testing after you change code in the SDK, you must install JUnit (to the externalLib folder) from http://www.junit.org/index.htm. Note that if the server-side prerequisites for a call are not present, a call from the Sanity Test suite will show a call failure. Additionally, some tests may fail or may show success even when there has been a failure. After you install JUnit, do the following:
  1. Update build.xml (under the SanityTest folder) based on your JUnit installation.
  2. Under the SanityTest folder, execute an ant -f build.xml command.
  3. Under the SanityTest folder, execute an ant run command.
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:
- http://download.fedora.redhat.com/pub/fedora/linux/updates/8/i386/libxcb-1.0-4.fc8.i386.rpm
- http://download.fedora.redhat.com/pub/fedora/linux/updates/8/i386/libxcb-devel-1.0-4.fc8.i386.rpm

SDK-Related Links

Building the SDK

In this section, you will use an ANT project file, sdkCodeGen.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.

To build the SDK, use the following steps:

Review and follow all the steps in the Installation Instructions.

Go to the SDKInstallDir described in the Installation Instructions.

In SDKInstallDir, using a text editor, edit setjava15.bat so that JAVA_HOME is set to your main JDK folder.

If you are using JDK 1.4.x, see the Installation Instructions. If you are using JDK 1.5.x, then in SDKInstallDir, open a command window and run setjava15.bat. This sets and appends necessary environment variables (i.e., it replaces JAVA_HOME and CLASSPATH, and it prepends PATH).
After running setjava15.bat, go to step 5 without closing the command window.

In the same command window, in SDKInstallDir, run the following command:
ant -buildfile sdkCodeGen.xml
Ant uses sdkCodeGen.xml to create source code (stubs) from a WSDL (by default, the WSDL delivered with the SDK). Ant modifies the stubs with the StubModifier tool (see ...\source\Tools\StubModifier\src\tools\webservices\wsdl\stubutil\StubModifier.java). Ant also uses sdkCodeGen.xml to compile SDK source code and create .jar files (such as ebaysdkcore.jar and ebaycalls.jar) for the SDK libraries.

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. Optionally, download the new WSDL you want to use. For more information, see WSDL Locations.
3. In sdkCodeGen.xml, on the line that sets the eBayWSDL property, set that property to the WSDL you want to use (local or web). By default, the eBayWSDL property is set to the WSDL that came with the SDK installation, and a commented-out line is set to a web version. To use a web version:
  1. Comment-out the line set to the local version.
  2. Remove the comment symbols around the line set to the web version.
  3. Specify a WSDL version number in the URL for the web version.
4. At a command prompt, from ...\SDKInstallDir, run the following command:
  ant -buildfile sdkCodeGen.xml

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.

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
externalLib: Axis 1.1 library files. You must compile the SDK with the version of the axis.jar file delivered with the SDK. If you download or otherwise obtain a version of Axis 1.1, then you must follow the instructions in the source\axis_customization\axis_1_1 folder to build Axis 1.1.
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.
The ANT file sdkCodeGen.xml has an eBayWSDL property. There is a commented-out version and a non-commented-out version.
The non-commented-out version is set to the WSDL that came with this SDK installation. The commented-out version is set to a full URL (that is, to the web), showing the full URL that refers to a particular WSDL version. When a new WSDL is available, you can download the new WSDL and set the eBayWSDL property to that WSDL or you can modify the full URL to use a web version.
The ANT project file sdkCodeGen.xml does the following:
1. Creates SDK source code from the WSDL.
2. Compiles all SDK source code.
3. Creates .jar files (ebaysdkcore.jar and ebaycalls.jar) for SDK libraries.
To update the code stubs in your SDK with a more recent WSDL file:
At a command prompt, change to the root directory of the eBay SDK for Java and run the following command: ant -buildfile sdkCodeGen.xml

Supported Client Environments

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

Apache Axis 1.1
Java 2 Standard Edition 1.5 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.