| Frames | No Frames |
1: /* java.beans.beancontext.BeanContext 2: Copyright (C) 1999 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.beans.beancontext; 40: 41: import java.beans.DesignMode; 42: import java.beans.Visibility; 43: import java.io.IOException; 44: import java.io.InputStream; 45: import java.net.URL; 46: import java.util.Collection; 47: 48: /** 49: * Acts as a container for sub-beans and as a sub-bean, 50: * so that an entire hierarchy of beans can be made up of 51: * <code>BeanContext</code>s. 52: * <P> 53: * 54: * Since I can't sprinkle the <code>Collections</code> interface 55: * documentation with special information for <code>BeanContext</code> 56: * implementors, I'll have to document special requirements for 57: * implementors of those functions here. 58: * <P> 59: * 60: * <code><strong>add()</strong></code> or <code>addAll()</code>: 61: * <br> 62: * <OL> 63: * <LI> 64: * May add any <code>Object</code> into the hierarchy as well as a 65: * <code>BeanContextChild</code>, <code>BeanContext</code> or 66: * <code>BeanContextProxy</code> object. 67: * This way, any Bean can be in the hierarchy. 68: * </LI> 69: * <LI> 70: * Must synchronize on <code>BeanContext.globalHierarchyLock</code>. 71: * </LI> 72: * <LI> 73: * Don't add the <code>Object</code> if it's already there (only once 74: * per <code>BeanContext</code>). 75: * </LI> 76: * <LI> 77: * If it is a <code>BeanContextChild</code> implementor, call 78: * <code>setBeanContext()</code> on it. If it's a 79: * <code>BeanContextProxy</code> implementor, call 80: * <code>getBeanContextProxy().setBeanContext()</code> on it. 81: * If <code>setBeanContext()</code> vetoes the change, back out 82: * all changes so far and throw <code>IllegalStateException</code>. 83: * </LI> 84: * <LI> 85: * If it (or its proxy) implements <code>Visibility</code>, call 86: * <code>dontUseGui()</code> or <code>okToUseGui()</code> on it, 87: * depending on whether you (the <code>BeanContext</code>) feel like 88: * allowing it to use the GUI or not. 89: * </LI> 90: * <LI> 91: * If it implements <code>BeanContextChild</code> or 92: * <code>BeanContextProxy</code>, register yourself (the 93: * <code>BeanContext</code>) as both a 94: * <code>PropertyChangeListener</code> and 95: * <code>VetoableChangeListener</code> on the "beanContext" 96: * property (it may also add itself on any other properties it wishes 97: * to). 98: * </LI> 99: * <LI> 100: * If it is a listener or event source that you (the 101: * <code>BeanContext</code>) are interested in, you may register 102: * yourself to it or register it to you. 103: * </LI> 104: * <LI> 105: * Fire a <code>java.beans.beancontext.BeanContextMembershipEvent</code> 106: * before exiting. <code>addAll()</code> should wait until everything 107: * is done changing before firing the event (or events) so that if a 108: * failure occurs, the backing-out process can proceed without any 109: * events being fired at all. 110: * </LI> 111: * </OL> 112: * <P> 113: * 114: * <code><strong>remove()</strong></code> or <code>removeAll()</code>: 115: * <br> 116: * <OL> 117: * <LI> 118: * Must synchronize on <code>BeanContext.globalHierarchyLock</code>. 119: * </LI> 120: * <LI> 121: * If the specified <code>Object</code> is not a child of this 122: * <code>BeanContext</code>, just exit without performing any actions. 123: * </LI> 124: * <LI> 125: * Remove the <code>Object</code> from your collection of children. 126: * </LI> 127: * <LI> 128: * If it is a <code>BeanContextChild</code> implementor, call 129: * <code>setBeanContext(null)</code> on it. If it's a 130: * <code>BeanContextProxy</code> implementor, call 131: * <code>getBeanContextProxy().setBeanContext(null)</code> on it. 132: * If <code>setBeanContext()</code> vetoes the change, back out 133: * all changes so far and throw <code>IllegalStateException</code>. 134: * </LI> 135: * <LI> 136: * If you registered the <code>Object</code> to listen to you or 137: * registered yourself as a listener on the <code>Object</code> during 138: * <code>add()</code> or <code>addAll()</code>, undo the registration 139: * bycalling the appropriate <code>removeListener()</code> method. 140: * </LI> 141: * <LI> 142: * Fire a <code>java.beans.beancontext.BeanContextMembershipEvent</code> 143: * before exiting. <code>removeAll()</code> should wait until 144: * everything is done changing before firing the event (or events) so 145: * that if a failure occurs, the backing-out process can proceed 146: * without any events being fired at all. 147: * </LI> 148: * </OL> 149: * <P> 150: * 151: * <code>addAll()</code>, <code>removeAll()</code>, 152: * <code>retainAll()</code> and <code>clear()</code> do not need to be 153: * implemented, but may be if so desired. 154: * <P> 155: * 156: * Similarly, <code>Visibility</code> and <code>DesignMode</code> methods 157: * should propagate changed values to children that implement interfaces 158: * of the same name. 159: * <P> 160: * 161: * A hierarchy of beans is mainly useful so that different sets of beans 162: * can be established, each with their own set of resources. 163: * 164: * @author John Keiser 165: * @since JDK1.2 166: */ 167: 168: public interface BeanContext 169: extends Collection, BeanContextChild, Visibility, DesignMode { 170: 171: /** 172: * The global lock on changing any BeanContext hierarchy. 173: * It kinda sucks that there is only one lock, since there can be 174: * multiple hierarchies. Oh well, I didn't design, I just code. 175: * <P> 176: * 177: * Methods that must (or do) synchronize on the global lock: 178: * <BR> 179: * <UL> 180: * <LI> 181: * Implementors of <CODE>BeanContext.add()</CODE> and <code>addAll()</code> 182: * </LI> 183: * </UL> 184: * @fixme fill in the rest of the methods which use the global lock. 185: */ 186: Object globalHierarchyLock = new Object(); 187: 188: /** 189: * Instantiate a Bean using this Bean's <code>ClassLoader</code> 190: * and this <code>BeanContext</code> as the parent. 191: * <P> 192: * 193: * This method exists mainly so that <code>BeanContext</code> 194: * implementations can perform extra actions on Beans that are 195: * created within them. 196: * 197: * @param beanName the name of the bean to instantiate 198: * @return the created Bean 199: * 200: * @see java.beans.Beans#instantiate(java.lang.ClassLoader,java.lang.String) 201: * @see java.beans.Beans#instantiate(java.lang.ClassLoader,java.lang.String,java.beans.beancontext.BeanContext) 202: * @exception IOException if there is an I/O problem during 203: * instantiation. 204: * @exception ClassNotFoundException if a serialized Bean's class 205: * is not found. 206: */ 207: Object instantiateChild(String beanName) 208: throws IOException, 209: ClassNotFoundException; 210: 211: /** 212: * Get a resource. The <code>BeanContext</code> will typically 213: * call <code>ClassLoader.getResource()</code>, but may do it any 214: * way it wants to. This allows a <code>BeanContext</code> to 215: * have its own set of resources separate from the rest of the 216: * system. 217: * <P> 218: * 219: * Beans should call this method on their parent rather than the 220: * associated <code>ClassLoader</code> method. 221: * <P> 222: * 223: * I am assuming, but am not entirely sure, that if a 224: * <code>BeanContext</code> cannot find a resource, its 225: * responsibility is to call the <code>getResource</code> method 226: * of its parent <code>BeanContext</code>. 227: * 228: * @return a URL to the requested resource. 229: * @param resourceName the name of the resource requested. 230: * @param requestor a reference to the child requesting the resource. 231: * @see java.lang.ClassLoader#getResource(java.lang.String) 232: */ 233: URL getResource(String resourceName, BeanContextChild requestor); 234: 235: /** 236: * Get a resource as a stream. The <code>BeanContext</code> will 237: * typically call <code>ClassLoader.getResourceAsStream()</code>, 238: * but may do it any way it wants to. This allows a 239: * <code>BeanContext</code>'s children to have their own set of 240: * resources separate from the rest of the system. 241: * <P> 242: * 243: * Beans should call this method on their parent rather than the 244: * associated <code>ClassLoader</code> method. 245: * <P> 246: * 247: * I am assuming, but am not entirely sure, that if a 248: * <code>BeanContext</code> cannot find a resource, its 249: * responsibility is to call the <code>getResourceAsStream</code> 250: * method of its parent <code>BeanContext</code>. 251: * 252: * @return the requested resource as a stream. 253: * @param resourceName the name of the resource requested. 254: * @param requestor a reference to the child requesting the resource. 255: * @see java.lang.ClassLoader#getResourceAsStream(java.lang.String) 256: */ 257: InputStream getResourceAsStream(String resourceName, BeanContextChild requestor); 258: 259: /** 260: * Add a listener on changes to the membership of this 261: * <code>BeanContext</code> object. 262: * @param listener the listener to add. 263: */ 264: void addBeanContextMembershipListener(BeanContextMembershipListener listener); 265: 266: /** 267: * Remove a listener on changes to the membership of this 268: * <code>BeanContext</code> object. 269: * @param listener the listener to remove. 270: */ 271: void removeBeanContextMembershipListener(BeanContextMembershipListener listener); 272: }