1 /*
2 * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.beans.beancontext;
27
28 import java.beans.PropertyChangeListener;
29 import java.beans.VetoableChangeListener;
30 import java.beans.PropertyVetoException;
31
32 import java.beans.beancontext.BeanContext;
33
34 /**
35 * <p>
36 * JavaBeans wishing to be nested within, and obtain a reference to their
37 * execution environment, or context, as defined by the BeanContext
38 * sub-interface shall implement this interface.
39 * </p>
40 * <p>
41 * Conformant BeanContexts shall as a side effect of adding a BeanContextChild
42 * object shall pass a reference to itself via the setBeanContext() method of
43 * this interface.
44 * </p>
45 * <p>
46 * Note that a BeanContextChild may refuse a change in state by throwing
47 * PropertyVetoedException in response.
48 * </p>
49 * <p>
50 * In order for persistence mechanisms to function properly on BeanContextChild
51 * instances across a broad variety of scenarios, implementing classes of this
52 * interface are required to define as transient, any or all fields, or
53 * instance variables, that may contain, or represent, references to the
54 * nesting BeanContext instance or other resources obtained
55 * from the BeanContext via any unspecified mechanisms.
56 * </p>
57 *
58 * @author Laurence P. G. Cable
59 * @since 1.2
60 *
61 * @see java.beans.beancontext.BeanContext
62 * @see java.beans.PropertyChangeEvent
63 * @see java.beans.PropertyChangeListener
64 * @see java.beans.PropertyVetoException
65 * @see java.beans.VetoableChangeListener
66 */
67
68 public interface BeanContextChild {
69
70 /**
71 * <p>
72 * Objects that implement this interface,
73 * shall fire a java.beans.PropertyChangeEvent, with parameters:
74 *
75 * propertyName "beanContext", oldValue (the previous nesting
76 * <code>BeanContext</code> instance, or <code>null</code>),
77 * newValue (the current nesting
78 * <code>BeanContext</code> instance, or <code>null</code>).
79 * <p>
80 * A change in the value of the nesting BeanContext property of this
81 * BeanContextChild may be vetoed by throwing the appropriate exception.
82 * </p>
83 * @param bc The <code>BeanContext</code> with which
84 * to associate this <code>BeanContextChild</code>.
85 * @throws <code>PropertyVetoException</code> if the
86 * addition of the specified <code>BeanContext</code> is refused.
87 */
88 void setBeanContext(BeanContext bc) throws PropertyVetoException;
89
90 /**
91 * Gets the <code>BeanContext</code> associated
92 * with this <code>BeanContextChild</code>.
93 * @return the <code>BeanContext</code> associated
94 * with this <code>BeanContextChild</code>.
95 */
96 BeanContext getBeanContext();
97
98 /**
99 * Adds a <code>PropertyChangeListener</code>
100 * to this <code>BeanContextChild</code>
101 * in order to receive a <code>PropertyChangeEvent</code>
102 * whenever the specified property has changed.
103 * @param name the name of the property to listen on
104 * @param pcl the <code>PropertyChangeListener</code> to add
105 */
106 void addPropertyChangeListener(String name, PropertyChangeListener pcl);
107
108 /**
109 * Removes a <code>PropertyChangeListener</code> from this
110 * <code>BeanContextChild</code> so that it no longer
111 * receives <code>PropertyChangeEvents</code> when the
112 * specified property is changed.
113 *
114 * @param name the name of the property that was listened on
115 * @param pcl the <code>PropertyChangeListener</code> to remove
116 */
117 void removePropertyChangeListener(String name, PropertyChangeListener pcl);
118
119 /**
120 * Adds a <code>VetoableChangeListener</code> to
121 * this <code>BeanContextChild</code>
122 * to receive events whenever the specified property changes.
123 * @param name the name of the property to listen on
124 * @param vcl the <code>VetoableChangeListener</code> to add
125 */
126 void addVetoableChangeListener(String name, VetoableChangeListener vcl);
127
128 /**
129 * Removes a <code>VetoableChangeListener</code> from this
130 * <code>BeanContextChild</code> so that it no longer receives
131 * events when the specified property changes.
132 * @param name the name of the property that was listened on.
133 * @param vcl the <code>VetoableChangeListener</code> to remove.
134 */
135 void removeVetoableChangeListener(String name, VetoableChangeListener vcl);
136
137 }