1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.resources;
17
18 import java.util.Locale;
19 import java.util.MissingResourceException;
20
21 /**
22 * <p>
23 * Definition of an interface for accessing resources in a generic way.
24 * </p>
25 * <p>
26 * Through this interface applications can access a resource manager object that
27 * is able to provide access to resource items or whole resource groups. This
28 * service is completely independent on the way the resources of this
29 * application are stored. The physical resource access is performed by a
30 * <code>ResourceLoader</code> object that is associated with this class.
31 * </p>
32 * <p>
33 * Resources supported by this library are always organized in logical resource
34 * groups. This allows for a logic structure. When resources are accessed a
35 * group name must always be provided.
36 * </p>
37 * <p>
38 * This interface defines all needed methods for accessing resources. A single
39 * item can be retrieved as object or, for convenience purpose, as string. It is
40 * also possible to retrieve a whole resource group.
41 * </p>
42 *
43 * @see ResourceGroup
44 * @see ResourceLoader
45 *
46 * @author Oliver Heger
47 * @version $Id: ResourceManager.java 205 2012-01-29 18:29:57Z oheger $
48 */
49 public interface ResourceManager
50 {
51 /**
52 * Returns the resource for the given <code>Locale</code>, resource
53 * group, and key.
54 *
55 * @param locale the <code>Locale</code>
56 * @param group the name of the resource group the resource belongs to
57 * @param key the resource key
58 * @return the specified resource
59 * @throws MissingResourceException if the resource cannot be found
60 */
61 Object getResource(Locale locale, Object group, Object key)
62 throws MissingResourceException;
63
64 /**
65 * Returns the text resource for the given combination of a
66 * <code>Locale</code>, resource group, and resource key. This is a
67 * convenience method if the resource is known to be a text resource.
68 *
69 * @param locale the <code>Locale</code>
70 * @param group the name of the resource group the resource belongs to
71 * @param key the resource key
72 * @return the specified resource
73 * @throws MissingResourceException if the resource cannot be found
74 */
75 String getText(Locale locale, Object group, Object key)
76 throws MissingResourceException;
77
78 /**
79 * Returns the <code>ResourceLoader</code> that is associated with this
80 * resource manager.
81 *
82 * @return the associated <code>ResourceLoader</code>
83 */
84 ResourceLoader getResourceLoader();
85
86 /**
87 * Sets the <code>ResourceLoader</code> for this resource manager. This
88 * loader is then used to retrieve resource groups.
89 *
90 * @param resourceLoader the <code>ResourceLoader</code> to be used
91 */
92 void setResourceLoader(ResourceLoader resourceLoader);
93
94 /**
95 * Returns the resource group for the specified <code>Locale</code> with
96 * the given name. The returned object can be used to retrieve all resources
97 * that belong to this group at once.
98 *
99 * @param locale the <code>Locale</code>
100 * @param group the name of the resource group
101 * @return the found resource group
102 * @throws MissingResourceException if the resource group cannot be found
103 */
104 ResourceGroup getResourceGroup(Locale locale, Object group)
105 throws MissingResourceException;
106
107 /**
108 * Returns the name of the default resource group.
109 *
110 * @return the default resource group's name
111 */
112 Object getDefaultResourceGroup();
113
114 /**
115 * Sets the name of the default resource group. If a resource is queried
116 * with an undefined group name, this default group will be used.
117 *
118 * @param grp the name of the default resource group
119 */
120 void setDefaultResourceGroup(Object grp);
121 }