Observable.java
01 /*
02  * Copyright 2010-2013 the original author or authors.
03  *
04  * Licensed under the Apache License, Version 2.0 (the "License");
05  * you may not use this file except in compliance with the License.
06  * You may obtain a copy of the License at
07  *
08  *      http://www.apache.org/licenses/LICENSE-2.0
09  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package griffon.core;
18 
19 import java.beans.PropertyChangeListener;
20 
21 /**
22  * Describes objects that provide bound properties as specified in the
23  * <a href="http://docs.oracle.com/javase/tutorial/javabeans/TOC.html">Java
24  * Bean Specification</a>.
25  *
26  @author Andres Almiray
27  @since 0.9.1
28  */
29 public interface Observable {
30     /**
31      * Adds the given PropertyChangeListener to the listener list.<p>
32      * The listener is registered for all bound properties of this class.
33      *
34      @param listener the PropertyChangeListener to be added
35      @see #removePropertyChangeListener(PropertyChangeListener)
36      */
37     void addPropertyChangeListener(PropertyChangeListener listener);
38 
39     /**
40      * Removes the given PropertyChangeListener from the listener list.<p>
41      * The listener is registered an specific property of this class.
42      *
43      @param propertyName The name of the property to listen on.
44      @param listener     the PropertyChangeListener to be added
45      @see #removePropertyChangeListener(String, PropertyChangeListener)
46      */
47     void addPropertyChangeListener(String propertyName, PropertyChangeListener listener);
48 
49     /**
50      * Removes the given PropertyChangeListener from the listener list.<p>
51      * This method should be used to remove PropertyChangeListeners that were
52      * registered for all bound properties of this class.
53      *
54      @param listener the PropertyChangeListener to be removed
55      @see #addPropertyChangeListener(PropertyChangeListener)
56      */
57     void removePropertyChangeListener(PropertyChangeListener listener);
58 
59     /**
60      * Removes the given PropertyChangeListener from the listener list.<p>
61      * This method should be used to remove PropertyChangeListeners that were
62      * registered for an specific property of this class.
63      *
64      @param propertyName The name of the property that was listened on.
65      @param listener     the PropertyChangeListener to be removed
66      @see #addPropertyChangeListener(String, PropertyChangeListener)
67      */
68     void removePropertyChangeListener(String propertyName, PropertyChangeListener listener);
69 
70     /**
71      * Returns an array of all the listeners that were added with addPropertyChangeListener().<p>
72      *
73      @return all of the {@code PropertyChangeListeners} added or an empty array if no
74      *         listeners have been added.
75      */
76     PropertyChangeListener[] getPropertyChangeListeners();
77 
78     /**
79      * Returns an array of all the listeners which have been associated
80      * with the named property.
81      *
82      @param propertyName The name of the property being listened to
83      @return all of the <code>PropertyChangeListeners</code> associated with
84      *         the named property.  If no such listeners have been added,
85      *         or if <code>propertyName</code> is null, an empty array is
86      *         returned.
87      */
88     PropertyChangeListener[] getPropertyChangeListeners(String propertyName);
89 }