/*
* Copyright (C) 2006-2016 DLR, Germany
*
* All rights reserved
*
* http://www.rcenvironment.de/
*/
package de.rcenvironment.core.datamodel.api;
/**
* Defines and performs conversions between {@link DataType}s.
*
* @author Robert Mischke
*/
public interface TypedDatumConverter {
/**
* Transforms the given {@link TypedDatum} into a {@link TypedDatum} of the given target type.
* The transformation may be performed by modifying properties of the input {@link TypedDatum}
* or copying its contents to a new object. If no modification is necessary, this method may
* also return the unmodified input {@link TypedDatum}.
*
* @param input the {@link TypedDatum} to transform
* @param targetType the desired {@link DataType}, specified by the target Java class
* @return the new {@link TypedDatum}
* @throws DataTypeException if the requested conversion is impossible
* @param <T> equal to targetType; used to specify the return type
*/
<T extends TypedDatum> T castOrConvert(TypedDatum input, Class<T> targetType) throws DataTypeException;
/**
* Transforms the given {@link TypedDatum} into a {@link TypedDatum} of the given target type.
* The transformation may be performed by modifying properties of the input {@link TypedDatum}
* or copying its contents to a new object. If no modification is necessary, this method may
* also return the unmodified input {@link TypedDatum}.
*
* Note that as class information is not available at compile time, this method only returns an
* unspecified {@link TypedDatum}. If this is unsuitable, use
* {@link #castOrConvert(TypedDatum, Class)}.
*
* @param input the {@link TypedDatum} to transform
* @param targetType the desired {@link DataType}
* @return the new {@link TypedDatum}
* @throws DataTypeException if the requested conversion is impossible
*/
TypedDatum castOrConvert(TypedDatum input, DataType targetType) throws DataTypeException;
/**
* @param input the source {@link TypedDatum}
* @param targetType the target type, specified by the target Java class
* @return true if the source {@link TypedDatum} can be safely converted to the target type
*/
boolean isConvertibleTo(TypedDatum input, Class<? extends TypedDatum> targetType);
/**
* @param input the source {@link TypedDatum}
* @param targetType the target type
* @return true if the source {@link TypedDatum} can be safely converted to the target type
*/
boolean isConvertibleTo(TypedDatum input, DataType targetType);
/**
* @param sourceType source {@link DataType}
* @param targetType the target {@link DataType}
* @return true if the source {@link TypedDatum} can be safely converted to the target type
*/
boolean isConvertibleTo(DataType sourceType, DataType targetType);
/**
* Transforms the given {@link TypedDatum} into a {@link TypedDatum} of the given target type.<br>
* <b>This conversion will be unsafe, so a correct conversion the other way is not
* guaranteed.</b><br>
* The transformation may be performed by modifying properties of the input {@link TypedDatum}
* or copying its contents to a new object. If no modification is necessary, this method may
* also return the unmodified input {@link TypedDatum}.
*
* @param input the {@link TypedDatum} to transform
* @param targetType the desired {@link DataType}, specified by the target Java class
* @return the new {@link TypedDatum}
* @throws DataTypeException if the requested conversion is impossible
* @param <T> equal to targetType; used to specify the return type
*/
<T extends TypedDatum> T castOrConvertUnsafe(TypedDatum input, Class<T> targetType) throws DataTypeException;
/**
* Transforms the given {@link TypedDatum} into a {@link TypedDatum} of the given target type.<br>
* <b>This conversion will be unsafe, so a correct conversion the other way is not
* guaranteed.</b><br>
* The transformation may be performed by modifying properties of the input {@link TypedDatum}
* or copying its contents to a new object. If no modification is necessary, this method may
* also return the unmodified input {@link TypedDatum}.
*
* Note that as class information is not available at compile time, this method only returns an
* unspecified {@link TypedDatum}. If this is unsuitable, use
* {@link #castOrConvert(TypedDatum, Class)}.
*
* @param input the {@link TypedDatum} to transform
* @param targetType the desired {@link DataType}
* @return the new {@link TypedDatum}
* @throws DataTypeException if the requested conversion is impossible
*/
TypedDatum castOrConvertUnsafe(TypedDatum input, DataType targetType) throws DataTypeException;
/**
* @param input the source {@link TypedDatum}
* @param targetType the target type, specified by the target Java class
* @return true if the source {@link TypedDatum} can be safely converted to the target type
*/
boolean isUnsafeConvertibleTo(TypedDatum input, Class<? extends TypedDatum> targetType);
/**
* @param input the source {@link TypedDatum}
* @param targetType the target type
* @return true if the source {@link TypedDatum} can be safely converted to the target type
*/
boolean isUnsafeConvertibleTo(TypedDatum input, DataType targetType);
/**
* @param sourceType source {@link DataType}
* @param targetType the target {@link DataType}
* @return true if the source {@link TypedDatum} can be safely converted to the target type
*/
boolean isUnsafeConvertibleTo(DataType sourceType, DataType targetType);
}