Observable.java
01 /*
02  * Copyright 2010-2012 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 package griffon.core;
17 
18 import java.beans.PropertyChangeListener;
19 
20 /**
21  * Describes objects that provide bound properties as specified in the
22  * <a href="http://java.sun.com/products/javabeans/docs/spec.html">Java
23  * Bean Specification</a>.
24  *
25  @author Andres Almiray
26  @since 0.9.1
27  */
28 public interface Observable {
29     /**
30      * Adds the given PropertyChangeListener to the listener list.<p>
31      * The listener is registered for all bound properties of this class.
32      *
33      @param listener the PropertyChangeListener to be added
34      @see #removePropertyChangeListener(PropertyChangeListener)
35      */
36     void addPropertyChangeListener(PropertyChangeListener listener);
37 
38     /**
39      * Removes the given PropertyChangeListener from the listener list.<p>
40      * The listener is registered an specific property of this class.
41      *
42      @param propertyName The name of the property to listen on.
43      @param listener     the PropertyChangeListener to be added
44      @see #removePropertyChangeListener(String, PropertyChangeListener)
45      */
46     void addPropertyChangeListener(String propertyName, PropertyChangeListener listener);
47 
48     /**
49      * Removes the given PropertyChangeListener from the listener list.<p>
50      * This method should be used to remove PropertyChangeListeners that were
51      * registered for all bound properties of this class.
52      *
53      @param listener the PropertyChangeListener to be removed
54      @see #addPropertyChangeListener(PropertyChangeListener)
55      */
56     void removePropertyChangeListener(PropertyChangeListener listener);
57 
58     /**
59      * Removes the given PropertyChangeListener from the listener list.<p>
60      * This method should be used to remove PropertyChangeListeners that were
61      * registered for an specific property of this class.
62      *
63      @param propertyName The name of the property that was listened on.
64      @param listener     the PropertyChangeListener to be removed
65      @see #addPropertyChangeListener(String, PropertyChangeListener)
66      */
67     void removePropertyChangeListener(String propertyName, PropertyChangeListener listener);
68 
69     /**
70      * Returns an array of all the listeners that were added with addPropertyChangeListener().<p>
71      *
72      @return all of the {@code PropertyChangeListeners} added or an empty array if no
73      *         listeners have been added.
74      */
75     PropertyChangeListener[] getPropertyChangeListeners();
76 
77     /**
78      * Returns an array of all the listeners which have been associated
79      * with the named property.
80      *
81      @param propertyName The name of the property being listened to
82      @return all of the <code>PropertyChangeListeners</code> associated with
83      *         the named property.  If no such listeners have been added,
84      *         or if <code>propertyName</code> is null, an empty array is
85      *         returned.
86      */
87     PropertyChangeListener[] getPropertyChangeListeners(String propertyName);
88 }