helloWorld is a very simple console application that uses the Java SDK to retrieve eBay's official time of day. While the work it does is trivial, it illustrates the basic aspects of writing and building a Java SDK application.
After you enter these items, the application gets the eBay official time through the Trading API and displays it on the console. The application's output will look something like this:
+++++++++++++++++++++++++++++++++++++++
+ Welcome to eBay SDK for Java Sample +
+ - HelloWorld +
+++++++++++++++++++++++++++++++++++++++
==== [1] Account Information ===
Enter your eBay Authentication Token:
AgAAAA**AQAAAA**aAAAAA**ySKaSQ**nY+sNZ2PrBwdj6wVnY+sE22PrAZdj6wJnY+iAZe...
Enter eBay SOAP server URL (e.g., https://api.ebay.com/wspi):
https://api.sandbox.ebay.com/wsapi
Begin to call eBay API, please wait ...
End to call eBay API, show call result ...
Official eBay Time : : Mon Aug 02 18:17:02 GMT+08:00 2010
The completed code is provided in the ConsoleGetUser sample located in the SDK samples subdirectory $JSDK/samples/helloWorld.
Before proceding with this tutorial make sure the following items have been completed:
An Eclipse project for building the helloWorld application is included in the Java SDK at $JSDK/samples/helloWorld/ If you are using a different Java development system, you can copy the Eclipse project source and property files and build your own project.
If you are using Eclipse, you can import the helloWorld project into your workspace much as you imported the Java SDK.
Open the Import dialog. From the tree of import sources, select General / Existing Projects into Workspace. Click Next to display the dialog's “Import Projects” page.
Click Select root directory, then Browse. Eclipse opens the Browse For Folder dialog. Navigate to the helloWorld project and click OK. Import closes the Browse for Folder dialog and places the directory's pathname in the Select root directory text box. The name and pathname of the helloWorld project should appear in the Projects text area.
If you are using a development system other than Eclipse, define a project for helloWorld in any suitable way. The project must include one source file, $JSDK/samples/helloWorld/src/main/java/helloworldApplicationHelloWorld.java.
Note that helloWorld uses a third-party package, log4j. This package is in the Java SDK distribution, and should automatically be included in the application if your development environment is properly configured. However, it requires a property file to run. The property file is located in the project's source tree, at $JSDK/samples/helloWorld/src/main/java/log4j.properties.
Run helloWorld now. Its main method displays some messages, then calls its getApiContext method, which constructs an ApiContext object.
ApiContext apiContext = getApiContext();
As you see, getApiContext returns an ApiContext object. ApiContext is a fundamental part of the Java SDK. It contains credentials and other information that the Java SDK needs to execute any Trading API call. Although ApiContext objects may be reused under certain conditions, an application typically constructs a new one for each API call it performs.
getApiContext constructs an ApiContext object and prompts you for an auth token and a connection point URL. It stores the values that you enter in the ApiContext object, then returns the object to its caller.
private static ApiContext getApiContext() throws IOException {
String input;
ApiContext apiContext = new ApiContext();
//set Api Token to access eBay Api Server
ApiCredential cred = apiContext.getApiCredential();
input = ConsoleUtil.readString("Enter your eBay Authentication Token: ");
cred.seteBayToken(input);
//set Api Server Url
input = ConsoleUtil.readString(
"Enter eBay SOAP server URL (e.g., https://api.ebay.com/wsapi): ");
apiContext.setApiServerUrl(input);
return apiContext;
}
When helloWorld prompts you for the auth token, paste in the auth token you created earlier, then press Enter.
When helloWorld prompts you for a URL, enter https://api.sandbox.ebay.com/wsapi. (This URL represents the SOAP request connection point of the Trading API server for the eBay Sandbox.) Then press Enter.
Now that helloWorld has an ApiContext object, it is almost ready to get the time from eBay.
First, though, helloWorld must construct an instance of a call wrapper class. This object represents the API call that the application will perform.
As a rule, each API call has its own call wrapper class. To get the time of day the application will use the GeteBayOfficialTime API call, whose call wrapper class is GeteBayOfficialTimeCall.
GeteBayOfficialTimeCall apiCall = new GeteBayOfficialTimeCall(apiContext);
Next helloWorld performs the API call by calling the call wrapper class's execute method. In this class the execute method is named geteBayOfficialTime (the same as the name of the API call, but starting with a lower case letter).
The GeteBayOfficialTimeCall.geteBayOfficialTime method sends a SOAP request to the Trading API's connection point and waits for the API's SOAP response. When the response arrives, the Java SDK parses it, stores its elements in the call wrapper object for later use, and returns its most important element as the execute method's value. In the case of GeteBayOfficialTimeCall the most important element of the response is the official time, and its type is Calendar.
System.out.println("Begin to cal eBay API, please wait ... ");
Calendar cal = apiCall.geteBayOfficialTime();
System.out.println("End to cal eBay API, show call result ...");
Finally, helloWorld extracts the time from the Calendar object and displays it.
System.out.println("Official eBay Time : " + cal.getTime().toString());
This ends helloWorld's normal operation.
If an error occurred, helloWorld would throw an exception, and the catch block would catch it and process it.
catch(Exception e) {
System.out.println("Fail to get eBay official time.");
e.printStackTrace();
}
When you run the application, it will prompt you for two pieces of information:
After you enter these items, the application gets the eBay official time through the Trading API and displays it on the console. The application's output will look something like this:
+++++++++++++++++++++++++++++++++++++++
+ Welcome to eBay SDK for Java Sample +
+ - HelloWorld +
+++++++++++++++++++++++++++++++++++++++
==== [1] Account Information ===
Enter your eBay Authentication Token:
AgAAAA**AQAAAA**aAAAAA**ySKaSQ**nY+sNZ2PrBwdj6wVnY+sE22PrAZdj6wJnY+iAZe...
Enter eBay SOAP server URL (e.g., https://api.ebay.com/wspi):
https://api.sandbox.ebay.com/wsapi
Begin to call eBay API, please wait ...
End to call eBay API, show call result ...
Official eBay Time : Mon Aug 02 18:17:02 GMT+08:00 2010
Most call wrapper classes have one or more request properties which may (and often must) be set before the execute method may be called. The GeteBayOfficalTimeCall method is an exception; its has no request properties because the GeteBayOfficialTime API call has none.
As an example of a request property, consider the GetItemCall class, which performs the GetItem API call. The GetItem call has several request properties, most obviously ItemID, which is required in most forms of the call to identify the item to be fetched. GetItemCall has a setter for this property, setItemID, which in most cases must be called before the execute method getItem is called.
In some setters the parameter is a standard class. For example, GetItemCall.setItemID expects its parameter to be a String. In others it is a schema class, which represents a part of the structure (the schema) of the call's SOAP request. As an example, consider the AddItemCall class, which lists an item for sale. It has one request property, Item, which represents a complete description of the item to be listed. The corresponding setter, setItem, expects a parameter of type ItemType, a class which contains many properties, some of which are themselves classes that contain many properties.
In addition to request properties, most call wrapper classes have response properties which the Java SDK sets from the Trading API's response to a request. As helloWorld showed, the execute method typically returns one of these properties. The application can call getters to fetch any of them (including the one returned by the execute method).
As an example, consider the GetCategories API call, which returns information about one or more eBay listing categories. It returns seven properties, among them CategoryArray (an array of elements of type Category, each of which describes one category), CategoryCount (the number of Category elements in CategoryArray), and CategoryVersion (the version number of the category version from which the response was fetched). Consequently the GetCategoriesCall class has seven response properties, and seven getters named getReturnedCategoryArray, getReturnedCategoryCount, getReturnedCategoryVersion, etc.
Response properties, like request properties, may have types that are standard classes or schema classes. For example, the GetCategories.getReturnedCategoryCount getter returns an Integer; the GetCategories.getReturnedCategoryArray getter returns an array of CategoryType elements.
Note that as a rule, every property of a call wrapper class has a getter and a setter. Just because both exist, it does not necessarily follow that both are meaningful.
For example, the GetItemCall call wrapper class has a getItemID method, but because ItemID is a request property, getItemID is not very useful; you must set the property before you can get it, and you must know it before you can set it, so getting it would tell you nothing new.
Similarly, the AddItemCall class has a setMinimumReservePrice method, but because MinimumReservePrice is a response property, setMinimumReservePrice is essentially useless; it has no effect on the item listing, and it will make a subsequent getMinimumReservePrice call return an incorrect value!
© 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.