agi.foundation.infrastructure

(agi.foundation.core-2024r2.jar)

Class FormatConverter<T,TFormatType extends IIndexedFormat>

java.lang.Object

agi.foundation.infrastructure.FormatConverter<T,TFormatType>

Type Parameters:

T - The type of object that this class converts the format of.

TFormatType - The class of the format object itself. This can be a base class.

public class FormatConverter<T,TFormatType extends IIndexedFormat>
extends Object

Converts between different formats of a given type, where a format is specified as an indexed format object. This class can chain conversions in cases where a direct conversion is not possible.

Constructor Summary

Constructors

Constructor and Description
FormatConverter() Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
T	convert(TFormatType from, TFormatType to, T instance) Converts the specified instance from one format to another.
FormatConversionCallback<T,TFormatType>	getConversionCallback(TFormatType from, TFormatType to) Gets the callback that converts from one format to another.
int	getConversionDistance(TFormatType from, TFormatType to) Gets the number of intermediate conversions that must be done to convert from from to to.
void	registerConversion(TFormatType from, TFormatType to, FormatConversionCallback<T,TFormatType> conversion) Registers a conversion between formats.
void	registerConversion(TFormatType from, TFormatType to, FormatConversionCallback<T,TFormatType> conversion, TryFormatConversionCallback<T,TFormatType> tryConversion) Registers a conversion between formats.
boolean	tryConvert(TFormatType from, TFormatType to, T instance, T[] result) Tries to convert the specified instance from one format to another, returning success or failure.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FormatConverter

public FormatConverter()

Initializes a new instance.

Method Detail

convert

public final T convert(@Nonnull
                       TFormatType from,
                       @Nonnull
                       TFormatType to,
                       T instance)

Converts the specified instance from one format to another.

Parameters:

from - The source TFormatType.

to - The destination TFormatType.

instance - The instance of T to convert.

Returns:

An instance of T equivalent to from, in the new TFormatType to.

Throws:

ArgumentException - Thrown when there is no conversion defined from from to to.

tryConvert

public final boolean tryConvert(@Nonnull
                                TFormatType from,
                                @Nonnull
                                TFormatType to,
                                T instance,
                                @Nonnull
                                T[] result)

Tries to convert the specified instance from one format to another, returning success or failure.

Parameters:

from - The source TFormatType.

to - The destination TFormatType.

instance - The instance of T to convert.

result - On input, an array with one element. On return, the array is populated with the resulting instance of T equivalent to from, in the new TFormatType to.

Returns:

true if from could be converted to the requested TFormatType to; otherwise false.

Throws:

ArgumentException - Thrown when there is no conversion defined from from to to.

getConversionCallback

@Nullable
public final FormatConversionCallback<T,TFormatType> getConversionCallback(@Nonnull
                                                                                      TFormatType from,
                                                                                      @Nonnull
                                                                                      TFormatType to)

Gets the callback that converts from one format to another.

Parameters:

from - The source format.

to - The destination format.

Returns:

The callback to convert from from to to, or null if a conversion does not exist.

getConversionDistance

public final int getConversionDistance(@Nonnull
                                       TFormatType from,
                                       @Nonnull
                                       TFormatType to)

Gets the number of intermediate conversions that must be done to convert from from to to. For example, if a conversion function is defined to directly convert between the types, 1 will be returned. If the two types are identical, 0 will be returned. If no conversion exists at all, Integer.MAX_VALUE will be returned.

Parameters:

from - The source format.

to - The destination format.

Returns:

The number of conversion functions that must be invoked to convert between the formats.

registerConversion

public final void registerConversion(@Nonnull
                                     TFormatType from,
                                     @Nonnull
                                     TFormatType to,
                                     @Nonnull
                                     FormatConversionCallback<T,TFormatType> conversion)

Registers a conversion between formats.

Parameters:

from - The source format.

to - The destination format.

conversion - A delegate referring to a function to convert from from to to.

Throws:

ArgumentException - Thrown when registering a conversion between identical formats. The parameters from and to cannot be equal.

registerConversion

public final void registerConversion(@Nonnull
                                     TFormatType from,
                                     @Nonnull
                                     TFormatType to,
                                     @Nonnull
                                     FormatConversionCallback<T,TFormatType> conversion,
                                     @Nonnull
                                     TryFormatConversionCallback<T,TFormatType> tryConversion)

Registers a conversion between formats.

Parameters:

from - The source format.

to - The destination format.

conversion - A delegate referring to a function to convert from from to to.

tryConversion - A delegate referring to a function to try converting from from to to, returning success or failure.

Throws:

ArgumentException - Thrown when registering a conversion between identical formats. The parameters from and to cannot be equal.