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 org.peaseplate.TemplateEngine;
23 import org.peaseplate.TemplateException;
24 import org.peaseplate.internal.ResourceKey;
25 import org.peaseplate.locator.MessagesLocator;
26 import org.peaseplate.locator.TemplateLocator;
27 import org.peaseplate.resolver.Resolver;
28
29 /**
30 * The resolver service is used to resolve templates and messages
31 * from somewhere by the specified key that contains the name and the locale.
32 *
33 * The resolver service can be enhanced by adding {@link Resolver}s to it.
34 *
35 * @author Manfred Hantschel
36 */
37 public interface ResolverService {
38
39 /**
40 * Scans the specified class loaders for resolver service definitions.
41 * The definitions are located in a resource with the name
42 * "META-INF/services/org.peaseplate.service.ResolverService".
43 * The file contains class names of {@link Resolver}s, one class name per line.
44 *
45 * @param classLoaders the class loaders
46 * @throws IllegalArgumentException if a class could not be instantiated
47 */
48 public void add(ClassLoader... classLoaders) throws IllegalArgumentException;
49
50 /**
51 * Adds the resolver to the service.
52 * Creates the instance immediately.
53 *
54 * @param resolverClass
55 * @throws IllegalArgumentException if the instance could not be created
56 */
57 public void add(Class<? extends Resolver> resolverClass) throws IllegalArgumentException;
58
59 /**
60 * Add the sepcified resolver to the service.
61 *
62 * @param resolver a resolver
63 */
64 public void add(Resolver resolver);
65
66 /**
67 * Asks all resolvers for a template described by the specified key
68 * and returns a locator for the template if found.
69 *
70 * @param engine the engine
71 * @param key the key
72 * @return a {@link TemplateLocator} or null if the template was not found
73 * @throws TemplateException on any error
74 */
75 public TemplateLocator getTemplate(TemplateEngine engine, ResourceKey key) throws TemplateException;
76
77 /**
78 * Asks all resolvers for a messages object described by the specified key
79 * and returns a locator for the messages if found.
80 *
81 * @param engine the engine
82 * @param key the key
83 * @return a {@link MessagesLocator} or null if the messages were not found
84 * @throws TemplateException on any error
85 */
86 public MessagesLocator getMessages(TemplateEngine engine, ResourceKey key) throws TemplateException;
87
88 }