001 /* java.beans.beancontext.BeanContextChild 002 Copyright (C) 1999 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package java.beans.beancontext; 040 041 import java.beans.PropertyChangeListener; 042 import java.beans.PropertyVetoException; 043 import 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 079 public 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 }