001 /* 002 * $Id: ResourcesFactory.java 349025 2005-11-25 21:09:54Z niallp $ 003 * $Revision: 349025 $ 004 * $Date: 2005-11-25 21:09:54 +0000 (Fri, 25 Nov 2005) $ 005 * 006 * ==================================================================== 007 * 008 * Copyright 2003-2005 The Apache Software Foundation 009 * 010 * Licensed under the Apache License, Version 2.0 (the "License"); 011 * you may not use this file except in compliance with the License. 012 * You may obtain a copy of the License at 013 * 014 * http://www.apache.org/licenses/LICENSE-2.0 015 * 016 * Unless required by applicable law or agreed to in writing, software 017 * distributed under the License is distributed on an "AS IS" BASIS, 018 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 019 * See the License for the specific language governing permissions and 020 * limitations under the License. 021 * 022 */ 023 024 package org.apache.commons.resources; 025 026 import java.io.Serializable; 027 028 /** 029 * <a>A {@link org.apache.commons.resources.ResourcesFactory} 030 * is a factory pattern interface for a 031 * class that can create {@link org.apache.commons.resources.Resources} 032 * instances based on a logical 033 * name that is passed to the factory. Repeated requests to return a 034 * {@link org.apache.commons.resources.Resources} instance with the same 035 * name should return the same 036 * {@link org.apache.commons.resources.Resources} instance each time.</p> 037 * 038 * <p>Implementations of {@link org.apache.commons.resources.ResourcesFactory} 039 * <strong>MUST</strong> 040 * include a zero-arguments constructor so that instances of the factory 041 * can be dynamically created. Therefore, configuration information 042 * above and beyond the configuration String will generally be specified 043 * via JavaBeans property setters on the 044 * {@link org.apache.commons.resources.ResourcesFactory} 045 * implementation class.</p> 046 * 047 * @see org.apache.commons.resources.impl.ResourcesFactoryBase 048 * @see org.apache.commons.resources.impl.JDBCResourcesFactory 049 * @see org.apache.commons.resources.impl.PropertyResourcesFactory 050 * @see org.apache.commons.resources.impl.ResourceBundleResourcesFactory 051 * @see org.apache.commons.resources.impl.WebappResourcesFactoryBase 052 * @see org.apache.commons.resources.impl.WebappPropertyResourcesFactory 053 * @see org.apache.commons.resources.impl.WebappXMLResourcesFactory 054 * @see org.apache.commons.resources.impl.XMLResourcesFactory 055 */ 056 public interface ResourcesFactory extends Serializable { 057 058 059 // ------------------------------------------------------------- Properties 060 061 062 /** 063 * <p>Return the <code>returnNull</code> property value that will be 064 * configured on {@link org.apache.commons.resources.Resources} 065 * instances created by this factory.</p> 066 * @return 'true' if null is returned for invalid key values. 067 */ 068 public boolean isReturnNull(); 069 070 071 /** 072 * <p>Set the <code>returnNull</code> property value that will be configured on 073 * {@link org.apache.commons.resources.Resources} instances created by this 074 * factory.</p> 075 * 076 * @param returnNull The new value to delegate 077 */ 078 public void setReturnNull(boolean returnNull); 079 080 081 // --------------------------------------------------------- Public Methods 082 083 084 /** 085 * <p>Create (if necessary) and return a 086 * {@link org.apache.commons.resources.Resources} instance 087 * for the specified logical name, with a default configuration.</p> 088 * 089 * @param name Logical name of the 090 * {@link org.apache.commons.resources.Resources} instance to 091 * be returned 092 * @return The resources instance. 093 * 094 * @exception ResourcesException if a 095 * {@link org.apache.commons.resources.Resources} instance 096 * of the specified logical name cannot be returned. 097 */ 098 public Resources getResources(String name); 099 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 }