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