1 /* 2 * Copyright (c) MuleSoft, Inc. All rights reserved. http://www.mulesoft.com 3 * The software in this package is published under the terms of the CPAL v1.0 4 * license, a copy of which has been included with this distribution in the 5 * LICENSE.txt file. 6 */ 7 package org.mule.api.transformer; 8 9 import org.mule.api.NamedObject; 10 import org.mule.api.context.MuleContextAware; 11 import org.mule.api.endpoint.ImmutableEndpoint; 12 import org.mule.api.lifecycle.Disposable; 13 import org.mule.api.lifecycle.Initialisable; 14 import org.mule.api.processor.MessageProcessor; 15 import org.mule.endpoint.EndpointAware; 16 17 import java.util.List; 18 19 /** 20 * <code>Transformer</code> can be chained together to covert message payloads 21 * from one object type to another. 22 */ 23 public interface Transformer extends MessageProcessor, Initialisable, Disposable, NamedObject, MuleContextAware, EndpointAware 24 { 25 26 /** 27 * Determines if a particular source class can be handled by this transformer 28 * 29 * @param aClass The class to check for compatability 30 * @return true if the transformer supports this type of class or false 31 * otherwise 32 * @deprecated use {@link #isSourceDataTypeSupported(org.mule.api.transformer.DataType)} instead 33 */ 34 @Deprecated 35 boolean isSourceTypeSupported(Class<?> aClass); 36 37 /** 38 * Determines if a particular source class can be handled by this transformer 39 * 40 * @param dataType The DataType to check for compatability 41 * @return true if the transformer supports this type of class or false 42 * otherwise 43 * @since 3.0.0 44 */ 45 boolean isSourceDataTypeSupported(DataType<?> dataType); 46 47 /** 48 * Returns an unmodifiable list of Source types registered on this transformer 49 * 50 * @return an unmodifiable list of Source types registered on this transformer 51 * @deprecated use {@link #getSourceDataTypes()} instead 52 */ 53 @Deprecated 54 List<Class<?>> getSourceTypes(); 55 56 /** 57 * Returns an unmodifiable list of Source types registered on this transformer 58 * 59 * @return an unmodifiable list of Source types registered on this transformer 60 * @since 3.0.0 61 */ 62 List<DataType<?>> getSourceDataTypes(); 63 64 /** 65 * Does this transformer allow null input? 66 * 67 * @return true if this transformer can accept null input 68 */ 69 boolean isAcceptNull(); 70 71 /** 72 * By default, Mule will throw an exception if a transformer is invoked with a source object that is not compatible 73 * with the transformer. Since transformers are often chained, it is useful to be able to ignore a transformer in the 74 * chain and move to the next one. 75 * 76 * @return true if the transformer can be ignorred if the currnet source type is not supported, false if an exception 77 * should be throw due to an incompatible source type being passed in. 78 */ 79 boolean isIgnoreBadInput(); 80 81 /** 82 * Thransforms the supplied data and returns the result 83 * 84 * @param src the data to transform 85 * @return the transformed data 86 * @throws TransformerException if a error occurs transforming the data or if the 87 * expected returnClass isn't the same as the transformed data 88 */ 89 Object transform(Object src) throws TransformerException; 90 91 /** 92 * Thransforms the supplied data and returns the result 93 * 94 * @param src the data to transform 95 * @param encoding the encoding to use by this transformer. many transformations will not need encoding unless 96 * dealing with text so you only need to use this method if yo wish to customize the encoding 97 * @return the transformed data 98 * @throws TransformerException if a error occurs transforming the data or if the 99 * expected returnClass isn't the same as the transformed data 100 */ 101 Object transform(Object src, String encoding) throws TransformerException; 102 103 /** 104 * Sets the expected return type for the transformed data. If the transformed 105 * data is not of this class type a <code>TransformerException</code> will be 106 * thrown. 107 * 108 * @param theClass the expected return type class 109 * @deprecated use {@link #setReturnDataType(DataType)} instead 110 */ 111 @Deprecated 112 void setReturnClass(Class<?> theClass); 113 114 /** 115 * Specifies the Java type of the result after this transformer has been executed. Mule will use this to validate 116 * the return type but also allow users to perform automatic transformations based on the source type of the object 117 * to transform and this return type. 118 * 119 * @return the excepted return type from this transformer 120 * @deprecated use {@link #getReturnDataType()} instead. 121 */ 122 @Deprecated 123 Class<?> getReturnClass(); 124 125 /** 126 * Sets the expected return type for the transformed data. If the transformed 127 * data is not of this class type a <code>TransformerException</code> will be 128 * thrown. 129 * <p/> 130 * This method superseeds {@link #getReturnClass()} because it allows Generics information to be associated with the 131 * return type of the transformer 132 * 133 * @param type the expected return type for this transformer 134 * @since 3.0.0 135 */ 136 void setReturnDataType(DataType<?> type); 137 138 /** 139 * Specifies the return type of the result after this transformer has been executed. Mule will use this to validate 140 * the return type but also allow users to perform automatic transformations based on the source type of the object 141 * to transform and this return type. 142 * <p/> 143 * This method superseeds {@link #getReturnClass()} because it allows Generics information to be associated with the 144 * return type of the transformer 145 * 146 * @return the excepted return type for this transformer 147 * @since 3.0.0 148 */ 149 DataType<?> getReturnDataType(); 150 151 /** 152 * Return the mime type returned by the transformer (if any). 153 */ 154 String getMimeType(); 155 156 /** 157 * Return the encoding returned by the transformer (if any). 158 */ 159 String getEncoding(); 160 161 /** 162 * The endpoint that this transformer is attached to 163 * @return the endpoint associated with the transformer 164 * @deprecated 165 */ 166 ImmutableEndpoint getEndpoint(); 167 168 }