js.converter

Interface Converter

All Known Implementing Classes:

BooleansConverter, CharactersConverter, ClassConverter, ConverterRegistry, DatesConverter, EnumsConverter, FileConverter, LocaleConverter, NumbersConverter, TimeZoneConverter, UrlConverter

public interface Converter

Convert value type instances to and from strings representation. This interface is the core abstraction of string converter package supplying methods for value type conversion. A value type is a class that wrap a single value susceptible to be represented as a single string - a sort of data atom, e.g. java.io.File or java.net.URL.

In order to be able to convert a given value type implementation must have a converter defined, see ConverterRegistry . One can check for implementation support using ConverterRegistry.hasType(Type) predicate.

As stated, this interface supplies two complementary conversion methods for string (de)serialization: asString(Object) and asObject(String, Class). The contract is that applying these methods in sequence we need to obtain original object, that is, sequence is idempotent:

 string.equals(converter.asString(converter.asObject(string, ValueType.class)))
 

Using converter is straightforward: get instance from converter registry and call conversion methods. Converter is reusable and thread safe.

      ConverterRegistry registry = ConverterRegistry.getInstance();
      Converter converter = registry.getConverterInstance();
      String string = converter.asString(object);
      ...
      Object object = converter.asObject(string, Object.class);
 

Custom Converter

Converter registry comes with stock converters for Java common value types but user defined converters are supported. Implement this interface and register with ConverterRegistry.registerConverter(Class, Class). It is user responsibility to ensure user defined converter is able to actually handle value type(s) for which is registered. Usually a converter is registered for a single value type but there is no formal restriction on that.

Custom converters could be registered also from third party libraries via ConverterProvider service.

Thread Safe

Converter implementation should be reusable and thread safe. For this reason it should not hold state, maybe besides thread local. Since converter registry is global per JVM also converter instances are.

Version:

final

Author:

Iulian Rotaru

See Also:

package description

Method Summary

Modifier and Type	Method and Description
<T> T	asObject(String string, Class<T> valueType) Create a new instance of given value type and initialize it from string.
String	asString(Object object) Create a string representation for given value type instance.

Method Detail

asObject

<T> T asObject(String string,
               Class<T> valueType)
        throws IllegalArgumentException,
               ConverterException

Create a new instance of given value type and initialize it from string. Instance string representation should be compatible with expected value type. It is user code responsibility to ensure that. Returns null if string argument is null; if string is empty implementation should return some specific empty instance, like false or 0 but is not recommended to return null.

 String string = "Iulian Rotaru<[email protected]>";
 Mailbox mailbox = converter.asObject(string, Mailbox.class);
 

Requested value type should have converter registered via ConverterRegistry.registerConverter(Class, Class).

Type Parameters:

T - instance type.

Parameters:

string - instance string representation, possible null or empty,

valueType - expected value type, null not accepted.

Returns:

newly created instance of requested type, null if string argument is null.

Throws:

IllegalArgumentException - if valueType is null.

ConverterException - if value type has no converter registered or string parsing fails.

asString

String asString(Object object)
         throws ConverterException

Create a string representation for given value type instance. Returns serialized instance or null if object argument is null.

 Mailbox mailbox = new Mailbox();
 String string = converter.asString(mailbox);
 

The type of requested value object should have converter registered via ConverterRegistry.registerConverter(Class, Class).

Parameters:

object - value type instance, possible null.

Returns:

string representation of given value type instance or null.

Throws:

ConverterException - if value object has not converter registered or if anything goes wrong on serialization process.