XUI meets eBay

Creating an eBay Store Manager with XUI

by Guillaume Montel

18-Oct-2005

Today eBay is one of the highest profile web service providers with a massive base of active users. Hitching a ride on this juggernaut of e-commerce we will demonstrate how the XUI framework can be used in conjunction with the eBay SDK to build powerful applications. The article will also look at the benefits that a rich-client framework like XUI can bring to a web service platform and we will show how XUI can help solve some of the most annoying usability problems associated with web applications.

We will also discuss how XUI can help to reduce the amount of code necessary to build an eBay application in the context of creating an eBay store manager tool.

Background

The eBay SDK is a free open-source library for building eBay applications. The SDK provides facilities for big seller and power users to manage their account and their transactions without using the website. Using the SDK it is possible to build a wide variety of custom applications and to integrate with other systems.

XUI on the other hand is also a free and open source library framework for building feature rich user interfaces in Java and XML. XUI, it could be said provides a rich-client platform that nicely complements the rich services provided by the eBay SDK. Sometimes web services are used with a thin-client architecture but using these two library to develop an eBay Store Manager application it is possible to offer the eBay seller tools that are faster and easier to use than the generic eBay website.

Requirements

First off we didn't feel there was any point building a one-off application just to showcase XUI. Instead we wanted to create an application that would be of real use in and of itself. We also wanted an application that was extensible so that its components could be integrated with the sort of legacy applications so common in many companies. In short we also wanted an application framework for working with eBay.

To a lesser extent we also wanted a framework that would reduce some of the pain of working with a web services API, a way of reducing the impedance mismatch between the world of eBay and the Java world in which XUI resides.

Other soft requirements included a desire to avoid being tied too closely to the many constants defined in the eBay SDK that can lead to a sort of hard coding. We felt that this sort of dependency would make maintenance difficult so anything that could alleviate such problems would be good.

In terms of functionality we wanted to provide features for power eBay users, for example features that would help in the setup and administration of business to business eBay stores rather than one-off eBay sales. We also wanted to facility certain types of procurement operations, searching for the best prices for a range of items. Ultimately we wanted to build an eBay enabled e-commerce engine for rich-client applications, something that a XUI or Carousel user could use to build an integrated eBay store for specific e-commerce requirements.

The Solution

The eBay Store Manager has been developed using the beta version of XUI 2.0 and the NetBeans IDE. Using the strengths of XUI, a framework has been created that gives an easy and fast navigation between each part of the application. Indeed, as the XUI frameworks is based on Java, very little loading time is needed for the navigation and so the only delays arise from the queries to eBay. For example, the process to sell an item under eBay needs only two XUI pages whereas the same process needs at least five pages using the website.

The process of working with eBay is further improved by the very nature of rich-client applications as the application can store information locally. The local storage helps reduce or even eliminate round-trips to the eBay server for updates making the application far snappier than the equivalent set of web pages.

The eBay Store Manager consists of two major parts, one for selling and the other for bidding and buying items. The two pronged approach was necessitated by the lack of a bid API in the eBay SDK, however despite this major short coming the division is not apparent to the end-user of the eBay Store Manager application.

What does XUI provide?

So, the XUI framework is a developer toolkit for reducing the amount of code necessary to develop a Swing or AWT application. It helps to create key components in the graphical user interface, including widgets, event handlers, data bindings and validation rules. An XML based system is used for the creation of the user interface and the various styles that can be applied to the user interface (UI). Moreover a Net Beans plug-in provides a visual editor that works with the familiar “drag and drop” metaphor, so all the development of XUI application can be carried out on a single platform.

And what about the eBay SDK?

The world famous e-commerce platform eBay gives to the open source community a range of developer APIs to build eBay applications. The entire API is based on SOAP and the Java SDK interfaces with the XML objects so that the Java programmer is insulated from the low level details of the SOAP API.

Numerous methods and calls to eBay are provided and allow you to build a specific application with your own user interface and some specific functions not available under the eBay web site. A sandbox environment is provided for developers to test their application before deploying to the production environment. The sandbox environment is similar to the real one except that transactions and items under are fictitious.

Despite the Java SDK being a free open source library, you need to register with the eBay developer's program to get keys. Without the sandbox keys you won't be able to make calls to eBay. The keys are free and you need only pay for transactions once your application is finished and working under the production environment...

Nevertheless, the eBay SDK doesn't manage bidding on items. To work around this problem, screen scrapping must be used. While using screen scraping is free, the code is harder to maintain because it reposes on the web site that is liable to change without notice. If eBay decides to modify the web page implementation or appearance, the bid function may not work anymore.

An example of the eBay SDK and XUI

The user interface for the eBay Store Manager is built using an XML file per page and this XML has an associated Java class. The XML for the Welcome page is shown below:

As you can see the XML style sheet is divided in three elements:

• The Components element where the different components are declared, with their style, their name and their content
• The Events element where a call is specified to a function in the associated Java class
• The Data element where you can bind data from a model to the user interface components

The layout was specified using absolute coordinates due to time constraints but XUI can supports various layout managers and these would probably be a better option particularly when localizing the application.

The associated Java class provides the implementation of the event handlers and the source code for this class can be seen below:

package xui.xoetrope.ebayExample;

import com.ebay.soap.eBLBaseComponents.SiteCodeType;
import net.xoetrope.builder.NavigationHelper;
import net.xoetrope.xui.data.XModel;
import net.xoetrope.xui.data.XBaseModel;


public class Welcome extends NavigationHelper 
{
    // The XModel are used to organize and transfer your data between each windows    
    private XModel userModel,siteModel; 
    
    /**
      * This method when the page associated to this class is created
      */

    public void pageCreated()
    { 
       // Initialize the model used
       userModel = ( XModel ) rootModel.get("eBay"); 
       siteModel = ( XModel ) rootModel.get("site");
    
       // Initialize the list of value in the siteCombo from the list available in 
           // the eBay Java SDK
       StaticData staticData = new StaticData(SiteCodeType.class, siteModel);  
       updateBindings();
    }
     
     /** 
       * This method is called when the button “btnConnect” is clicked
       */
     public void connect()
     {
         // Save the different value in the components
         saveBoundComponentValues();

         // Call eBay
         GetEbayTime getTime = new GetEbayTime(userModel);
         String time = getTime.getTime();

         // Add the date value in the model
         XBaseModel timeBaseModel = new XBaseModel( userModel,"officialTime", time );

         // Update all the value of the graphic components from the model defined in 
                 // the data block
         updateBindings();
    }
}

Much of the coding in the application is typical of a XUI application so we will not dwell on it further in this article.

The real value of the eBay Store Manager obviously comes from the integration with eBay and to demonstrate this let's look at the eBay query to get the official time. For this query two classes have been made:

• The EbayConnection classes to set up the connection to eBay. This class is reusable as it can be used for the entire query being made to eBay.
• And the GetEBayTime class to get the official 'eBay' time. The class extends the EbayConnection class.

The EbayConnection is shown below:

package xui.xoetrope.ebayExample;

import com.ebay.sdk.ApiAccount;
import com.ebay.sdk.ApiContext;
import com.ebay.sdk.ApiCredential;
import com.ebay.sdk.ApiLogging;
import com.ebay.sdk.eBayAccount;
import com.ebay.soap.eBLBaseComponents.SiteCodeType;
import net.xoetrope.xui.data.XModel;


public class EbayConnection 
{
    /**
     * where all the information about the connection are stored
     */
    protected ApiContext apiContext=new ApiContext();
    
    /**
     * The constructor which build the connection with eBay
     * @param connectionModel This is the model where all the information needed for 
     * the connection are stored
     */
    public EbayConnection(XModel connectionModel) 
    {
        ApiCredential cred=apiContext.getApiCredential();
        ApiAccount ac=cred.getApiAccount() ;      
    
        // Retrieve all the value from the model
        ac.setDeveloper( connectionModel.getValueAsString( "devID" ));
        ac.setApplication( connectionModel.getValueAsString( "appID" ));
        ac.setCertificate( connectionModel.getValueAsString( "certID" ));
        apiContext.setApiServerUrl( connectionModel.getValueAsString( "url" ));
        cred.seteBayToken( connectionModel.getValueAsString( "token" ));
        apiContext.setSite( SiteCodeType.fromString( 
                        connectionModel.getValueAsString( "site" )));
        apiContext.setWSDLVersion( "417" );  // the current version of WSDL services
    }   
    
    /**
     * method used to retrieve the ApiContext
     * @return the parameters necessary to make a call to eBay
     */
    public ApiContext getTheApiContext()
    {
        return this.apiContext;
    }
    
}

The class illustrates several of the techniques used within the application. First the application integrates its data into the XUI data model so that not only is data management simplified but it also helps remove hard coding from the application. In the above example the various named configuration parameters are obtained from the model and this gives the possibility of getting those settings from external files or from other parts of the application (other pages) without introducing any tight binding.

It is worth noting that the WSDL (Web Service Description Language) is regularly updated by eBay and the XML response to a query can vary with this versioning. To use the latest version of WDSL you must check all the queries in your program or check the eBay web site documentation. During the development changes to the WSDL version were necessary to work around some problems with missing or incomplete data but wrapping the eBay calls in the manner described above helps isolate such changes and thus stabilizes the system a little more.

Continuing and building on the class the official time is then retrieved via the eBay connection:

package xui.xoetrope.ebayExample;

import com.ebay.sdk.call.GeteBayOfficialTimeCall;
import com.ebay.sdk.util.eBayUtil;
import com.ebay.soap.eBLBaseComponents.DetailLevelCodeType;
import java.util.Calendar;
import java.util.Date;
import net.xoetrope.xui.data.XModel;


public class GetEbayTime extends EbayConnection
{
    String dateString = "";

    /**
     * Setup a call to get the eBay time
     * @param userModel the connection model
     */
    public GetEbayTime( XModel userModel ) 
    {
        //set the connection from EbayConnection
        super( userModel );
    }
    
    /**
     * Return the time. Call eBay and build a string corresponding to the eBay 
     * official time
     * @return the string value of the date or an zero length string if an error 
     * occurs.
     */
    public String getTime()
    {
        try {
            DetailLevelCodeType[] detailLevels = new DetailLevelCodeType[] 
                        {DetailLevelCodeType.ReturnAll};
        
            // Set the call with the APIContext
            GeteBayOfficialTimeCall api = new GeteBayOfficialTimeCall( 
                                super.getTheApiContext());
            api.setDetailLevel( detailLevels );

            // Execute the call to eBay
            Calendar offTime = api.geteBayOfficialTime();
            Date dt = offTime.getTime();

            // Transform the date into a string with the Java eBay SDK API
            dateString = eBayUtil.toAPITimeString( dt );
        } 
        catch( Exception ex ){
            System.out.println(ex.getMessage());
            dateString = "";
        }

        return dateString;
    }
}

Looking back to the Java class for the Welcome page we can see the GetEbayTime class in use. The data retrieved is added to the data model and the bound UI components are updated.

Much of the eBay SDK is wrapped in this way thereby hiding the low level details and making the API more convenient for use within XUI just as we had planned. That was OK for a simple call, but as mentioned above the eBay SDK makes significant use of specific types, almost enumerated types and it was not very convenient to use these types. Either hard coding was required or the types had to be listed in external configuration files and neither of these approaches was all that conducive to use with drop down lists or other widgets that you would expect to see in a rich user interface.

The eBay SDK lists a large number of constants for its various types in separate classes and fortunately the structure of these types is consistent. To overcome the problems with the eBay type system we built some utility classes. One such utility class is the StaticData class that uses reflection to determine the constants used by eBay and then stores the values within the XUI data model. Once the data is in the model it can be bound to the UI components with ease. Relying on reflection also means that list of constants will always be up-to-date.

An example of this use of constants is the list of eBay site. The list on its own would be hard to maintain 'by hand' so the benefit of the utility is plain. Here's how the utility is used:

public class StaticData 
{
    private Collection listFields = new ArrayList();
    
    /**
      * Load the value of a class into a model
      * @param className the class where the value will be loaded
      * @param outputModel the model where value are stored
      */
    public StaticData( Class className, XModel outputModel ) {
        Field[] fields = className.getFields();
        for ( int i = 0 ; i < fields.length ; i++ ){
          if ( !fields[ i ].getType().equals( org.apache.axis.types.Token.class )) 
            listFields.add( fields[ i ].getName());
        }
        Object[] list =  listFields.toArray();
        for ( int i = 0; i < list.length; i++ )
          XBaseModel listModel = new XBaseModel( outputModel, "row"+i, 
                  list[ i ].toString());
    }    
}

Comment

So XUI framework has numerous advantages above and beyond using Swing on its own for developing your Java UI:

• As you can see, the amount of code required is very low.
• Most of the time, you don't need to declare your graphic component in the class associated to your page and instead you only bind data, choosing a good XModel. The framework takes care of updating the UI.
• The data model in XUI is really useful because it makes the link between the interface and the Java code. Furthermore, as the model is an abstract hierarchy, you can use model node to add a value with its path (such as the dateString in the connect() method above).
• It is also very easy to add events. For this, you only need to declare it in the XML page file with the method name in the class, the target and the type of event. Therefore you can develop the method in your class without worrying about the user interface or the details of the event handling mechanism.

All the calls to eBay have the same basic workings. You need to define an APIContext (the eBay object where your developer parameters are set) and then to use the constructor of your call. The use of the XModel simplifies the process of initializing the connection to eBay.

The XModel is also a fast and effective way to communicate data between each page or between the application source code implementing your business logic and your user interface.

More than just saving some code, the combination of the eBay SDK and XUI results in a fully compatible eBay application with many advantages.

• The navigation between windows can be provided by the framework.
• The different parts of the program don't need any noticeable load time, as it's a Java program and network latency is avoided. More over, you can reduce the number of pages compared to the eBay web site and have faster access to all the information you need.
• Adding items to eBay can be done in few seconds, only the title, category, start price and the description need to be written. So you can start to sell your products by filling in just one quickly loaded page. The rest of the information can be loaded implicitly from local storage.
• Once you have retrieved the data from eBay it can be stored in a database. XUI then has many facilities to manipulate or display that data. For example, your table is converted into a model node and can be displayed directly or in parts
• When any eBay specific code is written the time needed to create the user interface is really short. You can use the interactive graphical editor and/or code the XML pages manually. So, it's really easy to modify your interface.

A whirlwind tour of the eBay Store Manager

Here are a few screenshots to illustrate what is in the complete application:

Conclusions

To build a fully compatible eBay application adapted to your need, XUI provides you an easy and fast way to design and creates your interface. You can develop your application module by module, integrate it to your database and use the advantages of the eBay SDK rather than the web site for more efficient sales.

Guillaume Montel is a student of Computer Science at the École Nationale des Mines at Nantes, France. Guillaume has worked at Xoetrope during his summer 2005 work placement. He can be contacted at

References:

The eBay developer program: http://www.developer.ebay.com/

The eBay sandbox: http://www.sandbox.ebay.com/

The XUI project: http://sourceforge.net/projects/xui

XUI tutorial: http://prdownloads.sourceforge.net/xui/IntroTutorial.zip?download

Full description of XUI:

To run the full application it is necessary to obtain eBay sand box keys. The application also set up a backing database to store history and to facilitate integration with other system (e.g. ERP, MRP or CRM Systems) and this requires that an odbc system DSN be setup as well (the system was developed using the jdbc-odbc bridge for convenience). Once the downloaded file has been unzipped it can be started by executing the run.bat file. Details of the eBay sandbox and database configuration can then be entered on the configuration page.

Please note that the application is provided AS IS and without warranty and is only intended as technology demonstration. The software remains copyright of Xoetrope Ltd.

The application and source code associated with this article is available to registered users... Click here to logon or register.