KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > api > mdr > events > MDRChangeSource


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19 package org.netbeans.api.mdr.events;
20
21 /** Event source interface implemented by all the repository
22  * objects and MDRepository. Enables other objects
23  * to register for listening to any repository events.
24  * The objects that have to be registered for event
25  * notifications need to implement {@link MDRChangeListener}
26  * or {@link MDRPreChangeListener} interface.<p>
27  *
28  * <p>The repository distributes all the events recursively in the following way:
29  * <ul>
30  * <li>Events fired on an instance are also fired on the corresponding class proxy for this instance.
31  * <li>Events fired on a class proxy are propagated to its immediate package proxy.
32  * <li>Events fired on an association proxy are fired on all the instances affected by this event
33  * (e.g. instances added/removed from a link) and also it is fired on the immediate package proxy.
34  * <li>Events fired on a package proxy are propagated to its immediate package proxy.
35  * If the package proxy is outermost, the event is propagated to the MDRepository that contains
36  * the proxy.
37  * </ul>
38  * Figure below shows where the
39  * events are initially fired and how they propagate.
40  * <img SRC="doc-files/eventForwardingChain.png" alt="Event sources and propagation"/>
41  * </p>
42  *
43  * <p>All the events are propagated recursively till they reach the repository object (e.g. each
44  * instance event is as a result of propagation always fired on the instance itself,
45  * on its class proxy, on its immediate package proxy, on all other package proxies containing
46  * the immediate package proxy to the outermost package proxy and at the end on the repository containing
47  * instance).</p>
48  *
49  * <p>In addition, any event is fired only once for each listener (so no matter how many objects
50  * on the event's propagation path is a listener registered on - e.g. on both
51  * class proxy and its instances - it receives each notification only once per event).</p>
52  *
53  * <p>Listeners may be added specifically for certain events only by calling
54  * {@link #addListener(MDRChangeListener, int) addListener(MDRChangeListener, int)}.
55  * If instead {@link #addListener(MDRChangeListener) addListener(MDRChangeListener)}
56  * is used for listener addition and, hence, no event mask is speficied, the listener
57  * receives all events which are propagated to the source it is registered for.
58  *
59  * @author Martin Matula
60  * @author <a HREF="mailto:hkrug@rationalizer.com">Holger Krug</a>.
61  */
62 public interface MDRChangeSource {
63     
64     /** Registers a listener for receiving all event notifications.
65      *
66      *
67      * @param listener Object that implements {@link MDRChangeListener} interface.
68      */
69     public void addListener(MDRChangeListener listener);
70     /** Registers a listener for receiving notifications about events the type
71      * of which matches <code>mask</code>.
72      * @param listener Object that implements {@link MDRChangeListener} interface.
73      * @param mask bitmask to be used in a call to {@link MDRChangeEvent#isOfType(int)}
74      * to filter events based on the mask. The masks are defined in {@link MDRChangeEvent}
75      * and the interfaces that extend it.
76      * @see <a HREF="../../../../../constant-values.html">Constant Field Values</a>
77      */
78     public void addListener(MDRChangeListener listener, int mask);
79     /** Removes listener from the list of objects registered for events notifications.
80      * @param listener Object that implements {@link MDRChangeListener} interface.
81      */
82     public void removeListener(MDRChangeListener listener);
83     /** Removes listener only for events of types matching <code>mask</code>.
84      * If a listener is additionally registered for events of other types, it
85      * proceeds listening on the remaining event types.
86      * @param listener Object that implements {@link MDRChangeListener} interface.
87      * @param mask determines the types of events the listener shall stop
88      * to listen on. The masks are defined in {@link MDRChangeEvent}
89      * and the interfaces that extend it.
90      * @see <a HREF="../../../../../constant-values.html">Constant Field Values</a>
91      */
92     public void removeListener(MDRChangeListener listener, int mask);
93 }
94
Popular Tags