1 /*
2 * $Id: Resources.java 354330 2005-12-06 06:05:19Z niallp $
3 * $Revision: 354330 $
4 * $Date: 2005-12-06 06:05:19 +0000 (Tue, 06 Dec 2005) $
5 *
6 * ====================================================================
7 *
8 * Copyright 2003-2005 The Apache Software Foundation
9 *
10 * Licensed under the Apache License, Version 2.0 (the "License");
11 * you may not use this file except in compliance with the License.
12 * You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * Unless required by applicable law or agreed to in writing, software
17 * distributed under the License is distributed on an "AS IS" BASIS,
18 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 * See the License for the specific language governing permissions and
20 * limitations under the License.
21 *
22 */
23
24 package org.apache.commons.resources;
25
26 import java.io.InputStream;
27 import java.io.Reader;
28 import java.io.Serializable;
29 import java.util.Iterator;
30 import java.util.Locale;
31
32 /**
33 * <p>An abstract representation of a set of internationalized resources,
34 * which are arbitrary objects identified by a unique String <code>key</code>.
35 * Localized versions of the resources (based on Locale parameter)
36 * can be retrieved in a variety of formats.</p>
37 *
38 * <p>When presented with an invalid <code>key</code> value, resource
39 * getter methods will behave differently based on the current value of
40 * the <code>returnNull</code> property for this {@link Resources} instance.
41 * If the property value is <code>true</code>, the getter method will return
42 * <code>null</code> (which may be ambiguous if <code>null</code> is a valid
43 * resource value). If the property value is <code>false</code>, a
44 * <code>ResourcesKeyException</code> will be thrown instead.</p>
45 *
46 * <p>Different implementations of the {@link Resources} interface support
47 * a variety of mechanisms for acquiring the data content represented by
48 * the keys. Examples could include property files, XML files, databases, web
49 * application resources, and other specialized approaches as desired.</p>
50 *
51 * <p>Different implementations of the {@link Resources} interface may apply
52 * different semantics to the use of the <code>locale</code>
53 * attribute used to perform localization. Consult
54 * the documentation for the specific {@link Resources} implementation you
55 * are using for the specific details of your implementation.</p>
56 *
57 * <p>Developers implementing {@link Resources} should extend the
58 * {@link org.apache.commons.resources.impl.ResourcesBase} class,
59 * and override the necessary methods,
60 * to shield themselves from future changes that may occur in this interface.
61 *
62 * @see org.apache.commons.resources.impl.ResourcesBase
63 * @see org.apache.commons.resources.impl.CollectionResourcesBase
64 * @see org.apache.commons.resources.impl.JDBCResources
65 * @see org.apache.commons.resources.impl.PropertyResources
66 * @see org.apache.commons.resources.impl.ResourceBundleResources
67 * @see org.apache.commons.resources.impl.WebappPropertyResources
68 * @see org.apache.commons.resources.impl.WebappXMLResources
69 * @see org.apache.commons.resources.impl.XMLResources
70 */
71 public interface Resources extends Serializable {
72
73
74 // ------------------------------------------------------ Lifecycle Methods
75
76
77 /**
78 * <p>This must be called to initialize the data content of this
79 * {@link Resources} instance, before any of the <code>getXxx()</code>
80 * methods are called.</p>
81 *
82 * @exception ResourcesException if an error occurs during initialization
83 */
84 public void init();
85
86
87 /**
88 * <p>This method must be called when the manager of this resource
89 * decides that it's no longer needed. After this method is called,
90 * no further calls to any of the <code>getXxx()</code> methods are
91 * allowed.</p>
92 *
93 * @exception ResourcesException if an error occurs during finalization
94 */
95 public void destroy();
96
97
98 // ------------------------------------------------------------- Properties
99
100
101 /**
102 * <p>Return an <code>Iterator</code> over the defined keys in this
103 * {@link Resources} instance.</p>
104 *
105 * @return The keys contained in this resources instance.
106 */
107 public Iterator getKeys();
108
109
110 /**
111 * <p>Return the logical name of this {@link Resources} instance.</p>
112 *
113 * @return The name of this resources instance.
114 */
115 public String getName();
116
117
118 /**
119 * <p>Return <code>true</code> if resource getter methods will return
120 * <code>null</code> instead of throwing an exception on invalid
121 * key values.</p>
122 * @return <code>true</code> if null is returned for invalid key values.
123 */
124 public boolean isReturnNull();
125
126
127 /**
128 * <p>Set a flag determining whether resource getter methods should
129 * return <code>null</code> instead of throwing an exception on
130 * invalid key values.</p>
131 *
132 * @param returnNull The new flag value
133 */
134 public void setReturnNull(boolean returnNull);
135
136
137 // ---------------------------------------------- Content Retrieval Methods
138
139
140 /**
141 * <p>Return the content for the specified <code>key</code> as a
142 * byte array, localized based on the specified <code>locale</code>.
143 * </p>
144 *
145 * @param key Identifier for the requested content
146 * @param locale Locale with which to localize retrieval,
147 * or <code>null</code> for the default Locale
148 * @return content for a specified key.
149 *
150 * @exception ResourcesException if an error occurs retrieving or
151 * returning the requested content
152 * @exception ResourcesKeyException if no value for the specified
153 * key was found, and <code>isReturnNull()</code> returns
154 * <code>false</code>
155 */
156 public byte[] getBytes(String key, Locale locale);
157
158
159 /**
160 * <p>Return the content for the specified <code>key</code> as an
161 * InputStream, localized based on the specified <code>locale</code>.
162 * </p>
163 *
164 * @param key Identifier for the requested content
165 * @param locale Locale with which to localize retrieval,
166 * or <code>null</code> for the default Locale
167 * @return content for a specified key.
168 *
169 * @exception ResourcesException if an error occurs retrieving or
170 * returning the requested content
171 * @exception ResourcesKeyException if no value for the specified
172 * key was found, and <code>isReturnNull()</code> returns
173 * <code>false</code>
174 */
175 public InputStream getInputStream(String key, Locale locale);
176
177
178 /**
179 * <p>Return the content for the specified <code>key</code> as an
180 * Object, localized based on the specified <code>locale</code>.
181 * </p>
182 *
183 * @param key Identifier for the requested content
184 * @param locale Locale with which to localize retrieval,
185 * or <code>null</code> for the default Locale
186 * @return content for a specified key.
187 *
188 * @exception ResourcesException if an error occurs retrieving or
189 * returning the requested content
190 * @exception ResourcesKeyException if no value for the specified
191 * key was found, and <code>isReturnNull()</code> returns
192 * <code>false</code>
193 */
194 public Object getObject(String key, Locale locale);
195
196
197 /**
198 * <p>Return the content for the specified <code>key</code> as a
199 * Reader, localized based on the specified <code>locale</code>.
200 * </p>
201 *
202 * @param key Identifier for the requested content
203 * @param locale Locale with which to localize retrieval,
204 * or <code>null</code> for the default Locale
205 * @return content for a specified key.
206 *
207 * @exception ResourcesException if an error occurs retrieving or
208 * returning the requested content
209 * @exception ResourcesKeyException if no value for the specified
210 * key was found, and <code>isReturnNull()</code> returns
211 * <code>false</code>
212 */
213 public Reader getReader(String key, Locale locale);
214
215
216 /**
217 * <p>Return the content for the specified <code>key</code> as a
218 * String, localized based on the specified <code>locale</code>.
219 * </p>
220 *
221 * @param key Identifier for the requested content
222 * @param locale Locale with which to localize retrieval,
223 * or <code>null</code> for the default Locale
224 * @return content for a specified key.
225 *
226 * @exception ResourcesException if an error occurs retrieving or
227 * returning the requested content
228 * @exception ResourcesKeyException if no value for the specified
229 * key was found, and <code>isReturnNull()</code> returns
230 * <code>false</code>
231 */
232 public String getString(String key, Locale locale);
233
234
235 }
236
237