View Javadoc

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 }