/*
* Copyright (c) MuleSoft, Inc. All rights reserved. http://www.mulesoft.com
* The software in this package is published under the terms of the CPAL v1.0
* license, a copy of which has been included with this distribution in the
* LICENSE.txt file.
*/
package org.mule.runtime.core.api.transformer;
import static org.mule.runtime.core.api.processor.ReactiveProcessor.ProcessingType.CPU_INTENSIVE;
import static org.mule.runtime.core.api.processor.ReactiveProcessor.ProcessingType.CPU_LITE;
import static org.mule.runtime.core.api.processor.ReactiveProcessor.ProcessingType.IO_RW;
import org.mule.runtime.api.metadata.DataType;
import org.mule.runtime.api.meta.NameableObject;
import org.mule.runtime.core.api.context.MuleContextAware;
import org.mule.runtime.api.lifecycle.Disposable;
import org.mule.runtime.api.lifecycle.Initialisable;
import org.mule.runtime.core.api.processor.Processor;
import java.nio.charset.Charset;
import java.util.List;
/**
* <code>Transformer</code> can be chained together to covert message payloads from one object type to another.
*/
public interface Transformer extends Processor, Initialisable, Disposable, NameableObject, MuleContextAware {
/**
* Determines if a particular source class can be handled by this transformer
*
* @param dataType The DataType to check for compatibility
* @return true if the transformer supports this type of class or false otherwise
* @since 3.0.0
*/
boolean isSourceDataTypeSupported(DataType dataType);
/**
* Returns an unmodifiable list of Source types registered on this transformer
*
* @return an unmodifiable list of Source types registered on this transformer
* @since 3.0.0
*/
List<DataType> getSourceDataTypes();
/**
* Does this transformer allow null input?
*
* @return true if this transformer can accept null input
*/
boolean isAcceptNull();
/**
* By default, Mule will throw an exception if a transformer is invoked with a source object that is not compatible with the
* transformer. Since transformers are often chained, it is useful to be able to ignore a transformer in the chain and move to
* the next one.
*
* @return true if the transformer can be ignored if the current source type is not supported, false if an exception should be
* throw due to an incompatible source type being passed in.
*/
boolean isIgnoreBadInput();
/**
* Transforms the supplied data and returns the result
*
* @param src the data to transform
* @return the transformed data
* @throws TransformerException if a error occurs transforming the data or if the expected returnClass isn't the same as the
* transformed data
*/
Object transform(Object src) throws TransformerException;
/**
* Transforms the supplied data and returns the result
*
* @param src the data to transform
* @param encoding the encoding to use by this transformer. many transformations will not need encoding unless dealing with text
* so you only need to use this method if yo wish to customize the encoding
* @return the transformed data
* @throws TransformerException if a error occurs transforming the data or if the expected returnClass isn't the same as the
* transformed data
*/
Object transform(Object src, Charset encoding) throws TransformerException;
/**
* Sets the expected return type for the transformed data. If the transformed data is not of this class type a
* <code>TransformerException</code> will be thrown.
*
* @param type the expected return type for this transformer
* @since 3.0.0
*/
void setReturnDataType(DataType type);
/**
* Specifies the return type of the result after this transformer has been executed. Mule will use this to validate the return
* type but also allow users to perform automatic transformations based on the source type of the object to transform and this
* return type.
*
* @return the excepted return type for this transformer
* @since 3.0.0
*/
DataType getReturnDataType();
@Override
default ProcessingType getProcessingType() {
return CPU_INTENSIVE;
}
}