1 /*
2 * This file is part of Pease Plate Template Engine.
3 *
4 * Pease Plate Template Engine is free software: you can redistribute
5 * it and/or modify it under the terms of the GNU Lesser General
6 * Public License as published by the Free Software Foundation,
7 * either version 3 of the License, or any later version.
8 *
9 * Pease Plate Template Engine is distributed in the hope that it
10 * will be useful, but WITHOUT ANY WARRANTY; without even the implied
11 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
12 * See the GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with Pease Plate Template Engine. If not, see
16 * <http://www.gnu.org/licenses/>.
17 *
18 * Copyright (c) 2008 Manfred HANTSCHEL
19 */
20 package org.peaseplate.service;
21
22 import java.lang.reflect.Method;
23
24 import org.peaseplate.DefaultTransformer;
25 import org.peaseplate.RenderContext;
26 import org.peaseplate.Transformer;
27
28 /**
29 * The transformer service stores and hold predefined transformers.
30 *
31 * @author Manfred HANTSCHEL
32 */
33 public interface TransformerService {
34
35 /**
36 * Scans the specified class loaders for transformer service definitions.
37 * The definitions are located in a resource with the name
38 * "META-INF/services/org.peaseplate.service.TransformerService".
39 * The file contains class names of transformers, one class name per line.
40 * The name of the transformers will be the name of each class
41 * trimming "Transformer" and "Transformers" at the end. This can be
42 * overruled by using the {@link Transformer} annotation.
43 *
44 * The class must contains at lease one method annotated as {@link Transformer}
45 * or {@link DefaultTransformer} and conform the following rules:
46 *
47 * <ul>
48 * <li>The method must have a return value</li>
49 * <li>The first parameter must be a {@link RenderContext}</li>
50 * <li>There must be a second parameter that can be of any type. It contains the value to be transformed.</li>
51 * </ul>
52 *
53 * @param classLoaders the class loaders
54 * @throws IllegalArgumentException if a class could not be instantiated
55 */
56 public void add(ClassLoader... classLoaders);
57
58 /**
59 * Adds the transformer specified by the class.
60 * Creates an instance immediately and calls the add method.
61 * The name of the transformer will be the name of the class
62 * trimming "Transformer" and "Transformers" at the end. This can be
63 * overruled by using the {@link Transformer} annotation.
64 *
65 * The class must contains at lease one method annotated as {@link Transformer}
66 * or {@link DefaultTransformer} and conform the following rules:
67 *
68 * <ul>
69 * <li>The method must have a return value</li>
70 * <li>The first parameter must be a {@link RenderContext}</li>
71 * <li>There must be a second parameter that can be of any type. It contains the value to be transformed.</li>
72 * </ul>
73
74 *
75 * @param transformerClass the transformer class
76 * @throws IllegalArgumentException if the instance could not be created
77 */
78 public void add(Class<?> transformerClass) throws IllegalArgumentException;
79
80 /**
81 * Adds the specified transformer class. The name of the transformer will be the name
82 * of the class trimming "Transformer" and "Transformers" at the end. This can be
83 * overruled by using the {@link Transformer} annotation.
84 *
85 * The class must contains at lease one method annotated as {@link Transformer}
86 * or {@link DefaultTransformer} and conform the following rules:
87 *
88 * <ul>
89 * <li>The method must have a return value</li>
90 * <li>The first parameter must be a {@link RenderContext}</li>
91 * <li>There must be a second parameter that can be of any type. It contains the value to be transformed.</li>
92 * </ul>
93 *
94 * @param transformer the transformer class
95 * @throws IllegalArgumentException on occasion
96 */
97 public void add(Object transformer) throws IllegalArgumentException;
98
99 public Object getInstance(String name);
100
101 public Method getMethod(String name, String extension, int numberOfParameters);
102
103 }