Trading API
 

Java: SOAP API: Making your first call (GeteBayOfficialTime)

(Code samples for this document can be downloaded here.)

Task

You need to establish communication between your Java application and the eBay SOAP API in a thread-safe manner. To authenticate, you need to pass authentication credentials such as a developer ID, application ID, certification ID, and token. Once authenticated, you need to pass requests to the SOAP API and receive SOAP API responses.

Solution

The best practice for a Java application to authenticate to the SOAP API is to use the ApiContext, ApiAccount, and ApiCredential classes in the eBay SDK for Java to set up communication. You then make the call through ApiCall, using the execute or executeByApiName methods. Both methods take a SOAP API request and return a SOAP API response.

The request can be based on the latest eBay WSDL or on any version of the WSDL. You do not need to use the wrapper classes in the SDK (in com.ebay.sdk.call), or the stub classes generated from the WSDL (in com.ebay.soap.eBLBaseComponents), either of which might be based on an earlier version of the WSDL than the one you want to use.

Description

Before you start writing code, rebuild your eBay SDK for Java with the version of the eBay WSDL you want to use. This step uses the sdkcodegen Ant task built in to the SDK. sdkcodegen generates stub classes from the WSDL and rebuilds JAR files.

One significant difference from using the Apache Axis WSDL2Java command is that the stub classes are generated to com.ebay.soap.eBLBaseComponents, a specific package that works with the eBay SDK for Java.

To rebuild the SDK:

  1. Have Apache Ant installed.
  2. Edit the sdkCodeGen file, especially the eBaySDK.home and eBayWsdl properties. Be sure that eBayWsdl is set to the WSDL version you want.
  3. From the top level of your SDK directory, enter:
    ant -f sdkCodeGen.xml
  4. Check the ReadMe file in the JSDKToSoap sample package for instructions on how to build and run the sample.

Next, you need to write a Java class that sets up the communication between your application and the SOAP API.

To set up communication:

  1. In your Java source file, obtain the credentials you want to use (in this example, they are read from a properties file).
  2. Create an ApiAccount object and set the developer ID, application ID, and certificate ID.
  3. Create an ApiCredential object, and set the ApiAccount object and token.
  4. Create an ApiContext object and set the ApiCredential object.

Eventually, all credentials wind up in the ApiContext object. 


//  Read properties file to load developer credentials
Properties keys = new Properties();
try {
  keys.load(new FileInputStream("keys.properties"));
} catch (IOException e) {
  System.out.println(e);
}

// set devId, appId, certId in ApiAccount
ApiAccount account = new ApiAccount();
account.setDeveloper( keys.getProperty("devId") );
account.setApplication( keys.getProperty("appId") );
account.setCertificate( keys.getProperty("certId") );

// set ApiAccount and token in ApiCredential
ApiCredential credential = new ApiCredential();
credential.setApiAccount( account );
credential.seteBayToken( keys.getProperty("token") );

// add ApiCredential to ApiContext
ApiContext context = new ApiContext();
context.setApiCredential(credential);

Next, you want to set certain values in ApiContext, at least the server URL to call and a timeout value. Note that the Sandbox URL for the SOAP API is:

https://api.sandbox.ebay.com/wsapi

You can also turn on logging by creating an ApiLogging object, setting logging preferences in it, and setting it in ApiContext. Logging displays the SOAP request and response and any exceptions, in this case, to the console window. 


// set eBay server URL to call
context.setApiServerUrl( "https://api.sandbox.ebay.com/wsapi" );  // sandbox

// set timeout in milliseconds - 3 minutes
context.setTimeout(180000);

// set wsdl version number
context.setWSDLVersion("423");

// turn on logging
ApiLogging logging = new ApiLogging();
logging.setEnableLogging(true);
logging.setLogSOAPMessages(true);
logging.setLogExceptions(true);
context.setApiLogging(logging);

Now you can create the ApiCall object, passing it the ApiContext object, and using it to make the call. Note that the request and response objects are created from stub classes, AbstractResponseType and GeteBayOfficialTimeRequestType. The lines after the call to executeByApiName parse the response object to display the eBay time. 


// create ApiCall object - we'll use it to make the call
ApiCall call = new ApiCall( context );

// create soap api request and response objects
GeteBayOfficialTimeRequestType request = new GeteBayOfficialTimeRequestType();
AbstractResponseType response;

// make the call and handle the response
try {
  response = call.executeByApiName("GeteBayOfficialTime", request);
  ...
} catch (ApiException ae) {
    	System.out.println(ae);
} catch (SdkSoapException sse) {
    	System.out.println(sse);
} catch (SdkException se) {
    	System.out.println(se);
}

When you run this class with logging on, you see the full SOAP request and response in the console window. The SDK request is sent from the eBay SDK for Java through Apache Axis. 

- Sending SOAP request to: https://api.sandbox.ebay.com/wsapi?siteid=0&routing=beta
  &callname=GeteBayOfficialTime&client=java&version=423&appid=INDEPENDENV14L9185124FNLW855JL
- <?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <soapenv:Header>
  <ebl:RequesterCredentials soapenv:mustUnderstand="0" xmlns:ebl="urn:ebay:apis:eBLBaseComponents">
   <ebl:eBayAuthToken xmlns:ebl="urn:ebay:apis:eBLBaseComponents">token</ebl:eBayAuthToken>
  </ebl:RequesterCredentials>
 </soapenv:Header>
 <soapenv:Body>
  <GeteBayOfficialTimeRequest xmlns="urn:ebay:apis:eBLBaseComponents">
   <DetailLevel>ReturnAll</DetailLevel>
   <Version>423</Version>
  </GeteBayOfficialTimeRequest>
 </soapenv:Body>
</soapenv:Envelope>

Likewise, the SOAP response is sent from eBay APIs through Apache Axis back to your application. 

- <?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <soapenv:Body>
  <GeteBayOfficialTimeResponse xmlns="urn:ebay:apis:eBLBaseComponents">
   <Timestamp>2005-09-01T20:54:57.993Z</Timestamp>
   <Ack>Success</Ack>
   <CorrelationID>00000000-00000000-00000000-00000000-00000000-00000000-0000000000</CorrelationID>
   <Version>423</Version>
   <Build>e423_core_Bundled_1699649_R1</Build>
  </GeteBayOfficialTimeResponse>
 </soapenv:Body>
</soapenv:Envelope>

The Version element shows the version of the WSDL that generated the response. Note that the version number is 423 (in this example, the version of the Java SDK JAR files we are using to run the sample).

Finally, the class displays the eBay official time, which looks like this: 

official ebay time in gmt is: 2005-9-1 20:54:57
in your time zone Thu, 01 Sep 2005 13:54:57 -0700