1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.resources.impl;
19
20 import java.util.HashMap;
21 import java.util.Iterator;
22 import java.util.Map;
23
24 import org.apache.commons.resources.Resources;
25 import org.apache.commons.resources.ResourcesException;
26 import org.apache.commons.resources.ResourcesFactory;
27
28 /**
29 * <p>Convenience base class for {@link ResourcesFactory} implementations.
30 * This implementation caches the {@link Resources} instances returned by
31 * a protected <code>createResources()</code> method, which must be implemented
32 * by concrete subclasses.</p>
33 *
34 * @see org.apache.commons.resources.impl.JDBCResourcesFactory
35 * @see org.apache.commons.resources.impl.PropertyResourcesFactory
36 * @see org.apache.commons.resources.impl.ResourceBundleResourcesFactory
37 * @see org.apache.commons.resources.impl.WebappResourcesFactoryBase
38 * @see org.apache.commons.resources.impl.WebappPropertyResourcesFactory
39 * @see org.apache.commons.resources.impl.WebappXMLResourcesFactory
40 * @see org.apache.commons.resources.impl.XMLResourcesFactory
41 */
42 public abstract class ResourcesFactoryBase implements ResourcesFactory {
43
44
45 // ----------------------------------------------------- Instance Variables
46
47
48 /**
49 * <p>The set of {@link Resources} instances previously created by
50 * this {@link ResourcesFactory}, keyed by logical name.</p>
51 */
52 private Map resources = new HashMap();
53
54
55 /**
56 * <p>The <code>returnNull</code> property value that will be configured
57 * on {@link Resources} instances created by this factory.</p>
58 */
59 private boolean returnNull = true;
60
61
62 // ------------------------------------------------------------- Properties
63
64
65 /**
66 * <p>Return the <code>returnNull</code> property value that will be
67 * configured on {@link Resources} instances created by this factory.</p>
68 * @return 'true' if null is returned for invalid key values.
69 */
70 public boolean isReturnNull() {
71
72 return (this.returnNull);
73
74 }
75
76
77 /**
78 * <p>Set the <code>returnNull</code> property value that will be
79 * configured on {@link Resources} instances created by this factory.</p>
80 *
81 * @param returnNull The new value to delegate
82 */
83 public void setReturnNull(boolean returnNull) {
84
85 this.returnNull = returnNull;
86
87 }
88
89
90 // --------------------------------------------------------- Public Methods
91
92
93 /**
94 * <p>Create (if necessary) and return a {@link Resources} instance
95 * for the specified logical name, with a default configuration.
96 * The default implementation of this method treats the name as the
97 * configuration String as well, and calls the
98 * <code>getResources(String,String)</code> method.
99 *
100 * @param name Logical name of the {@link Resources} instance to
101 * be returned
102 * @return The resources instance.
103 *
104 * @exception ResourcesException if a {@link Resources} instance
105 * of the specified logical name cannot be returned.
106 */
107 public Resources getResources(String name) {
108
109 return (getResources(name, name));
110
111 }
112
113
114 /**
115 * <p>Create (if necessary) and return a {@link Resources} instance
116 * for the specified logical name, with a configuration based on
117 * the specified configuration String.</p>
118 *
119 * @param name Logical name of the {@link Resources} instance to
120 * be returned
121 * @param config Configuration string for this resource (meaning
122 * is dependent upon the {@link ResourcesFactory} implementation
123 * being utilized), or <code>null</code> for the default
124 * configuration
125 * @return The resources instance.
126 *
127 * @exception ResourcesException if a {@link Resources} instance
128 * of the specified logical name cannot be returned.
129 */
130 public Resources getResources(String name, String config) {
131
132 synchronized (resources) {
133 Resources instance = (Resources) resources.get(name);
134 if (instance == null) {
135 instance = createResources(name, config);
136 resources.put(name, instance);
137 }
138 return (instance);
139 }
140
141 }
142
143
144 /**
145 * <p>Release any internal references to {@link Resources} instances
146 * that have been returned previously, after calling the
147 * <code>destroy()</code> method on each such instance.</p>
148 *
149 * @exception ResourcesException if a problem occurred while releasing
150 */
151 public void release() {
152
153 synchronized (resources) {
154 Iterator names = resources.keySet().iterator();
155 while (names.hasNext()) {
156 String name = (String) names.next();
157 ((Resources) resources.get(name)).destroy();
158 }
159 resources.clear();
160 }
161
162 }
163
164
165
166 // ------------------------------------------------------ Protected Methods
167
168
169 /**
170 * <p>Create and return a new {@link Resources} instance with the
171 * specified logical name, after calling its <code>init()</code>
172 * method and delegating the relevant properties. Concrete
173 * subclasses <strong>MUST</strong> implement this method.</p>
174 *
175 * @param name Logical name of the {@link Resources} instance to create
176 * @param config Configuration string for this resource (if any)
177 * @return The new Resources instance.
178 *
179 * @exception ResourcesException if a {@link Resources} instance
180 * of the specified logical name cannot be created.
181 */
182 protected abstract Resources createResources(String name, String config);
183
184
185 }