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

Tutorial #2: GetUser

GetUser is a simple console application that uses the Java SDK to retrieve information about a specified user.

Complete Source Code

The completed code is provided in the ConsoleGetUser sample located in the SDK samples subdirectory $JSDK/samples/getUser.

Back to top

Before You Begin

Before proceding with this tutorial make sure the following items have been completed:

• You have joined the eBay Developers Program and obtained application keys for the sandbox as described in the Quick Start Guide.
• You have already created a test user for the Sandbox environment ( buyer or seller). You have already generated a user token for that test user.
• You have installed Eclipse, version 3.x or later. You may use a different development system if you prefer, but the tutorial assumes you are using Eclipse.

Building the Application

An Eclipse project for building the getUser application is included in the Java SDK at $JSDK/samples/getUser/ 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 getUser 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 getUser 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 getUser project should appear in the Projects text area.

If You Don't Use Eclipse

If you are using a development system other than Eclipse, define a project for getUser in any suitable way. The project must include one source file, $JSDK/samples/getUser/src/main/java/getUser/ApplicationGetUser.java.

Note that getUser 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/getUser/src/main/java/log4j.properties.

Step 1: Constructing an ApiContext Object

Run the sample application GetUser now. Its main method displays some messages, then calls its getApiContext method to construct the ApiContext object.

   ApiContext apiContext = getApiContext();

Note: the getApiContext method in GetUser is substantially identical to the one in Hello World, so if you already went through that tutorial you may skip this section.

As you see, getApiContext returns an ApiContext object, which contains credentials and other information that the Java SDK needs to execute any Trading API call.

The getApiContext method constructs an ApiContext object, prompting you for an auth token and a connection point URL. It stores the values that you enter in the ApiContext object and returns the object to the 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 GetUser prompts you for the auth token, paste in the auth token you created earlier, then press Enter.

When GetUser 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.

Step 2: Constructing a Call Wrapper Object

Now that GetUser has an ApiContext object, it is almost ready to get user information from eBay.

First, though, GetUser 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 get information about a user the application will use the GetUser API call, whose call wrapper class is GetUserCall.

GetUserCall's UserID field must be set so that the GetUser API call will know what user ID to query.

   String input;
   input = ConsoleUtil.readString("Enter a user ID: ");

   // [Step 2] Create call object and execute the call
   GetUserCall userCall = new GetUserCall(apiContext);
   userCall.setUserID(input);

Step 3: Making the GetUser API Call

Next GetUser performs the API call by calling the call wrapper class's execute method. In this class the execute method is named getUser (the same as the name of the API call, but starting with a lower case letter).

The GetUserCall.getUser 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 GetUser the most important element of the response is the user description, and its type is UserType.

   System.out.println("Begin eBay API request, please wait... ");
   UserType userType = userCall.getUser();
   System.out.println("End eBay API request... ");

Step 4: Displaying the Result

Finally, GetUser extracts several pieces of information from the UserType object and displays them.

   System.out.println("A selection of data from the call:");
   System.out.println( "    In good standing: " + userType.isEBayGoodStanding().toString() );
   System.out.println( "    Email: " + userType.getEmail() );
   System.out.println( "    Positive feedback: " + userType.getPositiveFeedbackPercent().toString() + "%" );
   System.out.println( "    Registration date: " + userType.getRegistrationDate().getTime().toString() );

All of the user information comes from the UserType object. The structure of this object reflects the structure of the User element in the API call's response; it has the same set of fields, including eBayGoodStanding, PositiveFeedbackPercent, RegistrationDate, and so forth. Each field has a getter and a setter.

The GetUser application displays the “In good standing” value from the eBayGoodStanding field, which it gets by calling UserType.isEBayGoodStanding. That method returns a Boolean object, so GetUser calls that object's toString method to get the value in displayable form.

Similarly, GetUser gets the “Email” value from the Email field, which it gets by calling UserType.getEmail. (That method returns a String, so no further conversion is needed.) GetUser gets the “Positive feedback” value from UserType's PositiveFeedbackPercent field, which it gets by calling UserType.getPositiveFeedback, and it gets the “Registration date” value from UserType's RegistrationDate field by calling UserType.getRegistrationDate.

This ends GetUser's normal operation.

If an error occurs, GetUser throws an exception, and one of the catch blocks catches it and processes it. SdkException catches errors that relate to the Java SDK, such as an undefined user ID in the request. Exception catches any other (unexpected) type of error.

   catch (ApiException apiE) {
       System.out.println( "ApiException: " + apiE.getMessage() );
       sdkE.printStackTrace();
   }
   catch (Exception e) {
       System.out.println( "Exception: " + e.getMessage() );
       e.printStackTrace();
   }

Notes and Next Steps

The following are suggestions for extending this tutorial in order to learn more about SDK capabilities.

Suggestions for Further Exploration: Error Handling

Modify the GetUser application to distinguish among the following error conditions and display an appropriate message for each:

• An invalid auth token
• An invalid connection point URL
• An invalid user ID

You'll need catch blocks for the SdkSoapException, ApiException, and SdkHTTPException classes.

Modify the catch block for ApiException to identify and display more than one error.

It may be difficult to make the GetUser application display more than one error. You may try the following approaches:

1. Simulate multiple errors for testing purposes.
2. Look at the Errors by Number page to obtain a list of the errors that the call can return.
3. Write a new application that uses a different API call.

Suggestions for Further Exploration: Extracting Data from a Schema Class

Explore the response descriptions on the GetUser API call's documention page to see what other kinds of data you can make the GetUser application display. Modify the application to display some of these items. See how many nested levels of complex fields you can retrieve data from.

Back to top

User-Contributed 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.