About Bindings

Jadira Bindings is a framework for data binding artibrary Java objects to and from one object representation to another. Other libraries provide similar functionality, including: Joda Convert, Apache Commons Convert. Jadira Bindings differs from these frameworks in its functionality and intent.

Unlike other frameworks which typically only register bindings by type, Jadira Bindings supports qualifying bindings according to context. Why would you want to this? Consider the example of a date. The binding selected for database representation would need to be different from that selected for XML Schema. Jadira Bindings supports such distinctions by the use of qualifiers. The qualifier mechanism will be familiar to anyone that has used CDI.

Features and Capabilities

Key features of Jadira Bindings include:

• Pluggable support for a variety of binding specification mechanisms (Bindings can, for example, interpret Joda Convert annotations out of the box);
• Support for scoping particular To and From bindings with qualifiers, so that an appropriate method can be selected by context;
• Support for XML and Annotation configuration styles - XML binding utilises a bootstrap mechanism similar to CDI or the Spring Framework
• Bindings declared with annotations on the target class can be discovered automatically (with the exception of when used with Spring's converter framework).
• Support for programmatic configuration
• Integrations with Spring Framework and CDI

Setting up an annotation driven binding

Just mark up an object method as @To and a constructor or static method with an input object parameter as @From.

Invoking the Binding

Invoke new BasicBinder().convertTo(inputClass, outputClass, bar)

Using qualifiers

A To or From method can be assigned a scope by attaching a qualifier. A qualifier is a special annotation that can be defined and attached to the method. Refer to the Javadoc for org.jadira.bindings.core.annotation.BindingScope. When you don't supply an explicit qualifier, a method is assumed to belong to the qualifier scope org.jadira.bindings.core.annotation.DefaultBinding. The Binder interface provides versions of the convertTo method that accept a qualifier as an additional parameter.

Registering the binding

It is good practice to register the new binding rather than rely on the automatic discovery mechanism. This can be achieved by defining a META-INF/bindings.xml with a binding entry definining the class attribute - refer to jadira-bindings.xsd.

Joda Convert

Bindings can interpret Joda Convert annotations

XML Configuration

You can use bindings.xml to declaratively reference converter methods which don't have to be defined on the class they convert for - refer to the XSD

Java Interface

You can implement Binding, ToMarshaller, FromUnmarshaller, and/or Converter then use the XML configuration to register the implementation. When you implement an interface in this manner you can apply a qualifier annotation on the implementing should you wish

Service Loader

Bindings supports the Service Loader mechanism in JDK 1.6 for the service named org.jadira.bindings.core.Binder

CDI

In CDI environments bindings supports an automatic bootstrap mechanism that scans any beans loaded for bindings or annotated methods

Spring

The class BindingConverter is provided for registration available bindings with Spring Framework as converters

BindingProvider

To add new mechanisms for defining bindings, create and register a Converter Provider. To do so, implement the ConverterProvider interface, and register the provider with the bindings.xml file.