Information about your use of this website is collected using cookies.
The collected information consists of the following:
1. The IP address from which you access the website;
2. The type of browser and operating system you use to access our site;
3. The date and time you access our site;
4. The pages you visit; and
5. The addresses of pages from where you followed a link to our site.
Part of this information is gathered using a tracking cookie set by the Google Analytics service and handled by Google as described in their privacy policy. See your browser documentation for instructions on how to disable the cookie if you prefer not to share this data with Google.
We use the gathered information to help us make our site more useful to visitors and to better understand how and when our site is used. We do not track or collect personally identifiable information or associate gathered data with any personally identifying information from other sources.
By using this website, you consent to the collection of this data in the manner and for the purpose described above.
Joda-Convert provides a small set of classes to aid conversion between Objects and Strings. It is not intended to tackle the wider problem of Object to Object transformation.
// conversion to String String str = StringConvert.INSTANCE.convertToString(foo); // conversion from String Foo bar = StringConvert.INSTANCE.convertFromString(Foo.class, str);
Joda-Convert supports two mechanisms of extending the list of supported conversions. The first is to write your own converter implementing an interface. The second is to use annotations.
The ability of Joda-Convert to use annotations to define the conversion methods is a key difference from other projects.
For example, most value classes, like Currency or TimeZone, already have methods
to convert to and from a standard format String.
Consider a Distance class:
public class Distance {
@FromString
public static Distance parse(String str) { ... }
@ToString
public String getStandardOutput() { ... }
}
As shown, the two methods may have any name. They must simply fulfil the required method signatures for conversion.
The FromString annotation may also be applied to a constructor.
When Joda-Convert is asked to convert between an object and a String, if there is no registered converter then the annotations are checked. If they are found, then the methods are called by reflection.
Joda-Convert is licensed under the business-friendly Apache 2.0 licence.
Various documentation is available:
Release 1.5 is the current latest release. This release is considered stable and worthy of the 1.x tag. It depends on JDK 1.6 or later.
Available in the Maven Central repository.
Support on bugs, library usage or enhancement requests is available on a best efforts basis.
To suggest enhancements or contribute, please fork the source code on GitHub. Alternatively, use GitHub issues.
Joda-Convert is intended for one simple task - Converting objects to and from strings. This is a common problem, particularly when communicating over textual protocols like XML or JSON.
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.
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.
Arrays of byte are handled as a standard JDK type using Base64.
Arrays of char are handled by a standard JDK type by conversion to a string.
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.
In addition to manual registration of individual converters, each instance of StringConvert
has a list of factories to use. The StringConverterFactory interface defines the factory.
This allows either bulk registration or dynamic lookup of converters.
A factory is provided to allow numeric arrays to be converted to/from a comma separated list. A separate factory handles numeric object arrays. Another factory is provided to allow boolean arrays to be converted to/from a string such as 'TTFFT'. Again, a separate factory handles boolean object arrays. Primitive byte and char arrays are handled by default, but the primitive object arrays are handled via their own factories.
These extra factories must be manually registered, unless the StringConvert.create()
static method is used, which defines an "extended" converter with the factories included.
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, followed by immediate parent interfaces.
Sometimes, you want to provide to/from string conversions for interfaces. In JDK 8 this can be done using static methods on interfaces. However in earlier versions, a separate "factory" class is necessary. This can also be annotated:
@FromStringFactory(factory = DistanceFactory.class)
public interface Distance {
@ToString
String standardFormat();
}
public class Metres implements Distance {
@Override
public String standardFormat() { ... }
}
public class DistanceFactory {
@FromString
public static Distance parseDistance(String str) { ... }
}
The FromStringFactory annotation points at the factory class that will provide the factory method.
Although intended for use with interfaces, it can also be used on the target class or any superclass.
Note that only the immediate parent interfaces of a class will be 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 use conversion. 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. In both cases, the dependency is not a runtime for users of the projects.