001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.resources;
019
020 import java.io.Serializable;
021
022 /**
023 * <p>A {@link org.apache.commons.resources.ResourcesFactory}
024 * is a factory pattern interface for a
025 * class that can create {@link org.apache.commons.resources.Resources}
026 * instances based on a logical
027 * name that is passed to the factory. Repeated requests to return a
028 * {@link org.apache.commons.resources.Resources} instance with the same
029 * name should return the same
030 * {@link org.apache.commons.resources.Resources} instance each time.</p>
031 *
032 * <p>Implementations of {@link org.apache.commons.resources.ResourcesFactory}
033 * <strong>MUST</strong>
034 * include a zero-arguments constructor so that instances of the factory
035 * can be dynamically created. Therefore, configuration information
036 * above and beyond the configuration String will generally be specified
037 * via JavaBeans property setters on the
038 * {@link org.apache.commons.resources.ResourcesFactory}
039 * implementation class.</p>
040 *
041 * @see org.apache.commons.resources.impl.ResourcesFactoryBase
042 * @see org.apache.commons.resources.impl.JDBCResourcesFactory
043 * @see org.apache.commons.resources.impl.PropertyResourcesFactory
044 * @see org.apache.commons.resources.impl.ResourceBundleResourcesFactory
045 * @see org.apache.commons.resources.impl.WebappResourcesFactoryBase
046 * @see org.apache.commons.resources.impl.WebappPropertyResourcesFactory
047 * @see org.apache.commons.resources.impl.WebappXMLResourcesFactory
048 * @see org.apache.commons.resources.impl.XMLResourcesFactory
049 */
050 public interface ResourcesFactory extends Serializable {
051
052
053 // ------------------------------------------------------------- Properties
054
055
056 /**
057 * <p>Return the <code>returnNull</code> property value that will be
058 * configured on {@link org.apache.commons.resources.Resources}
059 * instances created by this factory.</p>
060 * @return 'true' if null is returned for invalid key values.
061 */
062 public boolean isReturnNull();
063
064
065 /**
066 * <p>Set the <code>returnNull</code> property value that will be configured on
067 * {@link org.apache.commons.resources.Resources} instances created by this
068 * factory.</p>
069 *
070 * @param returnNull The new value to delegate
071 */
072 public void setReturnNull(boolean returnNull);
073
074
075 // --------------------------------------------------------- Public Methods
076
077
078 /**
079 * <p>Create (if necessary) and return a
080 * {@link org.apache.commons.resources.Resources} instance
081 * for the specified logical name, with a default configuration.</p>
082 *
083 * @param name Logical name of the
084 * {@link org.apache.commons.resources.Resources} instance to
085 * be returned
086 * @return The resources instance.
087 *
088 * @exception ResourcesException if a
089 * {@link org.apache.commons.resources.Resources} instance
090 * of the specified logical name cannot be returned.
091 */
092 public Resources getResources(String name);
093
094
095 /**
096 * <p>Create (if necessary) and return a
097 * {@link org.apache.commons.resources.Resources} instance
098 * for the specified logical name, with a configuration based on
099 * the specified configuration String.</p>
100 *
101 * @param name Logical name of the
102 * {@link org.apache.commons.resources.Resources} instance to be returned
103 * @param config Configuration string for this resource (meaning
104 * is dependent upon the {@link org.apache.commons.resources.ResourcesFactory}
105 * implementation being utilized), or <code>null</code> for the default
106 * configuration
107 * @return The resources.
108 *
109 * @exception ResourcesException if a
110 * {@link org.apache.commons.resources.Resources} instance
111 * of the specified logical name cannot be returned.
112 */
113 public Resources getResources(String name, String config);
114
115
116 /**
117 * <p>Release any internal references to
118 * {@link org.apache.commons.resources.Resources} instances
119 * that have been returned previously, after calling the
120 * <code>destroy()</code> method of each such instance.</p>
121 *
122 * @exception ResourcesException if an error occurs while releasing
123 */
124 public void release();
125
126
127 }