View Javadoc

1   /*
2    * $Id: ResourcesFactory.java 349025 2005-11-25 21:09:54Z niallp $
3    * $Revision: 349025 $
4    * $Date: 2005-11-25 16:09:54 -0500 (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;
25  
26  import java.io.Serializable;
27  
28  /***
29   * <a>A {@link org.apache.commons.resources.ResourcesFactory} 
30   * is a factory pattern interface for a
31   * class that can create {@link org.apache.commons.resources.Resources} 
32   * instances based on a logical
33   * name that is passed to the factory.  Repeated requests to return a
34   * {@link org.apache.commons.resources.Resources} instance with the same 
35   * name should return the same
36   * {@link org.apache.commons.resources.Resources} instance each time.</p>
37   *
38   * <p>Implementations of {@link org.apache.commons.resources.ResourcesFactory} 
39   * <strong>MUST</strong>
40   * include a zero-arguments constructor so that instances of the factory
41   * can be dynamically created.  Therefore, configuration information
42   * above and beyond the configuration String will generally be specified
43   * via JavaBeans property setters on the 
44   * {@link org.apache.commons.resources.ResourcesFactory}
45   * implementation class.</p>
46   *
47   * @see org.apache.commons.resources.impl.ResourcesFactoryBase
48   * @see org.apache.commons.resources.impl.JDBCResourcesFactory
49   * @see org.apache.commons.resources.impl.PropertyResourcesFactory
50   * @see org.apache.commons.resources.impl.ResourceBundleResourcesFactory
51   * @see org.apache.commons.resources.impl.WebappResourcesFactoryBase
52   * @see org.apache.commons.resources.impl.WebappPropertyResourcesFactory
53   * @see org.apache.commons.resources.impl.WebappXMLResourcesFactory
54   * @see org.apache.commons.resources.impl.XMLResourcesFactory
55   */
56  public interface ResourcesFactory extends Serializable {
57      
58  
59      // ------------------------------------------------------------- Properties
60  
61  
62      /***
63       * <p>Return the <code>returnNull</code> property value that will be
64       * configured on {@link org.apache.commons.resources.Resources} 
65       * instances created by this factory.</p>
66       * @return 'true' if null is returned for invalid key values.
67       */
68      public boolean isReturnNull();
69  
70  
71      /***
72       * <p>Set the <code>returnNull</code> property value that will be configured on 
73       * {@link org.apache.commons.resources.Resources} instances created by this 
74       * factory.</p>
75       *
76       * @param returnNull The new value to delegate
77       */
78      public void setReturnNull(boolean returnNull);
79  
80  
81      // --------------------------------------------------------- Public Methods
82  
83  
84      /***
85       * <p>Create (if necessary) and return a 
86       * {@link org.apache.commons.resources.Resources} instance
87       * for the specified logical name, with a default configuration.</p>
88       *
89       * @param name Logical name of the 
90       * {@link org.apache.commons.resources.Resources} instance to
91       *  be returned
92       * @return The resources instance.
93       *
94       * @exception ResourcesException if a 
95       * {@link org.apache.commons.resources.Resources} instance
96       *  of the specified logical name cannot be returned.
97       */
98      public Resources getResources(String name);
99  
100 
101     /***
102      * <p>Create (if necessary) and return a 
103      * {@link org.apache.commons.resources.Resources} instance
104      * for the specified logical name, with a configuration based on
105      * the specified configuration String.</p>
106      *
107      * @param name Logical name of the 
108      * {@link org.apache.commons.resources.Resources} instance to be returned
109      * @param config Configuration string for this resource (meaning
110      *  is dependent upon the {@link org.apache.commons.resources.ResourcesFactory} 
111      * implementation being utilized), or <code>null</code> for the default
112      *  configuration
113      * @return The resources.
114      *
115      * @exception ResourcesException if a 
116      * {@link org.apache.commons.resources.Resources} instance
117      *  of the specified logical name cannot be returned.
118      */
119     public Resources getResources(String name, String config);
120 
121 
122     /***
123      * <p>Release any internal references to 
124      * {@link org.apache.commons.resources.Resources} instances
125      * that have been returned previously, after calling the
126      * <code>destroy()</code> method of each such instance.</p>
127      *
128      * @exception ResourcesException if an error occurs while releasing
129      */
130     public void release();
131 
132 
133 }