How to implement an EntityProxy interface without frustration

One of new GWT 2.1 features is RequestFactory; “an alternative to GWT-RPC for creating data-oriented services.”. The main drive behind many of the new features is Spring Roo with GWT support. RequestFactory offers some great advantages over GWT-RPC, but the bad news is, it’s very lightly documented. Also as RequestFactory adds an extra layer of abstraction with advanced functionality, like keeping objects synchronized, it makes it difficult to use and understand in practice without good documentation.

Part of the difficulty of using RequestFactory and more specific EntityProxy is the implied usage conventions. With EntityProxy client/server code part of the implementation depends on implicit naming conventions. This is similar to GWT-RPC where the service and serviceAsync interfaces are bound by naming conventions, not code. As a consequence it’s easy to forget or create invalid code, which you unfortunately will find out at runtime. Leading to longer development cycles and frustration.

Implementing an EntityProxy

In this article the focus is on implementing an EntityProxy interface without getting run time error because you missed some implicit convention. I tried to create a comprehensive list as possible, but don’t sue me if I missed something… I’m assuming from here you have a basic understanding of how to use an EntityProxy.

EntityProxy is the core of an alternative method to transfer data between client and server. With GWT-RPC you need to create Data Transfer Objects(DTO). A DTO contains simple getters and setters that mirror your server side data object. A DTO is necessary because your server side objects can not be used on the client side, due to dependencies on libraries that can’t be compiled with GWT. A big disadvantage of a DTO is that you need to copy data from the DTO into and from the server object. Code you need to write manually. With EntityProxy instead of creating a DTO you create an interface, and specify on that interface the getter and setter methods. GWT will generate a class for you from that interface. A small disadvantage of this approach is that is more difficult to debug. You have to include the generated path in your source path to access the code if you need and your data in the generated class is somewhat buried. But together with RequestFactory it gives you a simpler approach to keep data synchronized on the client. A very simple Employee EntityProxy example with a getter and setter method that relates to a field name in you server side class Employee would look as follows:

    @ProxyFor(Employee.class)
    public interface EmployeeProxy extends EntityProxy {

       String getName();

       void setName(String name);

       @Override
       EntityProxyId<EmployeeProxy> stableId();
    }

With this interface, anytime you need an Employee object on the client you use the EmployeeProxy and on the server side you program with the Employee class. Meaning you may never use one of them on the other side! This approach with the DTO interface looks like the same overhead as a DTO class. But it frees you from having to write the copy code from the data class into the DTO class and back. With the RequestBuilder you create instances of the EntityProxy objects, but I won’t go the details on how to do that in this article.

Rules to obey

When implementing an EntityProxy interface there are a number of conventions you need to know and follow. The main cause of problems simple problems when using EntityProxy are because there is no relation between the EntityProxy interface and the server side data object. As a consequence you have no compile time support to check if you missed something, like if the methods you put on the interface actual exist on the data class on the server. Incorrectly implementations result in run time errors and are sometimes buried in the stack trace or hard to find in production if the stack trace was not logged. Al you get in the client is an empty error message. GWT documentation already names a number of the items shown below, but here is an more comprehensive list:

For you EntityProxy interfaces:

  • Each method in your interface must have an matching method in the server side class.
  • Only get or set methods are allowed in your interface.
  • You don’t have to add getters/setters for all member fields of server side data class in the EntityProxy interface, only those you want to use on the client side
  • If you add a setter method to your EntityProxy you must add a getter or else the setter will have no effect.
  • The naming of the getter and setter method must match a field member in your server side class. If you have a getLocation() getter you must have a field named location in the server data class. This restriction has been removed in GWT 2.1.1. But when using an Editor with an EntityProxy you must name the Editor field (in Class) or method (in Interface) exactly as the getter/setter.
  • While you need matching getter/setter/fields the getters and setter don’t have to operate on the same type as the field, but it must match the type of the getter/setter method. So it correct to have an field of type Integer, while you getter/setter methods in the server side object and EntityProxy operate on String.
  • GWT 2.1 doesn’t support native types (like int) as return type for methods in the proxy interface and only List and Set data grouping types are valid. For the latter it means you can for example return an ArrayList, but the return type of the method must be List
  • In the example above the stableId() is override from the interface EntityProxy. You must always override the stableId() method can override the stableId() method so it will be easier to use with the RequestFactory find method, but it’s not a requirement.

While your server side data object have no knowledge of the client side, and are not dependent on GWT they must meet some requirements to make things work. Here is the list for your server side data objects:

  • A no-arg constructor. This may be the implicit default constructor. This is required unless you use a Locator, which takes the control of object instantiation.
  • The data class must have a method getId() that returns a String or Long any type (Since GWT 2.1.1) that represents the persisted ID.
  • A getVersion() method, which returns a non null value. This value should be incremented or changed each time that specific instance of the object is persisted. GWT uses this version number to check whether the object was changed. Some ORM frameworks have support for Versioning and thus can be implemented with ease. Since GWT 2.1.1 the return type is no longer limited to Integer and with a Locator you can use a different name for the method instead of getVersion().
  • A getVersion() method my not return null. GWT will not set version if you create a new object on the client. When a new object is persisted GWT will call getVersion() and you must make sure it doesn’t return null, even while it was never set to any value.
  • A method: public static entity_type find<entity_type>(id_type id). This method is used by RequestFactory find method to lookup individual instances. It seems possible since GWT 2.1.1 to do have a non static method by using a Locator. But I haven’t tried it.

To summarize. As you’ve seen you need to keep an eye on a number of rules to correctly implement and use EntityProxy interfaces. It might be possible in the future better tool will be released or some limitations will be lifted. For now keep the list at hand when implementing EntityProxy interfaces or you will become frustrated each time you hit a run time error…

This article only covered EntityProxy but to correctly and efficient use the RequestFactory there is enough material to write about. Thomas Broyer wrote two articles on GWT 2.1.1 RequestFactory Part I and Part II that are a good starting point. Finally if you find other rules I’ve missed let me know.

UPDATE January, 26 2011: Thanks to Thomas Broyer for commenting and pointing out some incorrect claims. Based on his feedback I’ve updated the text.

Posted in gwt | Tagged , , | 2 Comments

Introducing my new business site: h72.nl

In July this year I started as a freelancer. After many years working mostly for small startup product companies I decided to become a freelancer specialized in GWT (Google Web Toolkit).

In 2006 Google released GWT. From its inception I’ve been following and working with GWT and became a specialist in GWT. As more and more companies start to embrace GWT it leads to business opportunities for developers and freelancers, but also the need to train people.

To better position myself I’ve moved my old blog at bouwkamp.com to this site. If you’ve been following my old blog for GWT related topics please update your feed to the new site. Here is the link for the rss2 feed: h72.nl/?feed=rss2.

Posted in Uncategorized | Comments Off

A Solution to perform GWT RPC calls from within a Wave Gadget

The Problem

When you’re building a Google Wave Gadgets with GWT you might want to communicate with the server via RPC, because that’s any easy way to communicate. Until now it was not really possible to do. The reason, the standard RPC implementation works only when the client application is loaded from the same server to which the RPC calls are made. This is due to the cross-site restriction browsers enforce to avoid harmfull actions performed by malicious sites. The problem is that Wave caches the gadget and runs it from it’s own server, instead of the originating server, and thus when the Gadget is loaded and runs, the original server is now on another domain, and therefor it’s not possible to perform the standard RPC calls.

The Solution

The solution lies in the iGoogle Gadget api. Wave Gadgets are build upon the iGoogle Gadget api and the Gadget api contains a proxy method to perform RPC calls to another server. Calls are routed through the iGoogle Gadget proxy server and for the client, the gadget code, it seems as if it performs a direct call to the external server. This is nothing new. However, there was not yet a GWT wrapper for access to these Google Gadgets api calls, and thus you would have to write that yourself.

But that’s about to change. When I was informed by the GWT team they where working on a new release of the GWT Gadget api I noticed the wrapper for the iGoogle proxy methods were added and wrote additional code to make it easy to do actual RPC calls from Wave. Now this code has been added to get GWT Gadget api library and will be present in the comming release. The trunk already contains these method, so if you want to start today, build your own version of the GWT Gadget api from trunk.

How To

Making RPC work within a Wave GWT Gadget is now easy. With these 2 steps any GWT Gadget can be made to work to use RPC.

1) For each service you want to use you need to redirect it to the Gadget api proxy to perform RPC call. This is done with the static method redirectThroughProxy. As shown in the following example:

  YourServiceAsync yourService = GWT.create(YourService.class);
  GadgetsGwtRpc.redirectThroughProxy((ServiceDefTarget) yourService);

2) On the server side you need to override the method readContent in your servlet implementing the service, the one extending RemoteServiceServlet:

  @Override
  protected String readContent(HttpServletRequest request)
      throws ServletException, IOException {
    return RPCServletUtils.readContentAsUtf8(request, false);
  }

This is needed because the current implementation of the iGoogle Gadget and thus Wave proxy rewrites the content type header and the GWT RPC implementation checks for this type to be text/x-gwt-rpc.

One Final Remark

Wave Gadgets can store state in the Wave itself. When storing state it’s also available in the Wave’s history. When you decide to store state on your own server, via RPC, you need to take care of showing historic versions yourself. This means depending on the case it’s better to store state in the Wave instead of obtaining the data from your own server.

Thanks to the GWT team for adding the code and make it easy to perform RPC calls from within Wave Gadgets.

To easily write Wave Gadgets with GWT use the cobogwave library that wraps all Wave specific methods.

Update June, 28: The new iGoogle GWT Gadget api is available for download. Version 1.2: http://code.google.com/p/gwt-google-apis/downloads/detail?name=gwt-gadgets-1.2.0.zip

Posted in gadget, gwt, wave | 2 Comments

Update for cobogwave, the GWT wrapper for the Wave Gadget api: support for Private State and new Wave styled UI widgets

Just in time for GoogleIO 2010. Here is the updated version of the cobogwave library, the GWT wrapper for the Wave Gadget api. Recently, the Wave gadget api got some new features, and now the GWT wrapper library supports this new functionality.

Private State

State values stored in a gadget are global for every viewer of the wave containing the widget. Changes made by one of the viewer are seen by all other viewers. With the new api changes, it’s now possible to store private state. This means those state values are only accessible by the viewer who made the changes. Private state can be used to store data for a viewer, that should not be accessible or seen by other viewers.

Wave styled widgets

In the wave gadget api there are 3 methods added to create ui widgets with a Wave style. While it doesn’t seem to be supported officially, the cobogwave GWT wrapper now provides access to those methods such that they can be used as standard GWT widgets. The 3 widgets made accessible are: Button, DialogBox and DecoratedSimplePanel.

Button An anchor styled as button.

Wave button

DialogBox A DialogBox styled as a Wave dialog box.

Wave DialogBox

DecoratedSimplePanel A GWT SimplePanel with Wave style.

Wave DecoratedSimplePanel

Download the cobogwave library at http://code.google.com/p/cobogwave/.

Posted in gadget, gwt, wave | Comments Off