View Javadoc

1   /*
2    * $Id: Transformer.java 20321 2010-11-24 15:21:24Z 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.annotations;
12  
13  import java.lang.annotation.Documented;
14  import java.lang.annotation.ElementType;
15  import java.lang.annotation.Retention;
16  import java.lang.annotation.RetentionPolicy;
17  import java.lang.annotation.Target;
18  
19  /**
20   * Used to mark a that a class contains methods which are Mule Transformer, which means it will be made available in the Mule container.
21   * Transformers are used to convert one object type to another.  Mule uses them to provide automatic conversion of Java types
22   * and now support Mime type conversion too.
23   *
24   * The parameters passed into the method define the source object(s) to transform, the return type of the method defines the return object type.
25   * Transformers can define additional source types, that when received will be automatically converted to the parameter type accepted by
26   * the annotated method.
27   *
28   * There are some rules to follow when writing a transformer method -
29   * <ol>
30   * <li>The method's declaring class must be annotated with ContainsTransformerMethods</li>
31   * <li>The annotation must appear on a concrete method, not on an abstract or interface method</li>
32   * <li>The method must be public</li>
33   * <li>The method must have a non-void return type</li>
34   * <li>The method must have at least one parameter argument</li>
35   * </ol>
36   *
37   * It is good practice to define any custom transformers in their own class (a class can have more than one transformer method).
38   * A transformer class should be thread-safe and not have any transitive state, meaning that it should not maintain state as
39   * a result of a transformation. It is fine for transformers to have configuration state, such as in an XSLT or XQuery template file
40   * (note that Mule already provides transformers for XSLT and XQuery).
41   */
42  @Target(ElementType.METHOD)
43  @Retention(RetentionPolicy.RUNTIME)
44  @Documented
45  public @interface Transformer
46  {
47      /**
48       * The 'priorityWeighting property is used to resolve conflicts where there is more than one transformers that match
49       * the selection criteria.  10 is the highest priority and 1 is the lowest.
50       *
51       * @return the priority weighting for this transformer. If the class defines more than one transform method, every transform
52       *         method will have the same weighting.
53       */
54      int priorityWeighting() default 5;
55  
56      //TODO BL-140 add when we get support for Transformer mime types
57  //    String sourceMimeType() default MimeTypes.ANY;
58  //
59  //    String resultMimeType() default MimeTypes.ANY;
60  
61      /**
62       * SourceTypes define additional types that this transformer will accepts as a sourceType (beyond the method parameter).
63       * At run time if the current message matches one of these source types, Mule will attempt to transform from
64       * the source type to the method parameter type.  This means that transformations can be chained. The user can create
65       * other transformers to be a part of this chain.
66       *
67       * @return an array of class types which allow the transformer to be matched on
68       */
69      Class[] sourceTypes() default {};
70  }