Thursday 28 June 2012

Eclipse GWT Plugin Update Sites

This article lists all GWT Plugins available for various versions of the Eclipse IDE (or any development tool built on Eclipse such as SpringSource Tool Suite). The official GWT Plugin page (https://developers.google.com/eclipse/docs/download) now (2012-07-02) includes the latest version of the plugin together with all previous versions.

The following table lists the updates links for various versions of Eclipse.

Eclipse 4.2 (Juno) http://dl.google.com/eclipse/plugin/4.2
Eclipse 3.7 (Indigo) http://dl.google.com/eclipse/plugin/3.7
Eclipse 3.6 (Helios) http://dl.google.com/eclipse/plugin/3.6
Eclipse 3.5 (Galileo) http://dl.google.com/eclipse/plugin/3.5

Please refer to the GWT Plugin (https://developers.google.com/eclipse/docs/download) for further information about how you can install it.

Saturday 23 June 2012

Practical Example of GSON (Part 2)

Please note that this page has moved to: http://www.javacreed.com/gson-deserialiser-example/.

The first article I wrote about GSON (part 1) is (at the time of writing) the most popular article in my small blog. Thus, I decided to write a second article and add more practical and advance examples which anyone can use. As also noted in my previous article, the official GSON site is: http://sites.google.com/site/gson/.

In this article we will see how to parse complex JSON objects into existing Java objects that do not necessary have the same structure as the JSON object. We will see how the use of the GSON deserialiser (JsonDeserializer) in order to control how the JSON object maps to the Java object.

The code shown here is all available at: http://code.google.com/p/gson-practical-examples/source/checkout.

The readers are encouraged to first read part 1 before proceeding, unless they are already familiar with GSON.

A Simple Example

Let's say we have the following JSON object, where it contains four Java books titles written by various, well known, authors.

{
    '1': 'Effective Java (2nd Edition)',
    '2': 'JavaTM Puzzlers: Traps, Pitfalls, and Corner Cases',
    '3': 'Java Concurrency in Practice',
    '4': 'Java: The Good Parts'
}

Note that each name/value pair has a number as its name and the book title as its value. Using the methods discussed in part 1 would create a problem. In that article, Gson is expecting to find variable names in Java with the same name as that found in JSON. But names in Java cannot start with a number. They can contain a number, but cannot start with one (as described in chapter 6 of the Java Language Specification).

So how can we parse this JSON object and use it in Java?
We can use the JsonDeserializer to parse the JSON object into our Java object the way we want it. Using the JsonDeserializer, we have full control over how JSON is parsed as we will see in the following example.

Consider the following simple Java object.


package com.albertattard.examples.gson.part2_1;
import java.util.ArrayList;
import java.util.List;

public class Books {

  private List<string> booksTitles = new ArrayList<>();

  public void addBookTitle(String title) {
    booksTitles.add(title);
  }

  @Override
  public String toString() {
    return booksTitles.toString();
  }
}

This Java object will be used to hold the books listed in the JSON object shown earlier. Note that JSON object has four fields, one for each book, while the Java object has a list in which these books are saved. The structure of these two objects (Java and JSON) is different.

In order to be able to parse JSON to Java we need to create our own instance of the JsonDeserializer interface as shown next.


package com.albertattard.examples.gson.part2_1;
import java.lang.reflect.Type;
import com.google.gson.JsonDeserializationContext;
import com.google.gson.JsonDeserializer;
import com.google.gson.JsonElement;
import com.google.gson.JsonParseException;

public class BooksDeserializer implements JsonDeserializer<Books> {

  @Override
  public Books deserialize(final JsonElement json, 
        final Type typeOfT, 
        final JsonDeserializationContext context) 
        throws JsonParseException {

    Books books = new Books();
    // Parsing will be done here.
    return books;
  }
}

The above example is not complete and we still need to add the most important thing, which is the parsing. But let's understand this class before we make it more complex by adding more code to it. The interface JsonDeserializer requires a type, which is the type of object that we will be parsing. In this case, we are parsing JSON into the Java object of type Books. The return type of the deserialize() method must be of the same type as the interface parameter, Books.

How does this work?
Gson will parse the JSON object into a Java object of type JsonElement. The JsonElement can be thought of a tree of name/value pairs containing all elements found in the JSON object. Each child within the JsonElement is yet another JsonElement. In other words we have a tree of JsonElements. Through this object we can retrieve each JSON element by its name and set the Java object accordingly. The following example shows how we can retrieve the first book listed in the JSON object and add it to the Java object.


package com.albertattard.examples.gson.part2_1;
import java.lang.reflect.Type;
import com.google.gson.JsonDeserializationContext;
import com.google.gson.JsonDeserializer;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParseException;

public class BooksDeserializer implements JsonDeserializer<Books> {

  @Override
  public Books deserialize(final JsonElement json, 
        final Type typeOfT, 
        final JsonDeserializationContext context) 
        throws JsonParseException {
    Books books = new Books();

    JsonObject jsonObject = json.getAsJsonObject();
    books.addBookTitle(jsonObject.get("1").getAsString());

    return books;
  }
}

In the above example, we are retrieving the JSON element with name "1" using the following code fragment:

jsonObject.get("1")

This returns the JsonElement with the name: "1". In this case it is a simple String. Note that in order to retrieve the actual value we need to invoke another method on the JsonElement instance, which returns the value we need, String in this case.

jsonObject.get("1").getAsString()

The rest of the books titles can be retrieved in the same manner.

Before we can utilise our new deserializer, we must instruct GSON to use our deserializer when parsing objects of type Books, as shown in the next code example.


package com.albertattard.examples.gson.part2_1;
import java.io.InputStreamReader;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class Main {
  public static void main(String[] args) throws Exception {
    // Configure GSON
    GsonBuilder gsonBuilder = new GsonBuilder();
    gsonBuilder.registerTypeAdapter(Books.class,
        new BooksDeserializer());
    Gson gson = gsonBuilder.create();

    // The JSON data
    Reader data = new InputStreamReader(
        Main.class.getResourceAsStream("books.json"), "UTF-8");

    // Parse JSON to Java
    Books books = gson.fromJson(data, Books.class);
    System.out.println(books);
  }
}

In the above example, we are creating an instance of Gson through the GsonBuilder. Using the registerTypeAdapter() method, we are registering our deserializer and instructing GSON to use our deserializer when deserializing objects of type Books. When we request GSON to deserialize an object to the Books class, GSON will use our deserializer . The following list describes what happens when we invoke: gson.fromJson(data, Books.class).
  1. Parse the input as JsonElement. At this stage, the string JSON object is changed into a generic Java object of type JsonElement. This step also ensures that the given JSON data is valid.
  2. Find the deserializer for the given object, in this case the BooksDeserializer instance.
  3. Invokes the method deserialize() and provides the necessary parameters. In his example, our deserialize() will be invoked. Here an object of type Books is created from the given JsonElement object. This is from Java to Java conversion.
  4. Returns the object returned by the deserialize() method to the caller of the fromJson() method. This is like a chain, where GSON receives an object from out deserializer and returns it to its caller.
Running the above example would print the following:

[Effective Java (2nd Edition), JavaTM Puzzlers: Traps, Pitfalls, and Corner Cases, Java Concurrency in Practice, Java: The Good Parts]

This concludes our simple example. This example acts as a primer for other complex parsing. For example, parsing JSON objects that include nested objects, arrays and the like. In the next example we will discuss an enhanced version of the objects discussed here.

Nested Objects

In this example we will describe how to parse nested objects, that is, objects within other objects. Here we will introduce a new entity, the author. A book, together with the title and ISBN can have a list of authors. On the other hand every author can have many books. The JSON object that will be using in this example differs from the previous one to cater for the new entity as shown next:

{
  '1': {
    'title': 'Effective Java (2nd Edition)',
    'isbn': '978-0321356680',
    'authors': ['Joshua Bloch']
  },
  '2': {
    'title': 'JavaTM Puzzlers: Traps, Pitfalls, and Corner Cases',
    'isbn': '978-0321336781',
    'authors': ['Joshua Bloch', 'Neal Gafter']
  },
  '3': {
    'title': 'Java Concurrency in Practice',
    'isbn': '978-0321349606',
    'authors': ['Brian Goetz', 'Tim Peierls', 'Joshua Bloch', 
                'Joseph Bowbeer', 'David Holmes', 'Doug Lea']
  },
  '4': {
    'title': 'Java: The Good Parts',
    'isbn': '978-0596803735',
    'authors': ['Jim Waldo']
  }
}

We still have our four books, only this time we have a more complex and detailed JSON object. Instead of a simple book title, we also have an ISBN and an array of authors.

The new example provides new challenges. One of the authors, Joshua Bloch, has three books. This immediately leads to the following question.

How many instance of this author should we have?
There are two possible answers for this question: just one or three (one for every book). There is no one correct answer, and both cases can be valid. In our examples we are going to have one instance of the author even when he or she has more than one book. We are taking this approach as this approach resembles the reality and helps highlighting the goal of this article (GSON examples). Therefore we will have one author object representing the author Joshua Bloch.

For this example we will be using three domain objects:

  • Author
  • Book
  • Books
All three objects have references to the other objects. For example, the Author class has a list of Books and the Book has a list of Authors. The Books class contains all parsed objects. The Books class also provides the functionality required to maintain one instance for each author as we will see later on in this example.

Author


package com.albertattard.examples.gson.part2_2;
import java.util.HashSet;
import java.util.Set;

public class Author {

  private Set<Book> books = new HashSet<>();
  private String name;

  public Author(final String name) {
    this.name = name;
  }

  public void addBook(Book book) {
    books.add(book);
  }

  public Set<Book> getBooks() {
    return books;
  }

  public String getName() {
    return name;
  }

  @Override
  public String toString() {
    return String.format("%s has %d book(s)", name, books.size());
  }
}

Book


package com.albertattard.examples.gson.part2_2;

import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;

public class Book {

  private Set<Author> authors;
  private String isbn;
  private String title;

  public Book(String title, String isbn, Author... authors) {
    this.title = title;
    this.isbn = isbn;
    this.authors = new HashSet<>(Arrays.asList(authors));
  }

  public Set<Author> getAuthors() {
    return authors;
  }

  @Override
  public String toString() {
    StringBuilder fomrattedString = new StringBuilder();
    fomrattedString.append(title).append(" (").append(isbn)
        .append(")");

    fomrattedString.append(" by: ");
    for (Author author : authors) {
      fomrattedString.append(author.getName()).append(", ");
    }

    // To remove the last comma followed by a space
    return fomrattedString.
             substring(0, fomrattedString.length() - 2);
  }
}

Books


package com.albertattard.examples.gson.part2_2;

import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;

public class Books {

  // A map of authors index by their name.
  private Map<String, Author> authors = new HashMap<>();
  private Set<Book> books = new HashSet<>();

  public void addAuthor(Author author) {
    authors.put(author.getName(), author);
  }

  public void addBook(Book book) {
    books.add(book);
  }

  public Author getAuthorWithName(String name) {
    return authors.get(name);
  }

  @Override
  public String toString() {
    StringBuilder formattedString = new StringBuilder();
    for (Author author : authors.values()) {
      formattedString.append(author).append("\n");
      for (Book book : author.getBooks()) {
        formattedString.append("  ").append(book).append("\n");
      }
      formattedString.append("\n");
    }

    return formattedString.toString();
  }
}





Coming soon.
This article is not complete and more information will follow shortly.

Friday 17 June 2011

Why should we use dependency injection?

Please note that this page has moved to: http://www.javacreed.com/why-should-we-use-dependency-injection/.

In this article we will explore some of the benefits of dependency injection and how this can be used in all types of programming, including small and simple programs. Some of the example shown below make use of Guice, a dependency injection framework by Google. The same concept applies for any other dependency injection framework.

This article does not provide detailed description of Guice but it only focus on the benefits of dependency injection and design methods that improve modularity, extendibility and testing.

What is dependency injection?

Let say we want to make some tea. How would we do it and what do we need? We need to boil some water, a clean mug, tea bags, sugar and milk (at least that's what I put into mine). In order to make tea we need to provide all these ingredients and we need to manage all these ourselves. We have to fill the kettle with water and heat it up, get the milk from the refrigerator and get the rest.

Now assume that we can make tea, by simply asking someone else to do it for us. Someone that knows how to do the tea just the way we want it. Would that be better than making the tea ourselves? If yes, then welcome to dependency injection.

Dependency injection is a framework that takes care of creating objects for us without we having to worry about providing the right ingredients so to say.

A Simple Example

Let say we have a class, Person, and this class needs to send a message. The Person class requires the aid of some other class, Email, in order to send a message. Following is a simple way of doing this.

public class Email {
  public void sendEmail(String subject, String message){
  }
}

public class Person {
  private Email email = new Email();

  public void greetFriend(){
    email.sendEmail(parameters...);
  }
}

Some code is omitted from the above classes for brevity

We all agree that this is a very simple and straight forward example that involves two simple Java classes. Nevertheless, the above has some limitations as listed below.

  • The Persons class is dependent (has a strong/tight dependency) on the Email class. There is a hard connection between these two classes. Let say we have a new better version of email class, FastEmail, in order for us to use it, we need to go in each and every class that depends on the Email class, such as the Person class, replace it with the new version.
  • Let say we parametrise the Email's constructor. Again we have to go in each and every class that is initialising the Email class, such as the Person class, and change it.
  • A design decision is taken to make the Email class singleton. Similar to above we need to modify all instances where it is used.
  • In order to improve the notifications/messages system, we decide to add different message delivery systems such as SMS or tweets. The Person class and other like it, need to all be modified in order for it to use the new classes.
  • Another developer needs to use the Person class, but would like to use a different notification/message system. This cannot be achieved with the current version of the Person class as it is hardwired to the Email class. What generally happens is that the other developer duplicates the Person class and modifies it as he/she needs. The projects ends up with two versions of the Person class.
  • In the above points we mentioned many scenarios where code has to be changed. All changes made, need to and should be tested. How can we test the Person class without including the message delivery class such as the Email? Testing, in many cases, is left as an afterthought. The way we have the Person class constructed makes it hard to test it without involving the Email class. Furthermore, how would we automate such test? How can we use JUnit or the like to automate out tests?
  • Moving forward in the project, the Person class starts to depend on another class that allow this object to write a letter using the Pen class for example. The Person class can use other ways to write a letter, such as Pencil class or Typewriter class, but this approach does not allow that.

These limitations can be improved by changing the way we think and restructure our code in a modular way. This is independent from dependency injection as we will see in the following section.

Change the way we think

The Email class provides a service, that is, sending of messages over the Internet using the mail protocol. Instead of having the Person class initialising an instance of the Email class, we first create an interface, MessageService, and make the Person class using this interface instead. This removed the dependency that the Person class has on the Email and replaces it with an abstract message delivery interface.

The following three steps: define, implement and use, show how we can develop modular and extendable code. This approach also improves testing as we will see at the end of this article.

  1. Define Interfaces

    Many developers do not use interfaces as they see them as additional non-required code. This may be true (I said maybe as the System class makes use of interfaces) for the famous hello world program, definitely not true for the rest. Like with everything else, we have to see things in context and there will be cases when we can do without interfaces. Nevertheless, developing code using interfaces produce far more modular and extendable code as illustrated in the following examples. The example discussed in the previous section was quite simple, but nevertheless it included several pitfalls which can be easily avoided. Changing code at a later stage involves more work than having it right in the first place.

    We start by defining the MessageService interface that includes one method, sendMessage(String subject, String message). For simplicity we assume that no exceptions are thrown.

    public interface MessageService {
      void sendMessage(String subject, String message);
    }
    
  2. Implement Interfaces

    In the list of limitations we mentioned four possible methods of sending a message: email, fast email, SMS and tweet. Let's create four classes that handle each message delivery method and have all these classes implement the interface created above.

    public class EmailService implements MessageService {
      @Override
      public void sendMessage(String subject, String message){
        System.out.printf("Email: %s, %s%n ", subject, message);
      }
    }
    
    public class FastEmailService implements MessageService {
      @Override
      public void sendMessage(String subject, String message){
        System.out.printf("Fast Email: %s, %s%n ", subject, message);
      }
    }
    
    public class SMSService implements MessageService {
      @Override
      public void sendMessage(String subject, String message){
        System.out.printf("SMS: %s, %s%n ", subject, message);
      }
    }
    
    public class TweetService implements MessageService {
      @Override
      public void sendMessage(String subject, String message){
        System.out.printf("Tweet: %s, %s%n", subject, message);
      }
    }
    
  3. Use Interfaces

    Finally, instead of using classes, we use interfaces. In the Person class, we replace the Email field with the MessageService service interface as shown in red below.

    public class Person {
      private MessageService messageService;
    
      public Person(MessageService messageService){
        this.messageService = messageService;
      }
    
      public void greetFriend(){
        messageService.sendMessage(parameters...);
      }
    }
    

    Note that the Person class is not initialising the message service but it is expecting it as a parameter of its constructor. This is a key element in the design. It improves modularity, extendibility and testing. The Person class is not dependent on any implementation, but on a service defined by an interface. This means that we can use the Person class without having to worry about the underlying implementation. Furthermore, different Person instance can be instantiated using different message services.

One can argue that the new version of Person class became more complex to instantiate as it requires parameters. This is a fair statement and here is when dependency injection comes into play.

Using Dependency Injection

As mentioned in the introduction, dependency injection can help us initialising objects and provide these objects all the necessary resources (ingredients). For example, the Person class requires an instance of MessageService. The dependency injection framework will provide that for us. So to create an instance of Person, all we need to do is call something like: dependecyFramework.getInstance(Person.class). Magically, (not really), the dependency injection framework will create an instance of the Person class and provide an instance of the a MessageService to the Person object.

The next natural question will be, how does the dependency injection framework knows how to initialise the MessageService? We need to tell the dependency injection framework how to create an instance of MessageService. With Google Guice we do that by creating a module (extends AbstractModule ) as illustrated below:

public class ProjectModule extends AbstractModule {

  @Override
  protected void configure() {
    bind(MessageService.class).to(EmailService.class);
  }
}

Here we are telling the dependency injection how to create an instance of the MessageService class. We also need to add an annotation to the Person class in order to allow the dependency injection framework to inject the necessary parameters.

public class Person {
  private MessageService messageService;

  @Inject
  public Person(MessageService messageService){
    this.messageService = messageService;
  }

  public void greetFriend(){
    messageService.sendMessage(parameters...);
  }
}

With everything set, we create an instance of the Person class using the dependency injection framework

Injector injector = Guice.createInjector(new ProjectModule());
  Person person = injector.getInstance(Person.class);
  person.greetFriend();

We replaced a couple of lines of code with many others. What's the buzz about this? In the next section we will see some of the benefits of dependency injection and how this can be used to simplify our coding life

Benefits of Dependency Injection

In this section we will see some key benefits of dependency injection

  • Changing the message service

    Let's change the delivery method from email to SMS. How would we do that?

    We only need to change the ProjectModule class to map the MessageService class to the SmsService class as shown in red below.

    public class ProjectModule extends AbstractModule {
    
      @Override
      protected void configure() {
        bind(MessageService.class).to(SmsService.class);
      }
    }
    

    This one change will affect all classes initialised with the dependency injection framework without having to change any of these classes. This leads us to another advantage, testing.

  • Changing the message service

    We can create a MockService class which can be using in JUnit test as shown next.

    public class MockService implements MessageService {
    
      public String subject;
      public String message;
    
      @Override
      public void sendMessage(String subject, String message) {
        this.subject = subject;
        this.message = message;
      }
    
    }
    

    The above mock message service simply stores the parameters into two public fields. These fields can be used to retrieve the values of the parameters and used for testing ass illustrated next.

    public class TestPerson {
    
      private Injector injector;
    
      @Before
      public void init() {
        injector = Guice.createInjector(new AbstractModule() {
          @Override
          protected void configure() {
            bind(MockMessageService.class).in(Singleton.class);
            bind(MessageService.class).to(MockService.class);
          }
        });
      }
    
      @Test
      public void testGreetFriend() {
        Person person = injector.getInstance(Person.class);
        person.greetFriend();
    
        MockService mockService = injector
            .getInstance(MockService.class);
        assertEquals("Greet", mockService.subject);
        assertEquals("Hello my friend", mockService.message);
      }
    }
    

    This may require some explanation. So here we go. We created an injection (Guice dependency injection) just for this testing and provided a custom module (as an abstract inner anonymous class). The custom module wires the MessageService with the MockService instead. Also, we set the MockService as singleton, that is, whenever we request an instance of this class from the injection we always get the same object (singleton). After greetFriend() is invoked, we test using JUnit to make sure that the correct parameters are being passed to the message service instance.

    This design setup allows us to test the Person class independent from the other classes that it depends on in an automated manner.

  • Changing the signature of the Person constructor

    As we mentioned in the limitations, the Person class may evolve and include more functionality. Changing the signature of the Person constructor will not affect us as long as the injector knows how to provide the required parameters.

    public class Person {
      @Inject
      public Person(MessageService messageService, 
                    WritingService writingService){
      }
    }
    

    The Person class will still be initialised in the same way as it is now. Thus changing the Person constructor signature will not affect the other classes that make us of it.

    Person person = injector.getInstance(Person.class);
    

    The same applies for anything that is initialised and handled through the injector.

  • Passing the Injector as parameter

    In a project we can have one instance shared throughout the project. This can be achieved by passing the Injector as a parameter to other objects that needs it. We setup the injector at the beginning (in a main method for example), and then have it set as a constructor parameter in all the classes that require an instance of the injector. Like that one injector will server all classes in the project.

Conclusion

This ended up to be quite a long article. Dependency injection is quite simple to use and it has quite a "shallow" learning curve. This article does not explain how to use the actual dependency injection framework (such as Guice). Articles about that are easily found. This article described key benefits of using a dependency injection framework even in small projects.

Saturday 11 June 2011

OutOfMemoryError when reading large volumes of records from MySQL

When loading a large number of records from MySQL, an out of memory error (exception) may be thrown by the MyQSL connector. The connector reads all the data in memory (buffering) before it returns the result set. This may not be the case for other JDBC providers.

The follow code fragment will fail on the third line (shown in red) when invoking the executeQuery() method if the memory required to load the whole result is larger than the allocated heap size.

Statement statement = connection.createStatement();
ResultSet resultSet = 
    statement.executeQuery("SELECT * FROM `large_table`");
while(resultSet.next()){
}

One possible solution is to increase the heap size but this may not be required, especially if you are accessing small parts from the result set at one time. Increasing the heap size will only allow the program to consumes more resources that it actually requires.

The MYSQL statement interface (com.mysql.jdbc.Statement) provides a method called enableStreamingResults() which enables streaming over buffering, (as shown in red in the following code fragment).

Statement statement = connection.createStatement();
// This prevents the MYSQL connector from loading all the 
// results into memory
((com.mysql.jdbc.Statement) statement).enableStreamingResults();
ResultSet resultSet = 
    statement.executeQuery("SELECT * FROM `large_table`");
while(resultSet.next()){
}

This allows the code to read from a large table without consuming a large amount of memory.

Friday 9 July 2010

In line images

Many web sites include small images and icons in tool bars and menus. These images are downloaded one by one by the browser while the page is downloaded. In many cases, the establishing of connection is more expensive in terms of time and traffic than the actual image. By converting these images to base64 encoding text, the browser can download the page content and the images at one go. Here’s is the code of how to convert an image into a base64 string.

public static String convertToInLineImage(
    byte[] image, String type) {
// Convert a byte array to base64 string
char[] chars = new sun.misc.BASE64Encoder().
                    encode(image).toCharArray();
StringBuilder builder = new StringBuilder();
for (char c : chars) {
 switch (c) {
   case '\n':
   case '\r':
   continue;
 default:
   builder.append(c);
 }
}

return "data:" + type + ";base64," + builder.toString();
}

The above method simple converts an image from bytes into string. The string returned by this method should be placed within the image HTML style.

style="width:50px;
      height:50px;
      background:url('the-base64-string-here')
          no-repeat scroll 0px 0px transparent;"