Convert

Convert is a framework for decoupled conversion of Java objects from one type to another.

LGPL

1.1.1

Java 6

• Jar files
• Sources, includes Javadoc and jar files.
• Javadoc
• Discussion forum
• Issue tracking
• Roadmap

It is very often required in a Java program to convert one object type to another, e.g. String “33” to Integer 33, or String “java.util.Map” to class java.util.Map, or String “myRequestQueue” to JMS Queue. In Java there is no standard way to perform such conversions. To convert String to Integer we need to use Integer.parseInt(), to convert String to Class we need to use Class.forName() or ClassLoader.loadClass(), to convert String to Queue we need either naming context or JMS Session and invoke respective methods of these objects.

The Convert framework provides an extensible unified approach for type conversion in Java. Conversions can be context-free (e.g. “33”→33) or context-dependent (e.g. “myRequestQueue” → JMS Queue).

The picture above shows framework participants and dependencies:

• Source object/class is not dependent on any of framework components.
• Target object/class is not dependent on any of framework components either.
• Converting framework defines interfaces to be implemented by converters and classes used by clients (ConvertingService). Is not dependent on concrete converters as they are loaded by Java 6 ServiceLoader.
• Concrete converter depends on source class, target class and conversion framework.
• Client code is not dependent on concrete converter and source object type.

Object source = "333";
Integer target = ConvertingService.convert(source, Integer.class);

1. If source is null, then converting service returns null.
2. If source is instance of target class, it is returned as is.
3. If source implements Adaptable, then its getAdapter(targetClass) is invoked. If the method returned value is not null, then it is returned from the convert() method.
4. The framework searches for appropriate converter. If converter is found, then it is used to convert source to target type. A converter is searched in
   1. Services of type AtomicConverterBundle.
   2. Services of type AtomicConverter.
   3. Services of type Converter
   4. ReflectionConverter.discoverConstructorConverter() is used to attempt to construct target type from source type.
5. If converter is not found, then, as the last resort, the framework attempts to convert source to Adaptable. If conversion is successful, that adaptable's getAdapter(targetClass) is invoked to produce return value.

The framework defines a number of out-of-the-box converters in FoundationAtomicConverterBundle class. This class defines converters for primitive types and converters

• File → Reader converter
• File → InputStream
• InputStream → Reader
• String → Class

See source of FoundationAtomicConverterBundle.getConverters() method for more details.

• Decide on service type to implement:
  • AtomicConverter
  • AtomicConverterBundle
  • Converter
• Implement the service
• Register the service as described in ServiceLoader documentation.

• Configurator leverages Convert framework to convert string values from the configuration file (XML) to argument types of setters.
• Render uses Convert framework to “convert” objects being rendered to flavors of HtmlRenderer.