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.io.Writer;
23 import java.lang.reflect.Method;
24
25 import org.peaseplate.DefaultMacro;
26 import org.peaseplate.Macro;
27 import org.peaseplate.RenderContext;
28
29 /**
30 * The macro service. Stores and holds predefined macros.
31 *
32 * @author Manfred HANTSCHEL
33 */
34 public interface MacroService {
35
36 /**
37 * Scans the specified class loaders for macro service definitions.
38 * The definitions are located in a resource with the name
39 * "META-INF/services/org.peaseplate.service.MacroService".
40 * The file contains class names of macros, one class name per line.
41 * The name of the macros will be the name of each class
42 * trimming "Macro" and "Macros" at the end. This can be
43 * overruled by using the {@link Macro} annotation.
44 *
45 * The class must contains at lease one method annotated as {@link Macro}
46 * or {@link DefaultMacro} and conform the following rules:
47 *
48 * <ul>
49 * <li>The method must have no return value</li>
50 * <li>The first parameter must be a {@link RenderContext}</li>
51 * <li>The second parameter must be a {@link Writer}</li>
52 * </ul>
53 *
54 * @param classLoaders the class loaders
55 * @throws IllegalArgumentException if a class could not be instantiated
56 */
57 public void add(ClassLoader... classLoaders);
58
59 /**
60 * Adds the macro specified by the class.
61 * Creates an instance immediately and calls the add method.
62 * The name of the macro will be the name of the class
63 * trimming "Macro" and "Macros" at the end. This can be
64 * overruled by using the {@link Macro} annotation.
65 *
66 * The class must contains at lease one method annotated as {@link Macro}
67 * or {@link DefaultMacro} and conform the following rules:
68 *
69 * <ul>
70 * <li>The method must have no return value</li>
71 * <li>The first parameter must be a {@link RenderContext}</li>
72 * <li>The second parameter must be a {@link Writer}</li>
73 * </ul>
74 *
75 * @param macroClass the macro class
76 * @throws IllegalArgumentException if the instance could not be created
77 */
78 public void add(Class<?> macroClass) throws IllegalArgumentException;
79
80 /**
81 * Adds the specified macro class. The name of the macro will be the name
82 * of the class trimming "Macro" and "Macros" at the end. This can be
83 * overruled by using the {@link Macro} annotation.
84 *
85 * The class must contains at lease one method annotated as {@link Macro}
86 * or {@link DefaultMacro} and conform the following rules:
87 *
88 * <ul>
89 * <li>The method must have no return value</li>
90 * <li>The first parameter must be a {@link RenderContext}</li>
91 * <li>The second parameter must be a {@link Writer}</li>
92 * </ul>
93 *
94 * @param macro the macro class
95 * @throws IllegalArgumentException on occasion
96 */
97 public void add(Object macro) throws IllegalArgumentException;
98
99 public Object getInstance(String name);
100
101 public Method getMethod(String name, String extension, int numberOfParameters);
102
103 }