java.beans
public class EventSetDescriptor extends FeatureDescriptor
EventSets have several attributes: the listener class, the events that can be fired to the listener (methods in the listener class), and an add and remove listener method from the event firer's class.
The methods have these constraints on them:
void return value. Any
parameters and exceptions are allowed. May be public, protected or
package-protected. (Don't ask me why that is, I'm just following the spec.
The only place it is even mentioned is in the Java Beans white paper, and
there it is only implied.)void return value. Must
take exactly one argument, of the listener class's type. May fire either
zero exceptions, or one exception of type
java.util.TooManyListenersException.
Must be public.void return value. Must
take exactly one argument, of the listener class's type. May not fire any
exceptions. Must be public.A final constraint is that event listener classes must extend from EventListener.
There are also various design patterns associated with some of the methods of construction. Those are explained in more detail in the appropriate constructors.
Documentation Convention: for proper Internalization of Beans inside an RAD tool, sometimes there are two names for a property or method: a programmatic, or locale-independent name, which can be used anywhere, and a localized, display name, for ease of use. In the documentation I will specify different String values as either programmatic or localized to make this distinction clear.
Since: 1.1
| Constructor Summary | |
|---|---|
| EventSetDescriptor(Class<?> eventSourceClass, String eventSetName, Class<?> listenerType, String listenerMethodName)
Creates a new EventSetDescriptor | |
| EventSetDescriptor(Class<?> eventSourceClass, String eventSetName, Class<?> listenerType, String[] listenerMethodNames, String addListenerMethodName, String removeListenerMethodName)
Creates a new EventSetDescriptor.
| |
| EventSetDescriptor(Class<?> eventSourceClass, String eventSetName, Class<?> listenerType, String[] listenerMethodNames, String addListenerMethodName, String removeListenerMethodName, String getListenerMethodName)
Creates a new EventSetDescriptor.
| |
| EventSetDescriptor(String eventSetName, Class<?> listenerType, Method[] listenerMethods, Method addListenerMethod, Method removeListenerMethod, Method getListenerMethod)
Creates a new EventSetDescriptor.
This variant of the constructor allows you to specify the names of the methods and adds no new constraints on top of the rules already described at the top of the class. | |
| EventSetDescriptor(String eventSetName, Class<?> listenerType, Method[] listenerMethods, Method addListenerMethod, Method removeListenerMethod)
Creates a new EventSetDescriptor.
| |
| EventSetDescriptor(String eventSetName, Class<?> listenerType, MethodDescriptor[] listenerMethodDescriptors, Method addListenerMethod, Method removeListenerMethod) Creates a new EventSetDescriptor.
| |
| Method Summary | |
|---|---|
| Method | getAddListenerMethod() Returns the add listener method. |
| Method | getGetListenerMethod()
Returns the method that retrieves the listeners or null if
it does not exist. |
| MethodDescriptor[] | getListenerMethodDescriptors() Returns the event firing methods as {@link MethodDescriptor}. |
| Method[] | getListenerMethods() Returns the event firing methods. |
| Class<?> | getListenerType() Returns the class that contains the event firing methods. |
| Method | getRemoveListenerMethod() |
| boolean | isInDefaultEventSet() Returns whether or not this is in the default event set.
|
| boolean | isUnicast() Returns whether or not multiple listeners may be added.
|
| void | setInDefaultEventSet(boolean inDefaultEventSet) Sets whether or not this is in the default event set.
|
| void | setUnicast(boolean unicast) Sets whether or not multiple listeners may be added.
|
EventSetDescriptor
This version of the constructor enforces the rules imposed on the methods
described at the top of this class, as well as searching for:
-
The event-firing method must be non-private with signature
void
<listenerMethodName>(<eventSetName>Event) (where
<eventSetName> has its first character capitalized
by the constructor and the Event is a descendant of
{@link java.util.EventObject}) in class listenerType
(any exceptions may be thrown). Implementation note: Note that
there could conceivably be multiple methods with this type of signature
(example: java.util.MouseEvent vs.
my.very.own.MouseEvent). In this implementation, all
methods fitting the description will be put into the
EventSetDescriptor, even though the spec says only one
should be chosen (they probably weren't thinking as pathologically as I
was). I don't like arbitrarily choosing things. If your class has only one
such signature, as most do, you'll have no problems.
- The add and remove methods must be public and named
void
add<eventSetName>Listener(<listenerType>) and
void remove<eventSetName>Listener(<listenerType>)
in in class eventSourceClass, where
<eventSetName> will have its first letter capitalized.
Standard exception rules (see class description) apply.
Parameters: eventSourceClass
the class containing the add/remove listener methods. eventSetName
the programmatic name of the event set, generally starting with a
lowercase letter (i.e. fooManChu instead of FooManChu). This will
be used to generate the name of the event object as well as the
names of the add and remove methods. listenerType
the class containing the event firing method. listenerMethodName
the name of the event firing method.
Throws: IntrospectionException
if listenerType is not an EventListener, or if methods are not
found or are invalid.
EventSetDescriptor.
This form of the constructor allows you to specify the names of the methods and adds no new constraints on top of the rules already described at the top of the class.
Parameters: eventSourceClass the class containing the add and remove listener methods. eventSetName the programmatic name of the event set, generally starting with a lowercase letter (i.e. fooManChu instead of FooManChu). listenerType the class containing the event firing methods. listenerMethodNames the names of the even firing methods. addListenerMethodName the name of the add listener method. removeListenerMethodName the name of the remove listener method.
Throws: IntrospectionException if listenerType is not an EventListener or if methods are not found or are invalid.
EventSetDescriptor.
This variant of the constructor allows you to specify the names of the methods and adds no new constraints on top of the rules already described at the top of the class.
A valid GetListener method is public, flags no exceptions and has one
argument which is of type Class
{@link java.awt.Component#getListeners(Class)} is such a method.
Note: The validity of the return value of the GetListener method is not checked.
Parameters: eventSourceClass the class containing the add and remove listener methods. eventSetName the programmatic name of the event set, generally starting with a lowercase letter (i.e. fooManChu instead of FooManChu). listenerType the class containing the event firing methods. listenerMethodNames the names of the even firing methods. addListenerMethodName the name of the add listener method. removeListenerMethodName the name of the remove listener method. getListenerMethodName Name of a method which returns the array of listeners.
Throws: IntrospectionException if listenerType is not an EventListener or if methods are not found or are invalid.
Since: 1.4
EventSetDescriptor.
This variant of the constructor allows you to specify the names of the methods and adds no new constraints on top of the rules already described at the top of the class.
A valid GetListener method is public, flags no exceptions and has one
argument which is of type Class
{@link java.awt.Component#getListeners(Class)} is such a method.
Note: The validity of the return value of the GetListener method is not checked.
Parameters: eventSetName the programmatic name of the event set, generally starting with a lowercase letter (i.e. fooManChu instead of FooManChu). listenerType the class containing the listenerMethods. listenerMethods the event firing methods. addListenerMethod the add listener method. removeListenerMethod the remove listener method. getListenerMethod The method which returns an array of the listeners.
Throws: IntrospectionException if the listenerType is not an EventListener, or any of the methods are invalid.
Since: 1.4
EventSetDescriptor.
This form of constructor allows you to explicitly say which methods
do what, and no reflection is done by the EventSetDescriptor.
The methods are, however, checked to ensure that they follow the rules
set forth at the top of the class.
Parameters: eventSetName the programmatic name of the event set, generally starting with a lowercase letter (i.e. fooManChu instead of FooManChu). listenerType the class containing the listenerMethods. listenerMethods the event firing methods. addListenerMethod the add listener method. removeListenerMethod the remove listener method.
Throws: IntrospectionException if the listenerType is not an EventListener, or any of the methods are invalid.
EventSetDescriptor.
This form of constructor allows you to explicitly say which methods do
what, and no reflection is done by the EventSetDescriptor.
The methods are, however, checked to ensure that they follow the rules
set forth at the top of the class.
Parameters: eventSetName the programmatic name of the event set, generally starting with a lowercase letter (i.e. fooManChu instead of FooManChu). listenerType the class containing the listenerMethods. listenerMethodDescriptors the event firing methods. addListenerMethod the add listener method. removeListenerMethod the remove listener method.
Throws: IntrospectionException if the listenerType is not an EventListener, or any of the methods are invalid.
null if
it does not exist.Parameters: inDefaultEventSet whether this is in the default event set.
Parameters: unicast whether or not multiple listeners may be added.