001/* java.beans.beancontext.BeanContextChild 002 Copyright (C) 1999 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038 039package java.beans.beancontext; 040 041import java.beans.PropertyChangeListener; 042import java.beans.PropertyVetoException; 043import java.beans.VetoableChangeListener; 044 045/** 046 * Beans implement this to get information about the execution environment and 047 * its services and to be placed in the hierarchy. 048 * <P> 049 * 050 * The difference between a <code>BeanContext</code> and a 051 * <code>BeanContextChild</code>, mainly, is that a 052 * <code>BeanContext</code> may be a parent. 053 * <P> 054 * 055 * <code>BeanContextChild</code> instances will be serialized at some 056 * point in their life, but you need to make sure your bean context does 057 * not contain a serializable reference (directly or indirectly) to the 058 * parent <code>BeanContext</code>, to any of the other 059 * <code>BeanContext</code>s in the tree, or to any resources obtained 060 * via the <code>BeanContextServices</code> interface. One way to do this 061 * is to mark any fields that contain such references as 062 * <code>transient</code>. Another way is to use a custom serializer. 063 * <P> 064 * 065 * If you do not do this, when the <code>BeanContext</code> is serialized, 066 * all the other <code>BeanContext</code>s and other unnecessary things 067 * will be serialized along with it. 068 * <P> 069 * 070 * Before dying, a <code>BeanContextChild</code> should call 071 * <code>getBeanContext().remove(this)</code> to detach from the 072 * hierarchy and exit cleanly. 073 * 074 * @author John Keiser 075 * @since JDK1.2 076 * @see java.beans.beancontext.BeanContext 077 */ 078 079public interface BeanContextChild { 080 /** 081 * Set the parent <code>BeanContext</code>. 082 * <P> 083 * 084 * This method is called from <code>BeanContext.add()</code> and 085 * should not be called directly. 086 * <P> 087 * 088 * When this Object is being added to a new BeanContext or moved 089 * from an old one, a non-null value will be passed in. 090 * <P> 091 * 092 * When this Object is being removed from the current 093 * <code>BeanContext</code>, <code>setBeanContext()</code> will 094 * receive the parameter <code>null</code>. 095 * <P> 096 * 097 * When being removed from the current <code>BeanContext</code>, 098 * it is the <code>BeanContextChild</code>'s responsibility to 099 * release all services it has obtained. 100 * <P> 101 * 102 * This change should generate <code>PropertyChangeEvent</code> 103 * and <code>VetoableChangeEvent</code>s with the property name 104 * "beanContext". If the change is vetoed, it must re-throw the 105 * exception and not change anything. In this way, the parent 106 * <code>BeanContextChild</code>, who has registered himself with 107 * you, will have a chance to remove this child from its 108 * collection. 109 * <P> 110 * 111 * If the Bean does not wish to change the parent or be removed 112 * from one, it may throw the <code>PropertyVetoException</code>. 113 * If you veto a <code>setBeanContext(null)</code> call, then you 114 * should try your hardest to remedy whatever problem is keeping 115 * you from being removed from the <code>BeanContext</code> so 116 * that you can <em>not</em> veto it the next time. 117 * Otherwise, nasty pathological recursion stuff could occur in 118 * certain situations. 119 * <P> 120 * 121 * If you do veto the change, you must first back out any changes 122 * you made prior to the veto. Best not to make any such changes 123 * prior to the veto in the first place. 124 * <P> 125 * 126 * This method is called from <code>BeanContext.add()</code> and 127 * should not be called directly. 128 * 129 * @param parent the new parent for the <code>BeanContextChild</code>, 130 * or <code>null</code> to signify removal from a tree. 131 * @exception PropertyVetoException if the 132 * <code>BeanContextChild</code> implementor does not 133 * wish to have its parent changed. 134 */ 135 void setBeanContext(BeanContext parent) 136 throws PropertyVetoException; 137 138 /** 139 * Get the parent <code>BeanContext</code>. 140 * @return the parent <code>BeanContext</code>. 141 */ 142 BeanContext getBeanContext(); 143 144 /** 145 * Add a listener that will be notified when a specific property changes. 146 * @param prop the name of the property to listen on 147 * @param listener the listener to listen on the property. 148 */ 149 void addPropertyChangeListener(String prop, PropertyChangeListener listener); 150 151 /** 152 * Remove a listener to a certain property. 153 * @param prop the name of the property being listened on 154 * @param listener the listener listening on the property. 155 */ 156 void removePropertyChangeListener(String prop, PropertyChangeListener listener); 157 158 /** 159 * Add a listener that will be notified when a specific property 160 * change is requested (a PropertyVetoException may be thrown) as 161 * well as after the change is successfully made. 162 * 163 * @param prop the name of the property to listen on 164 * @param listener the listener to listen on the property. 165 */ 166 void addVetoableChangeListener(String prop, VetoableChangeListener listener); 167 168 /** 169 * Remove a listener to a certain property. 170 * @param prop the name of the property being listened on 171 * @param listener the listener listening on the property. 172 */ 173 void removeVetoableChangeListener(String prop, VetoableChangeListener listener); 174}