eBay Java SDK Getting Started Support     Knowledge Base     Forums     All Tutorials     All Code Samples Getting Started Guide Call References Making an SDK Call Samples/Tutorials Release Notes

Introduction

The eBay enterprise environment provides services that are essential to applications written for eBay sellers and buyers, such as listing items for sale, finding listed items that match given criteria, and placing bids on items. Because the applications that use these services often run on personal computers, or on servers operated by third parties, they must be able to invoke services through the Internet. eBay services make this possible by supporting service requests through several standard network protocols, among them SOAP.

Services are organized into groups of related operations called API's. One API, the Trading API, provides a variety of services related to trading, such as creating, bidding on, and ending item listings, transporting messages between sellers and buyers, and leaving feedback.

This section describes the directories and the most important files in the Java SDK distribution.

If you want to use the Java SDK you will need to have or do the following:

• Knowledge of the eBay Trading API, which you can obtain from the Trading API Guide and the Call Reference. You'll need to consult those documents whenever you write code for the API call objects because no details on the Trading API are provided in SDK documents.
• Knowledge of the Java development system needed to create Java applications of the appropriate type (e.g., Swing applications or web applications).
• Knowledge of HTML.
• Knowledge of XML and the SOAP protocol.
• Join the eBay Developers Program and get your access/application keys, App ID, RUname, etc, as described in the Quick Start Guide. You'll need both Sandbox and Production keys.
• Create at least two test users for the Sandbox environment (one to use as a buyer, one to use as a seller). For more information about the Sandbox testing environment, see Testing Applications.
• Obtain one Authentication token ("auth token") for each of those test users.
• A development computer running Microsoft Windows® or Linux. The Java SDK has been tested with the following versions:
  
  
  • Windows 2000
  • Windows XP with Service Pack 2
  • Fedora 8 (Linux)
• A Java development system, typically an interactive development environment (IDE). The Java SDK has been tested with the following IDE's:
  
  
  • Eclipse 3.x and later (the Java SDK comes largely configured for use with Eclipse)
  • JBuilder X and JBuilder 2005
  • NetBeans 5.x and NetBeans 6.x
• If you develop web applications, a copy of the Tomcat 5.5 application server running on the development computer.
• A copy of the Java Development Kit (JDK) compatible with your version of the eBay Java SDK. As of this writing, JDK versions recommended for use with current versions of the eBay Java SDK are Sun Microsystems Java 2 Standard Edition (J2SE or SE) JDK, version 1.5 (any release) and version 1.6 (release 4, 1.6.04, or later. (You can use the Sun Java SE JDK, version 1.6, release 3 and earlier, but you must make some changes to the JDK.) For your convenience, the eBay SDK for Java® page provides a link to Sun Microsystems' JDK download page.

  You can use IBM JDK version 1.5 or 1.6 (any release), but you must make some changes to the Java SDK after you install it. Instructions are given below. There are no known issues with the IBM JDK, but not all Java SDK features have been tested with it. Please report any issues you discover in the Java SDK developers' forum.

• A copy of the ebay Java SDK itself, available from the eBay Developer Center.

1. Go to the eBay SDK for Java page and scroll down to the Downloads section
2. Under JAX-WS, find the entry for the release of the eBay Java SDK that you prefer. We recommend choosing the latest full release of the SDK unless you have a clear reason for choosing a different release. Click the link of the chosen version to download the SDK Zip file.

If you will use the Java SDK with one of these JDK versions, you must copy two JAR files from the Java SDK to the JDK. Where $JDK represents the JDK's home directory, copy these files from $JSDK/lib/externalLib to $JDK/jre/lib/endorsed:

• jaxws-api.jar
• jaxb-api.jar

If you will use the Java SDK with the IBM JDK version 1.5 or 1.6, you must include the contents of the directory $JDK/externalLib/jaxp-1.4.2/ in the classpath. You may either add the directory in the classpath or copy the two JAR files it contains to another directory that is already in the classpath.

Note that if you are using a Sun JDK, these JAR files should not be in the classpath.

Configure Java to use a JDK (not a JRE) that is compatible with the Java SDK. See Prerequisites for more information.

Add all of the JAR files in $JSDK/lib/ and $JSDK/lib/externalLib/ to the classpath. (Do not add any of the files in $JSDK/lib/externalLib/optional/ unless you are specifically instructed to do so.)

If you are using an IDE that can display Javadoc for classes and class elements used in the source code, enter the pathname for the Java SDK's Javadoc directory. This directory is at $JSDK/docs/LibRef/.

Make any additional changes required to make the Java SDK work with the JDK you have chosen. See Requirement for using Sun Java SE JDK 1.6 or Requirement for using the IBM JDK for details.

These instructions are specific to Eclipse.

1. Start Eclipse and create a workspace which you will use to develop Java SDK applications.
2. Select the menu command Windows/Preferences to open the Preferences dialog. Select the Java/Installed JREs tab. Click the Add button, if necessary, to add the JDK that you intend to use with Java SDK applications. Select that JDK and deselect any other items in the Installed JREs list.
3. Select the Java/Build Path/User Libraries tab. Click the New button and enter a suitable name for a Java SDK user library (e.g., JavaSDK).
4. Select the newly created user library and click the Add JARs button. Eclipse opens an “Open File” dialog. Navigate to $JSDK/lib/. Select all of the JAR files in the directory and click the Open button.
5. Click Add JARs again. Eclipse reopens the “Open File” dialog. Navigate to $JSDK/lib/externalLib/. Select all of the JAR files in the directory and click Open.

The Java SDK includes Javadoc content which you can attach to each of the Java SDK library files (each of the JAR files in $JSDK/lib/). This will enable you to display summary information for a Java SDK element by clicking the element, then pressing F2. You can display the full Javadoc by clicking an “Open attached Javadoc” button in the summary information box.

To attach the Javadoc content to the library files:

1. Open the Preferences dialog.
2. Select the Java/Build Path/User Libraries tab.
3. Expand the entry for the first JAR file.
4. Select the JAR file's Javadoc location entry.
5. Click the Edit button. Eclipse opens a “Open File” dialog.
6. Navigate to the $JSDK/docs/LibRef/ directory and click OK.
7. Repeat steps 3–6 for each of the remaining JAR files.

Make any additional changes required to make the Java SDK work with the JDK you have chosen. See Requirement for using Sun Java SE JDK 1.6 or Requirement for using the IBM JDK for details.

Installing the Sample Application Projects for Eclipse

If you are using Eclipse, you can import prebuilt projects for the sample applications.

Start Eclipse and select the workspace that you use to develop Java SDK applications.

Select File/Import to display the Select page of the Import dialog.

From the tree of import sources, select General/Existing Projects into Workspace and click Next.

Click Select root directory and Browse, navigate to the $JSDK/samples/ directory, and click the OK button.

The names and pathnames of the sample application projects (all in subdirectories of $JSDK/samples/) should appear in the Projects text area, as shown below.

Select the projects you want to import, or click Select All to import all of them. Click the Finish button at the bottom of the dialog to import the projects into the workspace.

For details, see Making an SDK Call.

Handling Authorization in Your Applications

Most Trading API calls you make from the SDK require an authorization token, which represents the user's authorization of your application to access eBay on behalf of that user. If eBay authorization tokens are new to you, review the short and focused topic Getting Tokens in the Trading API Guide. Be especially attentive to the different requirements of single-user and multi-user applications. You might also want to look at the Getting Tokens tutorial.

Sample Code for Getting Tokens

The follow Java SDK sample program may be useful to you:

• A Java desktop application: JAVA: Sample Auth & Auth Desktop Application

Advanced Topics

The following sections describe advanced topics on commonly used SDK features:

Caching metadata

Metadata is data that conveys information about data. eBay's API architecture uses metadata to describe rules for listing items and managing them through the life cycle of a sale. An example of metadata is the definition of a site's item categories.

Metadata, by its nature, is subject to periodic change. Thus your application must download it through the API.

Because metadata can be quite voluminous, it's good practice to cache it, that is, to store it locally for reuse rather than fetch it through the API each time you need it. Your application can update the cached metadata periodically, either on a regular schedule or when the API reports that metadata has changed.

For example, the GetCategory call returns a version number for the current category hierarchy, and can be used to detect when this version number has changed. For more information about the category hierarchy version number see “Checking the Category Hierarchy Version” in the eBay Trading API Guide section “Maintaining Category Data.”

Call limits

The Trading API protects itself from malfunctioning or malicious applications by enforcing call limits (also known as access rules), which limit the number of API calls that each user of your application may make in a given period of time. Call limits may also apply to a few special types of operations other than API calls, namely to password authentications and non-UTF8 text usage.

Your application may be subject to an aggregate call limit which applies to all of the calls your application makes (although some types of calls do not count toward the limit). Your application may also be subject to one or more specific call limits which apply to particular types of calls and other operations. For example, your application might be subject to a specific call limit on AddItem calls and another on password authentications.

Each call limit has three major parts: a scope (what it applies to), a period (the period of time it applies to), and a count (the number of calls allowed within that period of time). For example, an access rule might limit the AddItem call (its scope) to 5,000 calls (its count) per hour (its period). The period of an access rule may be an hour, any whole number of days, or a month.

You can fetch your application's call limits and current usages by executing the GetApiAccessRules call, using the GetApiAccessRulesCall call wrapper class. For specifics, see the API documentation GetApiAccessRules.

You can increase your application's call limits by completing eBay's Compatible Application Check process. For more information, see “About compatible application check and going live with your application.”

It is good practice to evaluate your application's demands on the API relative to its call limits before the application goes into production. If your evaluation reveals a potential for exceeding the call limits you may want to redesign the application, or apply for a Compatible Application Check, or both.

API Call Retry

eBay's API services, like many web-based services, sometimes do not respond as they should. Calls may fail due to loss of data in the Internet, or because system or network loading prevents some component from fulfilling a request in a timely way.

For this reason, when an API call fails due to a server or network error, it's customary to retry the call a reasonable number of times (e.g., twice, for a total of three tries) before giving up.

In the Java SDK, an API call failure results in a thrown exception. However, the SDK has a built-in retry facility which you can use to implement command retry without coding your own retry logic.

To enable call retry, you must first construct a CallRetry object and set its fields to suit your needs. The setters for the most important fields are:

• setMaximumRetries: sets the maximum number of retries allowed for a failing API call before it throws an exception to the application.
• setDelayTime: set the delay between a call failure and the subsequent retry, in milliseconds.
• setTriggerExceptions: expects an array of objects of type Exception. If the list is non-null, the SDK will retry only for failures that throw exceptions found in the list. The following subclasses of Exception may be used:
  • SdkSoapException for errors in the SOAP protocol (usually server infrastructure errors)
  • ApiException for errors in use of the Trading API (usually application logic errors detected on the server)
  • org.xml.sax.SAXParseException for errors parsing the response payload
  • java.net.SocketTimeoutException for timeouts reading a socket
  • In accord with the rule that retry is useful only for server or network errors, it's good practice not to allow retry for ApiException errors.
• setTriggerApiErrorCodes: expects a String array that defines a list of API error codes. If the list is non-null, the SDK will retry only for failures that represent API error codes found in the list.

  Error codes are documented in the Trading API Reference in the Errors by Number page.

  Note: If setTriggerExceptions and setTriggerApiErrorCodes are both used, the SDK will retry if either condition occurs.

This code snippet illustrates how a CallRetry object might be set up:

   CallRetry cr = new CallRetry();
   java.lang.Class[] retryExceptions = {ApiException,SdkException};
   cr.setMaximumRetries(3);                      // Max 3 retries
   cr.setDelayTime(1000);                        // Retry delay 1000 ms
   cr.SetTriggerExceptions(retryExceptions);     // Retry for these two exceptions

Once you have set up a CallRetry object and set it into the ApiContext object, you can use it for any API call.

   ApiContext apiC = new ApiContext();
   apiC.setCallRetry(cr);
   ...
   GetItemCall gi = new GetItemCall(apiC);

The CallRetry object may be used for more than one call, but because ApiContext is a single-use object, setCallRetry must be called again for each API call.

For more information about best practices for call retry, see the Trading API Guide section “Error Handling.”

Traffic compression

“Traffic compression” refers to the practice of compressing the messages passed between an Internet client and a server.

The Trading API and the Java SDK support traffic compression for the traffic passed between them. Because traffic compression decreases network loading and improves response time in most situations, it is enabled by default.

The sample application configTest reports system performance metrics for Java SDK operation with and without traffic compression. It also illustrates how traffic compression can be disabled and enabled.

Executing an API call Without a Call Wrapper

It's possible to execute a Trading API call without using a call wrapper class by using ApiCall, the base class of all the call wrapper classes. This can be useful if you need to perform an operation that isn't supported by the distributed Java SDK because it was implemented after the latest release of the Java SDK came out.

This technique is useful because the Java SDK's schema classes are built from a WSDL (a Web Services Description Language file) that describes the Trading API calls. If you rebuild the Java SDK with a current copy of the WSDL, the schema classes will reflect the contents of the new WSDL and will support the Trading API's latest features.

Instructions for rebuilding the Java SDK with a current WSDL are in the Java SDK's release notes at $JSDK\docs\ReleaseNotes.html. See the following sections:

• Getting a current version of the WSDL: “WSDL Locations”
• Setting environment variables: “Post-Installation Configuration”
• Rebuilding the Java SDK: “Building the SDK”

Note: for an example that executes an API call without using wrappers, see the consoleAddItemDirect sample in $JSDK/samples.

The procedure for executing a Trading API call without a call wrapper has six steps:

1. Construct an ApiCall object.
2. Construct a nameRequestType object , where name is the name of the API call you will execute.
3. Set the call-specific request fields by calling the nameRequestType object's setters. Set the standard request fields by calling the AbstractRequestObject object's setters.
4. Execute the API call by calling the ApiCall object's execute method. This method expects one parameter, the nameRequestType object. If the API call is successful it returns an object of class nameResponseType. If the call is not successful it throws an exception.
5. Fetch the ApiCall object's AbstractResponseObject by calling the getResponseObject method.
6. Fetch the call-specific response fields by calling the nameResponseType object's getters. Fetch the standard response fields by calling the AbstractResponseObject's getters.

The sample below shows how the code for executing a Trading API call without a call wrapper looks. The sample application consoleAddItemDirect contains similar code in the context of a complete application.

   // 1. Construct an object of class ApiCall.
   ApiCall api = new ApiCall(apiContext);

   // 2. Construct an object of class AddItemRequestType and store an item number
   // in the Item field.
   AddItemRequestType req = new AddItemRequestType();
   req.setItem(item);

   // 3. Execute the API call.
   AddItemResponseType resp = (AddItemResponseType)api.execute(req);

   // 4. Extract the fields you need.
   FeesType fees = resp.getFees();
   ...

Logging

The eBay development environment allows the use of several different logging facilities. Which one (or ones) you use will depend on your needs and your individual working habits.

Application program logging

The Java SDK uses the Simple Logging Facade for Java (SLF4J), a simple facade for various logging frameworks such log4j and java.util.logging (also referred to as JDK 1.4 logging).

By default, the Java SDK uses the log4j framework. The log4j framework must be configured to work properly. There are several ways to configure log4j, discussed in the log4j documentation.

One convenient way to configure log4j is to put a log4j.properties file in your application's classpath. Many of the sample applications, such as consoleAddItem, use this technique. Refer to that application for a simple model of a log4j.properties file.

Note that there is no logging code in consoleAddItem itself, or in any of the other sample applications. See the SLF4J documentation for examples of how to do your own logging.

To use another logging framework, such as java.util.logging, you must remove slf4j-log4j12-1.6.1.jar and log4j-1.2.16.jar from your classpath and add slf4j-jdk14-1.6.1.jar to it. (The location of the file is $JSDK/lib/externalLib/optional/slf4j-1.6.1/slf4j-jdk14-1.6.1.jar.)

Java SDK logging

The Java SDK has a built-in logging facility that can be used to record exceptions, error codes, SOAP requests and responses, and (for web applications) HTTP messages sent and received. This logging facility works through SLF4J, so it can be configured with log4j.properties (or the equivalent, if you use a logging framework other than log4j).

For an example of setting up Java SDK logging, see the FAQ “Exception-based logging using eBay JAVA SDK.”

Performance Measurement

The MetricsLogger class can be used to collect performance metrics on the Trading API calls in an application that uses the Java SDK. After the application is properly instrumented, each execution of an API call may be followed by a call to the method MetricsLogger.collectMetrics. When the performance test is done, MetricsLogger can print a table that shows how much time each Trading API call spent in each stage of execution: preparation on the local system, net transport, etc.

A simple example of an application using MetricsLogger may be found in the eBay developer FAQ “Java SDK — Enabling call metrics logging.”

A more sophisticated example may be found in the SDK distribution at $JSDK/source/PerfTest/.

Rebuilding the eBay Java SDK

You should not need to rebuild the Java SDK unless you want to use it with a new version of the Trading API's WSDL, or you have modified the code.

Rebuilding the Java SDK is not a recommended procedure, and new users are strongly advised against it. It may cause some parts of the SDK to fail. You should rebuild the Java SDK in a testing environment, and test it thoroughly before using it for application development or production.

If you believe you need to rebuild the Java SDK, contact eBay's developer support. The SDK development group can provide instructions and build scripts in appropriate cases.

Runtime Errors in the eBay Java SDK

Several run time errors are unique to the Java SDK or have special meaning there.

Java heap space exhausted

The message “com.ebay.sdk.SdkException: Java heap space” can occur during certain Java SDK calls.

The following FAQ discusses strategies for dealing with this error, such as ways to reduce an API call's heap space requirements: “Java SDK: I am getting 'com.ebay.sdk.SdkException: Java heap space' error with some API calls.”

How to interpret a Java SDK exception

The Java SDK class SdkException has several subclasses for different types of errors.

• SdkSoapException represents errors that concern the SOAP protocol. Certain infrastructure errors on the Trading API server also cause this type of exception. Its getErrorType method returns an object of class ErrorType, whose getters can retrieve the error code and short and long versions of the corresponding message.
• ApiException represents errors in the use of the Trading API. These are usually logic errors in the application that are detected on the server. Its getErrors method returns an array of ErrorType objects representing a collection of errors.
• SdkHTTPException represents errors in the HTTP protocol. Its getErrorCode method returns an int that represents the operation's HTTP status code.

This code sample illustrates how the ErrorType class can be used.

try {
   ...
}
catch (Exception e) {
   if ( e instanceof SdkSoapException ) {
      SdkSoapException sdkSoapExe = (SdkSoapException)e;
      ErrorType error = sdkSoapExe.getErrorType();
      System.out.println("error code: " +error.getErrorCode()+ ": " +
                               error.getShortMessage()
                        );
   }
   if ( e instanceof ApiException ) {
      ApiException apiExe = (ApiException)e;
      ErrorType[] errs = apiExe.getErrors();
      for ( ErrorType error : errs ) {
         System.out.println( "error code " +error.getErrorCode()+ ": " +
                               error.getShortMessage()
                           );
      }
   }
}

After an API call has been executed, the ApiCall class's hasWarning and hasError methods return Boolean values that indicate whether the call returned warnings and errors.

java.lang.NoClassDefFoundError in main thread

The message “Exception in thread 'main' java.lang.NoClassDefFoundError” occurs if you use Sun JDK 1.6.0_04 or below as your Java Platform and your CLASSPATH includes the jaxp1.4.2 libraries, normally located in the directory $JSDK/externalLib/jaxp-1.4.2/.

To fix the problem, remove the jaxp-1.4.2 libraries from your CLASSPATH. These libraries should be in the classpath only if you are using the IBM JDK.

Other Links and Resources

• Eclipse download page
• Java SDK Technical Questions
• Knowledge Base. To filter Knowledge Base listings to the Java SDK, set Search by Product to Trading SDK and SDK to Java before supplying a search word or phrase.
• log4j which is an Apache Java logging component independent of other Apache products.
• System Announcements and Forums
• Tomcat home page
• Trading API Guide
• Trading API Call Reference
• Trading API Release Notes

© 2009–2011 eBay Inc. All rights reserved.
eBay and the eBay logo are registered trademarks of eBay Inc.
All other brands are the property of their respective owners.