001 /*
002 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.beans.beancontext;
027
028 import java.beans.PropertyChangeListener;
029 import java.beans.VetoableChangeListener;
030 import java.beans.PropertyVetoException;
031
032 import java.beans.beancontext.BeanContext;
033
034 /**
035 * <p>
036 * JavaBeans wishing to be nested within, and obtain a reference to their
037 * execution environment, or context, as defined by the BeanContext
038 * sub-interface shall implement this interface.
039 * </p>
040 * <p>
041 * Conformant BeanContexts shall as a side effect of adding a BeanContextChild
042 * object shall pass a reference to itself via the setBeanContext() method of
043 * this interface.
044 * </p>
045 * <p>
046 * Note that a BeanContextChild may refuse a change in state by throwing
047 * PropertyVetoedException in response.
048 * </p>
049 * <p>
050 * In order for persistence mechanisms to function properly on BeanContextChild
051 * instances across a broad variety of scenarios, implementing classes of this
052 * interface are required to define as transient, any or all fields, or
053 * instance variables, that may contain, or represent, references to the
054 * nesting BeanContext instance or other resources obtained
055 * from the BeanContext via any unspecified mechanisms.
056 * </p>
057 *
058 * @author Laurence P. G. Cable
059 * @version 1.28, 05/05/07
060 * @since 1.2
061 *
062 * @see java.beans.beancontext.BeanContext
063 * @see java.beans.PropertyChangeEvent
064 * @see java.beans.PropertyChangeListener
065 * @see java.beans.PropertyVetoException
066 * @see java.beans.VetoableChangeListener
067 */
068
069 public interface BeanContextChild {
070
071 /**
072 * <p>
073 * Objects that implement this interface,
074 * shall fire a java.beans.PropertyChangeEvent, with parameters:
075 *
076 * propertyName "beanContext", oldValue (the previous nesting
077 * <code>BeanContext</code> instance, or <code>null</code>),
078 * newValue (the current nesting
079 * <code>BeanContext</code> instance, or <code>null</code>).
080 * <p>
081 * A change in the value of the nesting BeanContext property of this
082 * BeanContextChild may be vetoed by throwing the appropriate exception.
083 * </p>
084 * @param bc The <code>BeanContext</code> with which
085 * to associate this <code>BeanContextChild</code>.
086 * @throws <code>PropertyVetoException</code> if the
087 * addition of the specified <code>BeanContext</code> is refused.
088 */
089 void setBeanContext(BeanContext bc) throws PropertyVetoException;
090
091 /**
092 * Gets the <code>BeanContext</code> associated
093 * with this <code>BeanContextChild</code>.
094 * @return the <code>BeanContext</code> associated
095 * with this <code>BeanContextChild</code>.
096 */
097 BeanContext getBeanContext();
098
099 /**
100 * Adds a <code>PropertyChangeListener</code>
101 * to this <code>BeanContextChild</code>
102 * in order to receive a <code>PropertyChangeEvent</code>
103 * whenever the specified property has changed.
104 * @param name the name of the property to listen on
105 * @param pcl the <code>PropertyChangeListener</code> to add
106 */
107 void addPropertyChangeListener(String name,
108 PropertyChangeListener pcl);
109
110 /**
111 * Removes a <code>PropertyChangeListener</code> from this
112 * <code>BeanContextChild</code> so that it no longer
113 * receives <code>PropertyChangeEvents</code> when the
114 * specified property is changed.
115 *
116 * @param name the name of the property that was listened on
117 * @param pcl the <code>PropertyChangeListener</code> to remove
118 */
119 void removePropertyChangeListener(String name,
120 PropertyChangeListener pcl);
121
122 /**
123 * Adds a <code>VetoableChangeListener</code> to
124 * this <code>BeanContextChild</code>
125 * to receive events whenever the specified property changes.
126 * @param name the name of the property to listen on
127 * @param vcl the <code>VetoableChangeListener</code> to add
128 */
129 void addVetoableChangeListener(String name,
130 VetoableChangeListener vcl);
131
132 /**
133 * Removes a <code>VetoableChangeListener</code> from this
134 * <code>BeanContextChild</code> so that it no longer receives
135 * events when the specified property changes.
136 * @param name the name of the property that was listened on.
137 * @param vcl the <code>VetoableChangeListener</code> to remove.
138 */
139 void removeVetoableChangeListener(String name,
140 VetoableChangeListener vcl);
141
142 }
|