eBay Java SDK
|
ConsoleAddItem is a console application that uses the Java SDK to list an item for sale. Although its logic is very simple — a few item properties are entered through the console, and others are hard-coded — it could in principle be expanded into a genuinely useful application for use by sellers.
The completed code is provided in the consoleAddItem sample located in the SDK samples subdirectory $JSDK/samples/consoleAddItem.
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/consoleAddItem/ 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 consoleAddItem 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 consoleAddItem 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 consoleAddItem project should appear in the Projects text area.
If you are using a development system other than Eclipse, define a project for consoleAddItem in any suitable way. The project must include one source file, $JSDK/samples/consoleAddItem/src/main/java/ApplicationAddItem.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/consoleadditem/src/main/java/log4j.properties.
When you run ConsoleAddItem, its main method displays some messages, then calls its getApiContext method, which constructs an ApiContext object.
ApiContext apiContext = getApiContext();
Note: the getApiContext method in ConsoleAddItem is substantially the same as the ones in helloWorld and GetUser. If you have already studied one of those tutorials, you may skip this section.
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 ConsoleAddItem prompts you for the auth token, paste in the auth token you created earlier, then press Enter.
When ConsoleAddItem prompts you for a URL, enter https://api.sandbox.ebay.com/wsapi. (This is the URL of the SOAP request connection point of the Trading API server for the eBay Sandbox.) Then press Enter.
Next, ConsoleAddItem calls the local method buildItem.
ItemType item = buildItem();
buildItem constructs and initializes an ItemType object. ItemType decribes all of the properties of an item, so it is an essential element of an application that adds an item to the eBay marketplace.
buildItem sets several of the ItemType object's fields with fixed values, and others with values read from the console.
private static ItemType buildItem() throws IOException {
String input;
ItemType item = new ItemType();
// item title
item.setTitle(ConsoleUtil.readString("Title: "));
// item setDescription(ConsoleUtil.readString("Description: "));
// listing type
item.setListingType(ListingTypeCodeType.FIXED_PRICE_ITEM);
. . .
Several of ItemType's fields — StartPrice, CategoryID, and ReturnPolicy — are complex fields. (They contain sub-fields, rather than a single value.) The Java SDK represents these fields with schema classes, so called because they represent elements of the Trading API's request schema. Complex fields occur in both the requests and responses of many Trading API calls.
Some of the complex fields are initialized with constants and others with values read from the console, as these two code snippets illustrate.
// return policy
ReturnPolicyType returnPolicy = new ReturnPolicyType();
returnPolicy.setReturnsAcceptedOption("ReturnsAccepted");
item.setReturnPolicy(returnPolicy);
// listing price
input = ConsoleUtil.readString("Start Price: ");
AmountType amount = new AmountType();
amount.setValue(Double.valueOf(input));
item.setStartPrice(amount);
Because the structure of the Item class is complicated, buildItem uses two helper methods, buildShippingDetails and buildItemSpecifics, to do the initialization.
Note that requests and responses can contain complex fields that are nested many levels deep. Large, complicated schema classes (of which ItemType is one) often contain four or five or more nested levels of complex fields.
For example, the AddItem API call, which ConsoleAddItem uses, describes the new item in its Item field, a complex field of type ItemType. One subfield of Item is ShippingDetails, a complex field of type ShippingDetailsType, which describes the seller's shipping terms for this item. One subfield of ShippingDetails is ShippingServiceOptions, a complex field of type ShippingServiceOptionsType, which describes the shipping options that the seller offers for this item. One subfield of ShippingServiceOptions is FreeShipping, a simple field whose value is a Boolean.
Now that ConsoleAddItem has an ApiContext object and an Item object, it is almost ready to list an item.
First, though, ConsoleAddItem must construct and initialize 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 list an item the application will use the AddItem API call, whose call wrapper class is AddItemCall.
AddItemCall's Item field must be set to define the item to be listed.
AddItemCall api = new AddItemCall(apiContext); api.setItem(item);
Next ConsoleAddItem performs the API call by calling the call wrapper class's execute method. In this class the execute method is named addItem (the same as the name of the API call, but starting with a lower case letter).
The AddItemCall.addItem 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 AddItem the most important element of the response is the Fees field, which lists the fees that apply to the item listing, and its type is FeesType.
FeesType fees = api.addItem();
System.out.println("End to call eBay API, show call result ...");
Finally, ConsoleAddItem extracts the listing fee from the FeesType object returned by AddItemCall, and displays it.
Because an item listing can incur several fees (for the item itself, gallery placement, extra hosted pictures, and so on), Fees contains one subfield (Fee), an array of FeeType elements that describe the individual fees. The description of Fees and its constituent fields in the Trading API Call Reference reflects this.
The field description table shows that Fees is a complex field with one component named Fee. The Fees.Fee field's entry in the table's Occurrence column says “Always, repeatable: [1..*].” In other words, the Fee sub-field can occur more than once in the Fees field; it is always present (the minimum number of occurrences is 1) and there is no limit on its repeating (the maximum number of occurrences is *, or undefined).
For example, an item that incurs three fees will return an XML response that looks something like this:
<?xml version="1.0" encoding="utf-8"?>
<AddItemResponse xmlns="urn:ebay:apis:eBLBaseComponents">
. . .
<Fees>
<Fee>
. . .
</Fee>
<Fee>
. . .
</Fee>
<Fee>
. . .
</Fee>
</Fees>
. . .
</AddItemResponse>
AddItemCall's execute method returns a three-element array. A few statements later, the statement that extracts the listing fee refers to the Fee array with the expression fees.getFree().
FeesType fees = api.addItem(); . . . fees.getFee() ...
The statement uses a utility class and method to locate the Fee object that represents the listing fee.
eBayUtil.findFeeByName(fees.getFee(), "ListingFee") ...
From the Fee object it extracts a field that represents the amount of the fee (somewhat confusingly also named Fee, but whose type is CurrencyCodeType).
eBayUtil.findFeeByName(fees.getFee(), "ListingFee").getFee() ...
From that field it extracts the sub-field Value, whose value is a simple type (a double) rather than a schema class.
double listingFee = eBayUtil.findFeeByName(fees.getFee(), "ListingFee").getFee().getValue();
Finally it displays the amount of the fee:
System.out.println("Listing fee is: " + new Double(listingFee).toString());
ConsoleAddItem's last operation is to display the newly listed item's item ID. It gets the ItemID from the response field ItemID by calling the getter getReturnedItemID.
System.out.println("Listed Item ID: " + api.getReturnedItemID());
Many call wrapper classes, but not all, follow the convention that a response field's getter has the same name as the field with the prefix getReturned, instead of get.
Many API calls return more than one top-level field in the response. AddItem, for example, returns ItemID (the item ID assigned to the item by eBay), StartTime (the item's start time), and EndTime (the item's scheduled end time), in addition to the Fees field that is considered “most important,” and so is returned by the execute method.
For each such API call, the call wrapper class has a getter for each top-level response field. For example, AddItem has getReturnedItemID, getReturnedStartTime, and getReturnedEndTime methods. (It also has a getReturnedFees method that returns the same value as the execute method — after the execute method has returned success.)
© 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.