View Javadoc

1   /*
2    * $Id: ResourcesFactoryBase.java 349025 2005-11-25 21:09:54Z niallp $
3    * $Revision: 349025 $
4    * $Date: 2005-11-25 21:09:54 +0000 (Fri, 25 Nov 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.impl;
25  
26  import java.util.HashMap;
27  import java.util.Iterator;
28  import java.util.Map;
29  
30  import org.apache.commons.resources.Resources;
31  import org.apache.commons.resources.ResourcesException;
32  import org.apache.commons.resources.ResourcesFactory;
33  
34  /**
35   * <p>Convenience base class for {@link ResourcesFactory} implementations.
36   * This implementation caches the {@link Resources} instances returned by
37   * a protected <code>createResources()</code> method, which must be implemented
38   * by concrete subclasses.</p>
39   *
40   * @see org.apache.commons.resources.impl.JDBCResourcesFactory
41   * @see org.apache.commons.resources.impl.PropertyResourcesFactory
42   * @see org.apache.commons.resources.impl.ResourceBundleResourcesFactory
43   * @see org.apache.commons.resources.impl.WebappResourcesFactoryBase
44   * @see org.apache.commons.resources.impl.WebappPropertyResourcesFactory
45   * @see org.apache.commons.resources.impl.WebappXMLResourcesFactory
46   * @see org.apache.commons.resources.impl.XMLResourcesFactory
47   */
48  public abstract class ResourcesFactoryBase implements ResourcesFactory {
49      
50  
51      // ----------------------------------------------------- Instance Variables
52  
53  
54      /**
55       * <p>The set of {@link Resources} instances previously created by
56       * this {@link ResourcesFactory}, keyed by logical name.</p>
57       */
58      private Map resources = new HashMap();
59  
60  
61      /**
62       * <p>The <code>returnNull</code> property value that will be configured
63       * on {@link Resources} instances created by this factory.</p>
64       */
65      private boolean returnNull = true;
66  
67  
68      // ------------------------------------------------------------- Properties
69  
70  
71      /**
72       * <p>Return the <code>returnNull</code> property value that will be
73       * configured on {@link Resources} instances created by this factory.</p>
74       * @return 'true' if null is returned for invalid key values.
75       */
76      public boolean isReturnNull() {
77  
78          return (this.returnNull);
79  
80      }
81  
82  
83      /**
84       * <p>Set the <code>returnNull</code> property value that will be
85       * configured on {@link Resources} instances created by this factory.</p>
86       *
87       * @param returnNull The new value to delegate
88       */
89      public void setReturnNull(boolean returnNull) {
90  
91          this.returnNull = returnNull;
92  
93      }
94  
95  
96      // --------------------------------------------------------- Public Methods
97  
98  
99      /**
100      * <p>Create (if necessary) and return a {@link Resources} instance
101      * for the specified logical name, with a default configuration.
102      * The default implementation of this method treats the name as the
103      * configuration String as well, and calls the
104      * <code>getResources(String,String)</code> method.
105      *
106      * @param name Logical name of the {@link Resources} instance to
107      *  be returned
108      * @return The resources instance.
109      *
110      * @exception ResourcesException if a {@link Resources} instance
111      *  of the specified logical name cannot be returned.
112      */
113     public Resources getResources(String name) {
114 
115         return (getResources(name, name));
116 
117     }
118 
119 
120     /**
121      * <p>Create (if necessary) and return a {@link Resources} instance
122      * for the specified logical name, with a configuration based on
123      * the specified configuration String.</p>
124      *
125      * @param name Logical name of the {@link Resources} instance to
126      *  be returned
127      * @param config Configuration string for this resource (meaning
128      *  is dependent upon the {@link ResourcesFactory} implementation
129      *  being utilized), or <code>null</code> for the default
130      *  configuration
131      * @return The resources instance.
132      *
133      * @exception ResourcesException if a {@link Resources} instance
134      *  of the specified logical name cannot be returned.
135      */
136     public Resources getResources(String name, String config) {
137 
138         synchronized (resources) {
139             Resources instance = (Resources) resources.get(name);
140             if (instance == null) {
141                 instance = createResources(name, config);
142                 resources.put(name, instance);
143             }
144             return (instance);
145         }
146 
147     }
148 
149 
150     /**
151      * <p>Release any internal references to {@link Resources} instances
152      * that have been returned previously, after calling the
153      * <code>destroy()</code> method on each such instance.</p>
154      *
155      * @exception ResourcesException if a problem occurred while releasing
156      */
157     public void release() {
158 
159         synchronized (resources) {
160             Iterator names = resources.keySet().iterator();
161             while (names.hasNext()) {
162                 String name = (String) names.next();
163                 ((Resources) resources.get(name)).destroy();
164             }
165             resources.clear();
166         }
167 
168     }
169 
170 
171 
172     // ------------------------------------------------------ Protected Methods
173 
174 
175     /**
176      * <p>Create and return a new {@link Resources} instance with the
177      * specified logical name, after calling its <code>init()</code>
178      * method and delegating the relevant properties.  Concrete
179      * subclasses <strong>MUST</strong> implement this method.</p>
180      *
181      * @param name Logical name of the {@link Resources} instance to create
182      * @param config Configuration string for this resource (if any)
183      * @return The new Resources instance.
184      *
185      * @exception ResourcesException if a {@link Resources} instance
186      *  of the specified logical name cannot be created.
187      */
188     protected abstract Resources createResources(String name, String config);
189 
190 
191 }