Amazon’s ECS with SOAP in Eclipse and Xfire

(for mere mortals)

 

Text Box: By the end of this tutorial you will have a very basic SOAP service that can retrieve the image URL for any item on Amazon

 

Introduction:

My goal was to populate a database with movie properties from Amazon. Now, Amazon has both SOAP and REST interfaces to their web services, and 85% of their usage is of the REST[1]. There’s plenty debate on which interface is preferable, a debate I will not contribute to, but I’ll tell you what influenced my choice.

From what I understand, REST works by sending one long URL type request and then you get your data by parsing the XML file your receive. SOAP works in a way similar to remote procedure calls (RPCs), but also wraps all communication in extra packaging formally called an envelope. That is – you just call the right function and viola you have your value/data type.

Personally, I wasn’t too keen on REST because it seemed to mean I had to parse huge XML files and wondered if SOAP could be made to be as simple as it originally was intended to be. I did find a way and hope that it could be of use for anyone out there asking the same questions.

 

Assumptions:

This tutorial is built in Eclipse 3.2 running on JRE 1.5.0_09 – I assume that you are already familiar with Eclipse and have set up your runtime environment. 

If you are using a proxy make sure it is set up before you continue  – Window -> Preferences -> Internet-> Proxy

 

Overview:

Become an Amazon developer

Create a new generic project

Install xfire

Set up the project

Setting up the code

Code explained

Potential problems and fixes

 

 

Become an Amazon ECS developer

1)      Get an Access key. You’ll need it in order to use the ECS service.

2)      Read the agreement – I normally skip this part, but in this case there are important things about how many requests you can send per second, how often you need to update cached information (some daily, other monthly).

3)      Take note (but don’t do anything yet) of the following

a.       The “WSDL” – this is pretty much the specification for what you can do. Not only that, but soon you’ll use a WSDL to automatically generate functions (RPC stubs) for you that you can use to access the service. You will not need to download this file.

b.      The forums – the help you can get here is priceless

 

Create a new generic project

  1. File -> New -> Java project
  2. Select Next
  3. Give the project a name
  4. Select Finish 

Install Xfire

            This is the service that makes all the stubs etc for you! This section is taken from http://xfire.codehaus.org/Eclipse+Plugin

 

Install the plugin

Use the plugin 

To install the Eclipse XFire plugin:

1)            Go to the Help menu, select "Software Updates" and then select "Find and Install."

2)            Select "Search for new features to install" and click Next.

3)            Select "New Remote Site" and enter "XFire" as the name and http://dist.codehaus.org/xfire/update/ as the eclipse update site.

4)            Select OK.

5)            Select Finish

6)            Select all features

7)            Select Next

8)            Accept Terms for the license

9)            Select Next

10)        Select Finish

11)        Select Install

12)        Restart Eclipse

Using the Plugin

  1. In the project you created start the code generation wizard. Go to File->New->Other. Then select Code generation from WSDL document.

    The plugin will then prompt you for the location of your WSDL, where to output the code, and also what package you would like the service in. 

WSDL documents are available by version and by locale.

 

  1. Locale URL

US http://ecs.amazonaws.com/AWSECommerceService/AWSECommerceService.wsdl

UK http://ecs.amazonaws.com/AWSECommerceService/UK/AWSECommerceService.wsdl

DE http://ecs.amazonaws.com/AWSECommerceService/DE/AWSECommerceService.wsdl

JP http://ecs.amazonaws.com/AWSECommerceService/JP/AWSECommerceService.wsdl

FR http://ecs.amazonaws.com/AWSECommerceService/FR/AWSECommerceService.wsdl

CA http://ecs.amazonaws.com/AWSECommerceService/CA/AWSECommerceService.wsdl

 

To access an older WSDL, insert the WSDL version between the last two path elements. For example, to

retrieve the 2006-06-28 WSDL, use the following URI:

http://ecs.amazonaws.com/AWSECommerceService/2006-06-28/AWSECommerceService.wsdl

If a version is omitted, the latest WSDL is returned by default.

 

  1. Output directory

You can use your project root as output directory – go through “Browse”.

 

  1. You can leave the package empty

  2. Here….
     
    Select Finish - this will take a minute or two, but once you're done you'll see the generated classes in your IDE! 

 

Setting up the code

    1. Create a new java class – File -> New -> Class
    2. Give it a name, if you want to create a package for it do so
    3. Make sure the “generate main stub” option is selected
    4. Select Finish
    5. Drag and drop the generated “com” to the “src” folder
    6. Copy and paste the following into the generated template
      • The import statement (see below)
      • The main function (see below)

What this does is look up an item with the ASIN or unique identifier “B00064APK0”,

then retrieves its “image URL”. A breakdown of the code can be found here.

§         Replace  <put your access key here> with your shiny new access key (see the section on becoming an Amazon developer)

    1. Right click on your new class -> Run as -> Java application…
    2. You may run into these two problems
    3. Test out the URL! J
    4. Try different ASINs

 

  1. import com.amazon.webservices.awsecommerceservice._2007_07_16.*; 
2.             public static void main () 
3.             { 
4.             AWSECommerceServiceClient ecs = new AWSECommerceServiceClient(); 
5.             ItemLookup il = new ItemLookup() ; 
6.             il.setAWSAccessKeyId("<put your access key here>") ; 
7.             ItemLookupRequest ilr = new ItemLookupRequest(); 
8.             java.util.List<ItemLookupRequest> list = il.getRequest() ; 
9.             list.add (ilr); 
10.          ilr.setIdType("ASIN"); 
11.          java.util.List<String> id = ilr.getItemId(); 
12.          id.add("B00064APK0"); 
13.          java.util.List<String> responseGroup = ilr.getResponseGroup() ; 
14.          responseGroup.add("Large"); 
15.          AWSECommerceServicePortType p = ecs.getAWSECommerceServicePort() ; 
16.          ItemLookupResponse response = p.itemLookup(il);
  1. System.out.println(response.getItems().get(0).getItem().get(0).getMediumImage().getURL()); 
18.          }
 

Comments for the code

1             Note that the version date is likely to differ…

4             Create a new client that uses the ECS service.

5          There are a number of operations you can use on ECS of which ItemLookup is probably the simplest. If you already know what you want, then it can look it up for you. Perhaps the best use of it is to get more details on a particular item.

6             This is where you identify yourself to the service

7             What happens with your lookup operation is that you first “request” something and then you get a “response”

8-9          In fact, you can make several requests at once, but lets just have the one for now…

10-12   The item can be looked up in a bunch of ways, here we choose to use ASIN as the identifier type. If you know what the ASIN is you don’t risk getting mixed up with items you don’t necessarily want. So we get the identifier object and define it.

13-14   Response groups are great – you can tell Amazon which and how much information you want back. Right now we are going for a whole lot because we want something as superfluous (!) as an image…thus the “Large”.

15        Now that we have a client we just need to connect

16        Ask for the respone

17        And now that we have the response we have to dig out the property we want out of this huge object (otherwise known as a hairy XML file). I’ll leave digging the documentation for this for another day, but let me try to give you an idea. From this response you can get a number of collections of items (depending on your number of requests), for each collection (well, a list really) you can tell it which item you want, for each item you can tell it what property you want etc… In our case Image is an object and has a bunch of properties of which the URL is one.

You can also get small and large images just the same way (just use e.g."getLargeImage()")…

 

Potential problems and fixes

Problems with dependencies.

You have this problem if you get an error that says something about class definitions e.g. Exception in thread "main" java.lang.NoClassDefFoundError.

 

What you want to do then is:

  • Download the full distribution from http://xfire.codehaus.org/Download : xfire-distribution-1.2.6.zip and unzip it
  • Create a user library with the necessary jars and add the library to the project
    • Right click the project folder, and select “Preferences”
    • Go to “Java build Path” in the right hand menu
    • Go to the libraries tab and “Add library”->”User Library”
    • Click “User Libraries” -> Click “New”
    • Name it, e.g. “xFire dependencies”
    • Click “Add jars”, add all the jars under the “lib” folder under the main distribution folder -> Ok
    • Click ok again
    • Tick the library so it is selected now
    • Finish (you should see your new library under the library tab...)

 

Problems connecting

You have this problem if you get this type of error:

org.codehaus.xfire.transport.http.HttpChannel sendViaClient

SEVERE: java.net.NoRouteToHostException: No route to host: connect

 

In this case you might need to configure your proxy in the virtual machine (VM) as well.

§         Right click your main class

§         Select Run As -> Run…

§         Select the “Arguments tab”, and set your VM arguments for the proxy:

-Dhttp.proxyHost=<your proxy host> -Dhttp.proxyPort=<your proxy port>

                              

                               E.g. -Dhttp.proxyHost="proxy.abdn.ac.uk" -Dhttp.proxyPort=8080

 

Questions?                                         

Any additional questions or comments are welcomed at:

n.tintare {at} abdn {dot} ac {dot} uk


[1] http://www.oreillynet.com/pub/wlg/3005?wlg=yes