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