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.util.Locale;
23
24 import org.peaseplate.Messages;
25 import org.peaseplate.Template;
26 import org.peaseplate.TemplateEngine;
27 import org.peaseplate.TemplateException;
28 import org.peaseplate.internal.ResourceKey;
29 import org.peaseplate.resolver.Resolver;
30
31 /**
32 * The cache service is responsible for caching templates and messages,
33 * to load them if they are on in the cache and
34 * to reload them if they are outdated.
35 *
36 * @author Manfred Hantschel
37 */
38 public interface CacheService {
39
40 /**
41 * Returns the template with the specified name.
42 * <br/><br/>
43 * The name of the template is usually some path on the file system or
44 * the resources but you can enhance this by implementing an own {@link Resolver}.
45 *
46 * @param engine the template engine
47 * @param name the name of the template
48 * @return the template or null if not found
49 * @throws TemplateException if anything goes wrong
50 */
51 public Template getTemplate(TemplateEngine engine, String name) throws TemplateException;
52
53 /**
54 * Returns the template with the specified name.
55 * <br/><br/>
56 * The name of the template is usually some path on the file system or
57 * the resources but you can enhance this by implementing an own {@link Resolver}.
58 *
59 * @param engine the template engine
60 * @param name the name of the template
61 * @param locale the locale; uses the default locale if null
62 * @return the template or null if not found
63 * @throws TemplateException if anything goes wrong
64 */
65 public Template getTemplate(TemplateEngine engine, String name, Locale locale) throws TemplateException;
66
67 /**
68 * Returns the template with the specified name.
69 * <br/><br/>
70 * The name of the template is usually some path on the file system or
71 * the resources but you can enhance this by implementing an own {@link Resolver}.
72 *
73 * @param engine the template engine
74 * @param name the name of the template
75 * @param encoding the encoding; uses the default encoding if null
76 * @return the template or null if not found
77 * @throws TemplateException if anything goes wrong
78 */
79 public Template getTemplate(TemplateEngine engine, String name, String encoding) throws TemplateException;
80
81 /**
82 * Returns the template with the specified name.
83 * <br/><br/>
84 * The name of the template is usually some path on the file system or
85 * the resources but you can enhance this by implementing an own {@link Resolver}.
86 *
87 * @param engine the template engine
88 * @param name the name of the template
89 * @param locale the locale; uses the default locale if null
90 * @param encoding the encoding; uses the default encoding if null
91 * @return the template or null if not found
92 * @throws TemplateException if anything goes wrong
93 */
94 public Template getTemplate(TemplateEngine engine, String name, Locale locale, String encoding) throws TemplateException;
95
96 public Template getTemplate(TemplateEngine engine, ResourceKey key) throws TemplateException;
97
98 /**
99 * Returns the messages with the specified name. Makes use of the CacheService.
100 * <br/><br/>
101 * The name is usually the template name. The extension will get replaced by ".properties".
102 * But internally it depends on the resolver, which you can enhance by implementing your own.
103 *
104 * @param engine the template engine
105 * @param name the name of the template (The extension will get replaces by ".properties"
106 * @return the messages or null if not found
107 * @throws TemplateException if anything goes wrong
108 */
109 public Messages getMessages(TemplateEngine engine, String name) throws TemplateException;
110
111 /**
112 * Returns the messages with the specified name. Makes use of the CacheService.
113 * <br/><br/>
114 * The name is usually the template name. The extension will get replaced by ".properties".
115 * But internally it depends on the resolver, which you can enhance by implementing your own.
116 *
117 * @param engine the template engine
118 * @param name the name of the template (The extension will get replaces by ".properties"
119 * @param locale the locale; uses the default locale if null
120 * @return the messages or null if not found
121 * @throws TemplateException if anything goes wrong
122 */
123 public Messages getMessages(TemplateEngine engine, String name, Locale locale) throws TemplateException;
124
125 /**
126 * Returns the messages with the specified name. Makes use of the CacheService.
127 * <br/><br/>
128 * The name is usually the template name. The extension will get replaced by ".properties".
129 * But internally it depends on the resolver, which you can enhance by implementing your own.
130 *
131 * @param engine the template engine
132 * @param name the name of the template (The extension will get replaces by ".properties"
133 * @param encoding the encoding; uses the default encoding if null, but usually not needed,
134 * the messages are loaded from properties file, and properties files have their own
135 * encoding
136 * @return the messages or null if not found
137 * @throws TemplateException if anything goes wrong
138 */
139 public Messages getMessages(TemplateEngine engine, String name, String encoding) throws TemplateException;
140
141 /**
142 * Returns the messages with the specified name. Makes use of the CacheService.
143 * <br/><br/>
144 * The name is usually the template name. The extension will get replaced by ".properties".
145 * But internally it depends on the resolver, which you can enhance by implementing your own.
146 *
147 * @param engine the template engine
148 * @param name the name of the template (The extension will get replaces by ".properties"
149 * @param locale the locale; uses the default locale if null
150 * @param encoding the encoding; uses the default encoding if null, but usually not needed,
151 * the messages are loaded from properties file, and properties files have their own
152 * encoding
153 * @return the messages or null if not found
154 * @throws TemplateException if anything goes wrong
155 */
156 public Messages getMessages(TemplateEngine engine, String name, Locale locale, String encoding) throws TemplateException;
157
158 public Messages getMessages(TemplateEngine engine, ResourceKey key) throws TemplateException;
159
160 }