Basic usage

Using Joda-Convert is easy at the simplest level. The main access is via the class StringConvert.

The easiest way to use the conversion is via the global constant:

// conversion to a String
TimeZone zone = ...
String str = StringConvert.INSTANCE.convertToString(zone);

// conversion from a String
TimeZone zone = StringConvert.INSTANCE.convertFromString(TimeZone.class, str);

In both cases, if the input is null then the output will also be null.

The global constant is quick and easy to use, but is shared between all users in the ClassLoader. It also cannot be extended.

The alternative approach is to instantiate your own instance of StringConvert. This would normally be stored in your own static variable, or made available as needed by dependency injection. This may be updated by registering your own converters.

Converters

Each instance of StringConvert, including the global singleton, includes a standard set of JDK-based converters. These cover all the standard JDK types for which conversion to and from a string is sensible. The set also includes JSR-310 types, but these are optional and loaded by reflection. The system will run without any dependency.

Each StringConvert instance, other than the global singleton, may have additional converters registered manually. Each converter implements the StringConverter interface, which is self explanatory.

Converters may also be manually added by method name. This is equivalent to using annotations, but suitable when you don't own the code to add them. See StringConvert.registerMethods and StringConvert.registerMethodConstructor.

A converter can only be registered if one is not already registered for that type.

Annotation based conversion

If there is no registered converter for a type, then a search by annotation is performed. This will search for the ToString and FromString annotation on the type. These annotations will indicate which method should be called to perform the conversion.

public class Distance {

  @FromString
  public static Distance parse(String str) { ... }

  @ToString
  public String getStandardOutput() { ... }

}

To be valid, the class must contain one ToString annotation and one FromString annotation. The ToString annotation must be an instance method taking no parameters and returning a String. The FromString annotation must be either a static method or a constructor taking a String parameter and returning the correct type. If the annotations are not found on the target class, then superclasses are searched.

The concept is that other open source libraries, as well as your application code, will implement these two annotations. For open source projects, a key point is that adding the annotations is a compile-time only event. The Joda-Convert jar file is not needed by your users unless they want to. If they don't want to use Joda-Convert then the annotations are effectively ignored.

Joda-Time v2.0 and Joda-Money will both contain the annotations. However, in both cases, the dependency is compile-time only, and not at runtime.