001 /*
002 * $Id: Resources.java 354330 2005-12-06 06:05:19Z niallp $
003 * $Revision: 354330 $
004 * $Date: 2005-12-06 06:05:19 +0000 (Tue, 06 Dec 2005) $
005 *
006 * ====================================================================
007 *
008 * Copyright 2003-2005 The Apache Software Foundation
009 *
010 * Licensed under the Apache License, Version 2.0 (the "License");
011 * you may not use this file except in compliance with the License.
012 * You may obtain a copy of the License at
013 *
014 * http://www.apache.org/licenses/LICENSE-2.0
015 *
016 * Unless required by applicable law or agreed to in writing, software
017 * distributed under the License is distributed on an "AS IS" BASIS,
018 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
019 * See the License for the specific language governing permissions and
020 * limitations under the License.
021 *
022 */
023
024 package org.apache.commons.resources;
025
026 import java.io.InputStream;
027 import java.io.Reader;
028 import java.io.Serializable;
029 import java.util.Iterator;
030 import java.util.Locale;
031
032 /**
033 * <p>An abstract representation of a set of internationalized resources,
034 * which are arbitrary objects identified by a unique String <code>key</code>.
035 * Localized versions of the resources (based on Locale parameter)
036 * can be retrieved in a variety of formats.</p>
037 *
038 * <p>When presented with an invalid <code>key</code> value, resource
039 * getter methods will behave differently based on the current value of
040 * the <code>returnNull</code> property for this {@link Resources} instance.
041 * If the property value is <code>true</code>, the getter method will return
042 * <code>null</code> (which may be ambiguous if <code>null</code> is a valid
043 * resource value). If the property value is <code>false</code>, a
044 * <code>ResourcesKeyException</code> will be thrown instead.</p>
045 *
046 * <p>Different implementations of the {@link Resources} interface support
047 * a variety of mechanisms for acquiring the data content represented by
048 * the keys. Examples could include property files, XML files, databases, web
049 * application resources, and other specialized approaches as desired.</p>
050 *
051 * <p>Different implementations of the {@link Resources} interface may apply
052 * different semantics to the use of the <code>locale</code>
053 * attribute used to perform localization. Consult
054 * the documentation for the specific {@link Resources} implementation you
055 * are using for the specific details of your implementation.</p>
056 *
057 * <p>Developers implementing {@link Resources} should extend the
058 * {@link org.apache.commons.resources.impl.ResourcesBase} class,
059 * and override the necessary methods,
060 * to shield themselves from future changes that may occur in this interface.
061 *
062 * @see org.apache.commons.resources.impl.ResourcesBase
063 * @see org.apache.commons.resources.impl.CollectionResourcesBase
064 * @see org.apache.commons.resources.impl.JDBCResources
065 * @see org.apache.commons.resources.impl.PropertyResources
066 * @see org.apache.commons.resources.impl.ResourceBundleResources
067 * @see org.apache.commons.resources.impl.WebappPropertyResources
068 * @see org.apache.commons.resources.impl.WebappXMLResources
069 * @see org.apache.commons.resources.impl.XMLResources
070 */
071 public interface Resources extends Serializable {
072
073
074 // ------------------------------------------------------ Lifecycle Methods
075
076
077 /**
078 * <p>This must be called to initialize the data content of this
079 * {@link Resources} instance, before any of the <code>getXxx()</code>
080 * methods are called.</p>
081 *
082 * @exception ResourcesException if an error occurs during initialization
083 */
084 public void init();
085
086
087 /**
088 * <p>This method must be called when the manager of this resource
089 * decides that it's no longer needed. After this method is called,
090 * no further calls to any of the <code>getXxx()</code> methods are
091 * allowed.</p>
092 *
093 * @exception ResourcesException if an error occurs during finalization
094 */
095 public void destroy();
096
097
098 // ------------------------------------------------------------- Properties
099
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