Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
ResourcesFactory |
|
| 1.0;1 |
1 | /* | |
2 | * $Id: ResourcesFactory.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; | |
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 | } |