001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.resources;
019
020 import java.io.InputStream;
021 import java.io.Reader;
022 import java.io.Serializable;
023 import java.util.Iterator;
024 import java.util.Locale;
025
026 /**
027 * <p>An abstract representation of a set of internationalized resources,
028 * which are arbitrary objects identified by a unique String <code>key</code>.
029 * Localized versions of the resources (based on Locale parameter)
030 * can be retrieved in a variety of formats.</p>
031 *
032 * <p>When presented with an invalid <code>key</code> value, resource
033 * getter methods will behave differently based on the current value of
034 * the <code>returnNull</code> property for this {@link Resources} instance.
035 * If the property value is <code>true</code>, the getter method will return
036 * <code>null</code> (which may be ambiguous if <code>null</code> is a valid
037 * resource value). If the property value is <code>false</code>, a
038 * <code>ResourcesKeyException</code> will be thrown instead.</p>
039 *
040 * <p>Different implementations of the {@link Resources} interface support
041 * a variety of mechanisms for acquiring the data content represented by
042 * the keys. Examples could include property files, XML files, databases, web
043 * application resources, and other specialized approaches as desired.</p>
044 *
045 * <p>Different implementations of the {@link Resources} interface may apply
046 * different semantics to the use of the <code>locale</code>
047 * attribute used to perform localization. Consult
048 * the documentation for the specific {@link Resources} implementation you
049 * are using for the specific details of your implementation.</p>
050 *
051 * <p>Developers implementing {@link Resources} should extend the
052 * {@link org.apache.commons.resources.impl.ResourcesBase} class,
053 * and override the necessary methods,
054 * to shield themselves from future changes that may occur in this interface.
055 *
056 * @see org.apache.commons.resources.impl.ResourcesBase
057 * @see org.apache.commons.resources.impl.CollectionResourcesBase
058 * @see org.apache.commons.resources.impl.JDBCResources
059 * @see org.apache.commons.resources.impl.PropertyResources
060 * @see org.apache.commons.resources.impl.ResourceBundleResources
061 * @see org.apache.commons.resources.impl.WebappPropertyResources
062 * @see org.apache.commons.resources.impl.WebappXMLResources
063 * @see org.apache.commons.resources.impl.XMLResources
064 */
065 public interface Resources extends Serializable {
066
067
068 // ------------------------------------------------------ Lifecycle Methods
069
070
071 /**
072 * <p>This must be called to initialize the data content of this
073 * {@link Resources} instance, before any of the <code>getXxx()</code>
074 * methods are called.</p>
075 *
076 * @exception ResourcesException if an error occurs during initialization
077 */
078 public void init();
079
080
081 /**
082 * <p>This method must be called when the manager of this resource
083 * decides that it's no longer needed. After this method is called,
084 * no further calls to any of the <code>getXxx()</code> methods are
085 * allowed.</p>
086 *
087 * @exception ResourcesException if an error occurs during finalization
088 */
089 public void destroy();
090
091
092 // ------------------------------------------------------------- Properties
093
094
095 /**
096 * <p>Return an <code>Iterator</code> over the defined keys in this
097 * {@link Resources} instance.</p>
098 *
099 * @return The keys contained in this resources instance.
100 */
101 public Iterator getKeys();
102
103
104 /**
105 * <p>Return the logical name of this {@link Resources} instance.</p>
106 *
107 * @return The name of this resources instance.
108 */
109 public String getName();
110
111
112 /**
113 * <p>Return <code>true</code> if resource getter methods will return
114 * <code>null</code> instead of throwing an exception on invalid
115 * key values.</p>
116 * @return <code>true</code> if null is returned for invalid key values.
117 */
118 public boolean isReturnNull();
119
120
121 /**
122 * <p>Set a flag determining whether resource getter methods should
123 * return <code>null</code> instead of throwing an exception on
124 * invalid key values.</p>
125 *
126 * @param returnNull The new flag value
127 */
128 public void setReturnNull(boolean returnNull);
129
130
131 // ---------------------------------------------- Content Retrieval Methods
132
133
134 /**
135 * <p>Return the content for the specified <code>key</code> as a
136 * byte array, localized based on the specified <code>locale</code>.
137 * </p>
138 *
139 * @param key Identifier for the requested content
140 * @param locale Locale with which to localize retrieval,
141 * or <code>null</code> for the default Locale
142 * @return content for a specified key.
143 *
144 * @exception ResourcesException if an error occurs retrieving or
145 * returning the requested content
146 * @exception ResourcesKeyException if no value for the specified
147 * key was found, and <code>isReturnNull()</code> returns
148 * <code>false</code>
149 */
150 public byte[] getBytes(String key, Locale locale);
151
152
153 /**
154 * <p>Return the content for the specified <code>key</code> as an
155 * InputStream, localized based on the specified <code>locale</code>.
156 * </p>
157 *
158 * @param key Identifier for the requested content
159 * @param locale Locale with which to localize retrieval,
160 * or <code>null</code> for the default Locale
161 * @return content for a specified key.
162 *
163 * @exception ResourcesException if an error occurs retrieving or
164 * returning the requested content
165 * @exception ResourcesKeyException if no value for the specified
166 * key was found, and <code>isReturnNull()</code> returns
167 * <code>false</code>
168 */
169 public InputStream getInputStream(String key, Locale locale);
170
171
172 /**
173 * <p>Return the content for the specified <code>key</code> as an
174 * Object, localized based on the specified <code>locale</code>.
175 * </p>
176 *
177 * @param key Identifier for the requested content
178 * @param locale Locale with which to localize retrieval,
179 * or <code>null</code> for the default Locale
180 * @return content for a specified key.
181 *
182 * @exception ResourcesException if an error occurs retrieving or
183 * returning the requested content
184 * @exception ResourcesKeyException if no value for the specified
185 * key was found, and <code>isReturnNull()</code> returns
186 * <code>false</code>
187 */
188 public Object getObject(String key, Locale locale);
189
190
191 /**
192 * <p>Return the content for the specified <code>key</code> as a
193 * Reader, localized based on the specified <code>locale</code>.
194 * </p>
195 *
196 * @param key Identifier for the requested content
197 * @param locale Locale with which to localize retrieval,
198 * or <code>null</code> for the default Locale
199 * @return content for a specified key.
200 *
201 * @exception ResourcesException if an error occurs retrieving or
202 * returning the requested content
203 * @exception ResourcesKeyException if no value for the specified
204 * key was found, and <code>isReturnNull()</code> returns
205 * <code>false</code>
206 */
207 public Reader getReader(String key, Locale locale);
208
209
210 /**
211 * <p>Return the content for the specified <code>key</code> as a
212 * String, localized based on the specified <code>locale</code>.
213 * </p>
214 *
215 * @param key Identifier for the requested content
216 * @param locale Locale with which to localize retrieval,
217 * or <code>null</code> for the default Locale
218 * @return content for a specified key.
219 *
220 * @exception ResourcesException if an error occurs retrieving or
221 * returning the requested content
222 * @exception ResourcesKeyException if no value for the specified
223 * key was found, and <code>isReturnNull()</code> returns
224 * <code>false</code>
225 */
226 public String getString(String key, Locale locale);
227
228
229 }
230
231