java.beans
Class EventSetDescriptor
java.lang.Object
|
+--java.beans.FeatureDescriptor
|
+--java.beans.EventSetDescriptor
EventSetDescriptor describes the hookup between an event source
class and an event listener class.
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:
- event firing methods: must have
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.)
- add listener method: must have
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.
- remove listener method: must have
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:Author:EventSetDescriptor(java.lang.Class eventSourceClass, java.lang.String eventSetName, java.lang.Class listenerType, java.lang.String listenerMethodName)
|
EventSetDescriptor(java.lang.Class eventSourceClass, java.lang.String eventSetName, java.lang.Class listenerType, java.lang.String[] listenerMethodNames, java.lang.String addListenerMethodName, java.lang.String removeListenerMethodName)
|
EventSetDescriptor(java.lang.String eventSetName, java.lang.Class listenerType, java.lang.reflect.Method listenerMethods, java.lang.reflect.Method addListenerMethod, java.lang.reflect.Method removeListenerMethod)
|
EventSetDescriptor(java.lang.String eventSetName, java.lang.Class listenerType, java.beans.MethodDescriptor listenerMethodDescriptors, java.lang.reflect.Method addListenerMethod, java.lang.reflect.Method removeListenerMethod)
|
EventSetDescriptor
public EventSetDescriptor(java.lang.Class eventSourceClass, java.lang.String eventSetName, java.lang.Class listenerType, java.lang.String listenerMethodName)Create a new 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
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:
Throws:
EventSetDescriptor
public EventSetDescriptor(java.lang.Class eventSourceClass, java.lang.String eventSetName, java.lang.Class listenerType, java.lang.String[] listenerMethodNames, java.lang.String addListenerMethodName, java.lang.String removeListenerMethodName)Create a new 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:
Throws:
EventSetDescriptor
public EventSetDescriptor(java.lang.String eventSetName, java.lang.Class listenerType, java.beans.MethodDescriptor listenerMethodDescriptors, java.lang.reflect.Method addListenerMethod, java.lang.reflect.Method removeListenerMethod)Create a new 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:
Throws:
EventSetDescriptor
public EventSetDescriptor(java.lang.String eventSetName, java.lang.Class listenerType, java.lang.reflect.Method listenerMethods, java.lang.reflect.Method addListenerMethod, java.lang.reflect.Method removeListenerMethod)Create a new 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:
Throws:
getAddListenerMethod
public Method getAddListenerMethod()Get the add listener method. *
getListenerMethodDescriptors
public MethodDescriptor[] getListenerMethodDescriptors()Get the event firing methods as MethodDescriptors. *
getListenerMethods
public Method[] getListenerMethods()Get the event firing methods. *
getListenerType
public Class getListenerType()Get the class that contains the event firing methods. *
getRemoveListenerMethod
public Method getRemoveListenerMethod()Get the remove listener method. *
isInDefaultEventSet
public boolean isInDefaultEventSet()Get whether or not this is in the default event set. (Defaults to true.)*
isUnicast
public boolean isUnicast()Get whether or not multiple listeners may be added. (Defaults to false.) *
setInDefaultEventSet
public void setInDefaultEventSet(boolean inDefaultEventSet)Set whether or not this is in the default event set.
Parameters:
setUnicast
public void setUnicast(boolean unicast)Set whether or not multiple listeners may be added.
Parameters:
The methods have these constraints on them:
- event firing methods: must have
- add listener method: must have
- remove listener method: must have
A final constraint is that event listener classes must extend from EventListener.voidreturn 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.)voidreturn value. Must take exactly one argument, of the listener class's type. May fire either zero exceptions, or one exception of typejava.util.TooManyListenersException. Must be public.voidreturn value. Must take exactly one argument, of the listener class's type. May not fire any exceptions. Must be public.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.