org.scijava.convert

Interface Converter<I,O>

All Superinterfaces:

Comparable<Prioritized>, Contextual, HandlerPlugin<ConversionRequest>, HasPluginInfo, Prioritized, RichPlugin, SciJavaPlugin, SingletonPlugin, Typed<ConversionRequest>, TypedPlugin<ConversionRequest>

All Known Implementing Classes:

AbstractConverter, ArrayConverters.BoolArrayUnwrapper, ArrayConverters.BoolArrayWrapper, ArrayConverters.ByteArrayUnwrapper, ArrayConverters.ByteArrayWrapper, ArrayConverters.CharArrayUnwrapper, ArrayConverters.CharArrayWrapper, ArrayConverters.DoubleArrayUnwrapper, ArrayConverters.DoubleArrayWrapper, ArrayConverters.FloatArrayUnwrapper, ArrayConverters.FloatArrayWrapper, ArrayConverters.IntArrayUnwrapper, ArrayConverters.IntArrayWrapper, ArrayConverters.LongArrayUnwrapper, ArrayConverters.LongArrayWrapper, ArrayConverters.ShortArrayUnwrapper, ArrayConverters.ShortArrayWrapper, DefaultConverter, NullConverter, PrimitiveArrayUnwrapper, PrimitiveArrayWrapper

public interface Converter<I,O>
extends HandlerPlugin<ConversionRequest>

Extensible conversion Plugin for converting between classes and types.

Author:

Mark Hiner

See Also:

ConversionRequest

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canConvert(Class<?> src, Class<?> dest) Deprecated. Use canConvert(Object, Class)
boolean	canConvert(Class<?> src, Type dest) Deprecated. Use canConvert(Object, Type)
boolean	canConvert(ConversionRequest request) Checks whether a given can be processed, by converting the desired ConversionRequest.sourceClass() to its ConversionRequest.destClass() or ConversionRequest.destType().
boolean	canConvert(Object src, Class<?> dest) Checks whether the given object's type can be converted to the specified type.
boolean	canConvert(Object src, Type dest) Checks whether the given object's type can be converted to the specified type.
Object	convert(ConversionRequest request) Converts the given ConversionRequest.sourceObject() to the specified ConversionRequest.destClass() or ConversionRequest.destType().
<T> T	convert(Object src, Class<T> dest) Converts the given object to an object of the specified type.
Object	convert(Object src, Type dest) As convert(Object, Class) but capable of creating and populating multi-element objects (Collections and array types).
Class<I>	getInputType()
Class<O>	getOutputType()
void	populateInputCandidates(Collection<Object> objects) Populates the given collection with objects which are known to exist, and which are usable as inputs for this converter.

Methods inherited from interface org.scijava.Contextual

context, getContext, setContext

Methods inherited from interface org.scijava.Prioritized

getPriority, setPriority

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface org.scijava.plugin.HasPluginInfo

getInfo, setInfo

Methods inherited from interface org.scijava.Typed

getType, supports

Method Detail

canConvert

boolean canConvert(ConversionRequest request)

Checks whether a given can be processed, by converting the desired ConversionRequest.sourceClass() to its ConversionRequest.destClass() or ConversionRequest.destType().

See Also:

convert(ConversionRequest)

canConvert

boolean canConvert(Object src,
                 Type dest)

Checks whether the given object's type can be converted to the specified type.

Note that this does not necessarily entail that convert(Object, Type) on that specific object will succeed. For example: canConvert("5.1", int.class) will return true because a String can in general be converted to an int, but calling convert("5.1", int.class) will throw a NumberFormatException when the conversion is actually attempted via the Integer.Integer(String) constructor.

See Also:

convert(Object, Type)

canConvert

boolean canConvert(Object src,
                 Class<?> dest)

Checks whether the given object's type can be converted to the specified type.

Note that this does not necessarily entail that convert(Object, Class) on that specific object will succeed. For example: canConvert("5.1", int.class) will return true because a String can in general be converted to an int, but calling convert("5.1", int.class) will throw a NumberFormatException when the conversion is actually attempted via the Integer.Integer(String) constructor.

See Also:

convert(Object, Class)

convert

Object convert(Object src,
             Type dest)

As convert(Object, Class) but capable of creating and populating multi-element objects (Collections and array types). If a single element type is provided, it will be converted the same as convert(Object, Class). If a multi-element type is detected, then the value parameter will be interpreted as potential collection of values. An appropriate container will be created, and the full set of values will be type converted and added.

NB: This method should be capable of creating any array type, but if a Collection interface or abstract class is provided we can only make a best guess as to what container type to instantiate. Defaults are provided for Set and List subclasses.

Parameters:

src - The object to convert.

dest - Type to which the object should be converted.

convert

<T> T convert(Object src,
            Class<T> dest)

Converts the given object to an object of the specified type. The object is casted directly if possible, or else a new object is created using the destination type's public constructor that takes the original object as input (except when converting to String, which uses the Object.toString() method instead). In the case of primitive types, returns an object of the corresponding wrapped type. If the destination type does not have an appropriate constructor, returns null.

Type Parameters:

T - Type to which the object should be converted.

Parameters:

src - The object to convert.

dest - Type to which the object should be converted.

convert

Object convert(ConversionRequest request)

Converts the given ConversionRequest.sourceObject() to the specified ConversionRequest.destClass() or ConversionRequest.destType().

Parameters:

request - ConversionRequest to process.

Returns:

The conversion output

See Also:

convert(Object, Class), convert(Object, Type)

populateInputCandidates

void populateInputCandidates(Collection<Object> objects)

Populates the given collection with objects which are known to exist, and which are usable as inputs for this converter.

That is: each such object added to the collection would return true if queried with converter.canConvert(object), and hence would produce an output of type getOutputType() if passed to converter.convert(object).

The means by which "known objects" are determined is implementation dependent, although the most typical use case is to query the ObjectService for known objects of type getInputType(), and return those. But other behaviors are possible, depending on the converter implementation.

Parameters:

objects - an initialized collection into which appropriate objects will be inserted.

getOutputType

Class<O> getOutputType()

Returns:

The base Class this Converter produces as output.

getInputType

Class<I> getInputType()

Returns:

The base Class this Converter accepts as input.

canConvert

@Deprecated
boolean canConvert(Class<?> src,
                            Type dest)

Deprecated. Use canConvert(Object, Type)

Checks whether objects of the given class can be converted to the specified type.

See Also:

convert(Object, Type)

canConvert

@Deprecated
boolean canConvert(Class<?> src,
                            Class<?> dest)

Deprecated. Use canConvert(Object, Class)

Checks whether objects of the given class can be converted to the specified type.

See Also:

convert(Object, Class)