Coverage Report

Coverage Report - org.apache.commons.resources.Resources

Classes in this File

 /*
  * $Id: Resources.java 354330 2005-12-06 06:05:19Z niallp $
  * $Revision: 354330 $
  * $Date: 2005-12-06 06:05:19 +0000 (Tue, 06 Dec 2005) $
  *
  * ====================================================================
  *
  *  Copyright 2003-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
  *  You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  *  Unless required by applicable law or agreed to in writing, software
  *  distributed under the License is distributed on an "AS IS" BASIS,
  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
  */
 
 package org.apache.commons.resources;
 
 import java.io.InputStream;
 import java.io.Reader;
 import java.io.Serializable;
 import java.util.Iterator;
 import java.util.Locale;
 
 /**
  * <p>An abstract representation of a set of internationalized resources,
  * which are arbitrary objects identified by a unique String <code>key</code>.
  * Localized versions of the resources (based on Locale parameter)
  * can be retrieved in a variety of formats.</p>
  *
  * <p>When presented with an invalid <code>key</code> value, resource
  * getter methods will behave differently based on the current value of
  * the <code>returnNull</code> property for this {@link Resources} instance.
  * If the property value is <code>true</code>, the getter method will return
  * <code>null</code> (which may be ambiguous if <code>null</code> is a valid
  * resource value).  If the property value is <code>false</code>, a
  * <code>ResourcesKeyException</code> will be thrown instead.</p>
  *
  * <p>Different implementations of the {@link Resources} interface support
  * a variety of mechanisms for acquiring the data content represented by
  * the keys.  Examples could include property files, XML files, databases, web
  * application resources, and other specialized approaches as desired.</p>
  *
  * <p>Different implementations of the {@link Resources} interface may apply
  * different semantics to the use of the <code>locale</code> 
  * attribute used to perform localization.  Consult
  * the documentation for the specific {@link Resources} implementation you
  * are using for the specific details of your implementation.</p>
  *
  * <p>Developers implementing {@link Resources} should extend the
  * {@link org.apache.commons.resources.impl.ResourcesBase} class,
  * and override the necessary methods,
  * to shield themselves from future changes that may occur in this interface.
  *
  * @see org.apache.commons.resources.impl.ResourcesBase
  * @see org.apache.commons.resources.impl.CollectionResourcesBase
  * @see org.apache.commons.resources.impl.JDBCResources
  * @see org.apache.commons.resources.impl.PropertyResources
  * @see org.apache.commons.resources.impl.ResourceBundleResources
  * @see org.apache.commons.resources.impl.WebappPropertyResources
  * @see org.apache.commons.resources.impl.WebappXMLResources
  * @see org.apache.commons.resources.impl.XMLResources
  */
 public interface Resources extends Serializable {
 
 
     // ------------------------------------------------------ Lifecycle Methods
 
 
     /**
      * <p>This must be called to initialize the data content of this
      * {@link Resources} instance, before any of the <code>getXxx()</code>
      * methods are called.</p>
      *
      * @exception ResourcesException if an error occurs during initialization
      */
     public void init();
 
 
     /**
      * <p>This method must be called when the manager of this resource
      * decides that it's no longer needed.  After this method is called,
      * no further calls to any of the <code>getXxx()</code> methods are
      * allowed.</p>
      *
      * @exception ResourcesException if an error occurs during finalization
      */
     public void destroy();
 
 
     // ------------------------------------------------------------- Properties
 
 
     /**
      * <p>Return an <code>Iterator</code> over the defined keys in this
      * {@link Resources} instance.</p>
      *
      * @return The keys contained in this resources instance.
      */
     public Iterator getKeys();
 
 
     /**
      * <p>Return the logical name of this {@link Resources} instance.</p>
      *
      * @return The name of this resources instance.
      */
     public String getName();
 
 
     /**
      * <p>Return <code>true</code> if resource getter methods will return
      * <code>null</code> instead of throwing an exception on invalid
      * key values.</p>
      * @return <code>true</code> if null is returned for invalid key values.
      */
     public boolean isReturnNull();
 
 
     /**
      * <p>Set a flag determining whether resource getter methods should
      * return <code>null</code> instead of throwing an exception on
      * invalid key values.</p>
      *
      * @param returnNull The new flag value
      */
     public void setReturnNull(boolean returnNull);
 
 
     // ---------------------------------------------- Content Retrieval Methods
 
 
     /**
      * <p>Return the content for the specified <code>key</code> as a
      * byte array, localized based on the specified <code>locale</code>.
      * </p>
      *
      * @param key Identifier for the requested content
      * @param locale Locale with which to localize retrieval,
      *  or <code>null</code> for the default Locale
      * @return content for a specified key.
      *
      * @exception ResourcesException if an error occurs retrieving or
      *  returning the requested content
      * @exception ResourcesKeyException if no value for the specified
      *  key was found, and <code>isReturnNull()</code> returns
      *  <code>false</code>
      */
     public byte[] getBytes(String key, Locale locale);
 
 
     /**
      * <p>Return the content for the specified <code>key</code> as an
      * InputStream, localized based on the specified <code>locale</code>.
      * </p>
      *
      * @param key Identifier for the requested content
      * @param locale Locale with which to localize retrieval,
      *  or <code>null</code> for the default Locale
      * @return content for a specified key.
      *
      * @exception ResourcesException if an error occurs retrieving or
      *  returning the requested content
      * @exception ResourcesKeyException if no value for the specified
      *  key was found, and <code>isReturnNull()</code> returns
      *  <code>false</code>
      */
     public InputStream getInputStream(String key, Locale locale);
 
 
     /**
      * <p>Return the content for the specified <code>key</code> as an
      * Object, localized based on the specified <code>locale</code>.
      * </p>
      *
      * @param key Identifier for the requested content
      * @param locale Locale with which to localize retrieval,
      *  or <code>null</code> for the default Locale
      * @return content for a specified key.
      *
      * @exception ResourcesException if an error occurs retrieving or
      *  returning the requested content
      * @exception ResourcesKeyException if no value for the specified
      *  key was found, and <code>isReturnNull()</code> returns
      *  <code>false</code>
      */
     public Object getObject(String key, Locale locale);
 
 
     /**
      * <p>Return the content for the specified <code>key</code> as a
      * Reader, localized based on the specified <code>locale</code>.
      * </p>
      *
      * @param key Identifier for the requested content
      * @param locale Locale with which to localize retrieval,
      *  or <code>null</code> for the default Locale
      * @return content for a specified key.
      *
      * @exception ResourcesException if an error occurs retrieving or
      *  returning the requested content
      * @exception ResourcesKeyException if no value for the specified
      *  key was found, and <code>isReturnNull()</code> returns
      *  <code>false</code>
      */
     public Reader getReader(String key, Locale locale);
 
 
     /**
      * <p>Return the content for the specified <code>key</code> as a
      * String, localized based on the specified <code>locale</code>.
      * </p>
      *
      * @param key Identifier for the requested content
      * @param locale Locale with which to localize retrieval,
      *  or <code>null</code> for the default Locale
      * @return content for a specified key.
      *
      * @exception ResourcesException if an error occurs retrieving or
      *  returning the requested content
      * @exception ResourcesKeyException if no value for the specified
      *  key was found, and <code>isReturnNull()</code> returns
      *  <code>false</code>
      */
     public String getString(String key, Locale locale);
 
 
 }
 
 

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