View Javadoc
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 }