Introduction

The Commons module provides all the basic functionality that is currently lacking in GWT, but greatly needed in order to develop robust GWT applications. For now, it contains two main pieces of functionality:

• Utilities, including String and Array related utilities.
• Conversion, a converter infrastructure inspired by the Java PropertyEditors, but better suited for GWT applications.

Details

The functionalities offered by the Commons module is used heavily by all other modules of the GWToolbox project.

Utilities

For now, the GWToolbox Commons module contains three utility classes located in the org.gwtoolbox.commons.util.client package:

• ArrayUtils, providing utility methods for working with arrays
• Proxy, represents a proxy to another object
• StringUtils, provides utility methods for working with strings

Conversion

The converter infrastructure provided by the Commons module of the GWToolbox project is centered around one basic interface TextConverter, located in the org.gwtoolbox.commons.conversion.client package. The TextConverter interface defines the basic infrastructure for converting an Object to a String and vice versa. The TextConverter interface is depicted below. As you can see, it defines three methods, two for converting an object from and to a string and one to let the TextConverter implementation indicate which types it can convert.

package org.gwtoolbox.commons.conversion.client;

public interface TextConverter {

    Class[] getSupportedTypes();

    String toText(Object value);

    Object toValue(String text);

}

GWToolbox comes with the following implementations of the TextConverter interface out of the box, located in the org.gwtoolbox.commons.conversion.client.converter package:

• BooleanTextConverter
• ByteTextConverter
• CharacterTextConverter
• DateTimeTextConverter
• DoubleTextConverter
• FloatTextConverter
• IntegerTextConverter
• LongTextConverter
• ShortTextConverter
• StringTextConverter

All of these converter implementations can be used to convert their specific type(s). Note that the DateTimeTextConverter can be configured with the pattern to use to perform the conversion (default is 'dd-MM-yyyy HH:mm:ss').

Using the conversion infrastructure for converting an object from and to a string is very much straightforward. You just need to get a reference to the system-wide GlobalTextConverter and use that to convert back and forth between objects and their string representation.

GlobalTextConverter converter = TextConverterManager.getGlobalConverter();
converter.toText(Date.class, new Date());

If you want to register your own converter implementations, you can do this by calling the registerTextConverter(TextConverter) method on the TextConverterManager.

Note: the ordering in which text converter implementations are registered is important as the registration might overwrite previously registered or default text converters for certain classes.

Imporant interfaces

The core interfaces the developer needs to know about are:

TextConverter - The most basic construct that defines the strategy of how to convert an object of specific type to its text representation and back. Each converter can support multiple types (as returned by the getSupportedTypes() method.

public interface TextConverter {

    Class[] getSupportedTypes();

    String toText(Object value);

    Object toValue(String text);

}

TextConverterRegistry - Represents a registry where text converters are registered and can be retrieved on demand.

public interface TextConverterRegistry {

    TextConverter getTextConverter(Class clazz);

    void register(TextConverter converter);

}

GlobalTextConverter - A more generic text converter interface which is not bound to specific types (like the TextConverter is) and also serves as a text converter registry.

public interface GlobalTextConverter extends TextConverterRegistry {

    String toText(Class type, Object value);

    Object toValue(Class type, String text);

}

TextConverterManager - As the entry point to the conversion infrastructure this interface provides a simple mechanism to register new text converters and also provides access to a single global text converter implementation which is based on all registered text converters.

public class TextConverterManager {

    ...

    public static void registerTextConverter(TextConverter converter) { ... }

    public static GlobalTextConverter getGlobalConverter() { ... }

}

The TextConverterManager is initialized with the DefaultGlobalTextConverter which apart of being a simple implementation of the GlobalTextConverter interface, also comes with default text converters for common types already registered. The following types are supported:

• Boolean/boolean (BooleanTextConverter)
• Byte/byte (ByteTextConverter)
• Character/char (CharacterTextConverter)
• Short/short (ShortTextConverter)
• Integer/int (IntegerTextConverter)
• Long/long (LongTextConverter)
• Float/float (FloatTextConverter)
• Double/double (DoubleTextConverter)
• String (StringTextConverter)
• Date (DateTimeTextConverter) - by default uses 'dd-MM-yyyy HH:mm:ss' as the date pattern

It is possible to override any of the pre-registered converters just by registering the new converters with the TextConverterManager (A common action would probably be to override the Date text converter with custom date/time pattern).