java.beans
Class EventSetDescriptor

java.lang.Object
  extended by java.beans.FeatureDescriptor
      extended by java.beans.EventSetDescriptor

public class EventSetDescriptor
extends FeatureDescriptor

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:

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)
          Creates a new EventSetDescriptor.
EventSetDescriptor(String eventSetName, Class<?> listenerType, Method[] listenerMethods, Method addListenerMethod, Method removeListenerMethod, Method getListenerMethod)
          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 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.
 
Methods inherited from class java.beans.FeatureDescriptor
attributeNames, getDisplayName, getName, getShortDescription, getValue, isExpert, isHidden, isPreferred, setDisplayName, setExpert, setHidden, setName, setPreferred, setShortDescription, setValue
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EventSetDescriptor

public EventSetDescriptor(Class<?> eventSourceClass,
                          String eventSetName,
                          Class<?> listenerType,
                          String listenerMethodName)
                   throws IntrospectionException
Creates 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:

  1. 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 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.
  2. 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

public EventSetDescriptor(Class<?> eventSourceClass,
                          String eventSetName,
                          Class<?> listenerType,
                          String[] listenerMethodNames,
                          String addListenerMethodName,
                          String removeListenerMethodName)
                   throws IntrospectionException
Creates 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:
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

public EventSetDescriptor(Class<?> eventSourceClass,
                          String eventSetName,
                          Class<?> listenerType,
                          String[] listenerMethodNames,
                          String addListenerMethodName,
                          String removeListenerMethodName,
                          String getListenerMethodName)
                   throws IntrospectionException
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.

A valid GetListener method is public, flags no exceptions and has one argument which is of type Class 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

public EventSetDescriptor(String eventSetName,
                          Class<?> listenerType,
                          Method[] listenerMethods,
                          Method addListenerMethod,
                          Method removeListenerMethod,
                          Method getListenerMethod)
                   throws IntrospectionException
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.

A valid GetListener method is public, flags no exceptions and has one argument which is of type Class 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

public EventSetDescriptor(String eventSetName,
                          Class<?> listenerType,
                          Method[] listenerMethods,
                          Method addListenerMethod,
                          Method removeListenerMethod)
                   throws IntrospectionException
Creates 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:
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

public EventSetDescriptor(String eventSetName,
                          Class<?> listenerType,
                          MethodDescriptor[] listenerMethodDescriptors,
                          Method addListenerMethod,
                          Method removeListenerMethod)
                   throws IntrospectionException
Creates 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:
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.
Method Detail

getListenerType

public Class<?> getListenerType()
Returns the class that contains the event firing methods.


getListenerMethods

public Method[] getListenerMethods()
Returns the event firing methods.


getListenerMethodDescriptors

public MethodDescriptor[] getListenerMethodDescriptors()
Returns the event firing methods as MethodDescriptor.


getAddListenerMethod

public Method getAddListenerMethod()
Returns the add listener method.


getRemoveListenerMethod

public Method getRemoveListenerMethod()

getGetListenerMethod

public Method getGetListenerMethod()
Returns the method that retrieves the listeners or null if it does not exist.


setUnicast

public void setUnicast(boolean unicast)
Sets whether or not multiple listeners may be added.

Parameters:
unicast - whether or not multiple listeners may be added.

isUnicast

public boolean isUnicast()
Returns whether or not multiple listeners may be added. (Defaults to false.)


setInDefaultEventSet

public void setInDefaultEventSet(boolean inDefaultEventSet)
Sets whether or not this is in the default event set.

Parameters:
inDefaultEventSet - whether this is in the default event set.

isInDefaultEventSet

public boolean isInDefaultEventSet()
Returns whether or not this is in the default event set. (Defaults to true.)