home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / beans / EventSetDescriptor.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  11.4 KB  |  337 lines
  1. /*
  2.  * @(#)EventSetDescriptor.java    1.44 98/03/18
  3.  *
  4.  * Copyright 1996, 1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.beans;
  16.  
  17. import java.lang.reflect.*;
  18.  
  19. /**
  20.  * An EventSetDescriptor describes a group of events that a given Java
  21.  * bean fires.
  22.  * <P>
  23.  * The given group of events are all delivered as method calls on a single
  24.  * event listener interface, and an event listener object can be registered
  25.  * via a call on a registration method supplied by the event source.
  26.  */
  27.  
  28.  
  29. public class EventSetDescriptor extends FeatureDescriptor {
  30.  
  31.     /**
  32.      * This constructor creates an EventSetDescriptor assuming that you are
  33.      * following the most simple standard design pattern where a named
  34.      * event "fred" is (1) delivered as a call on the single method of
  35.      * interface FredListener, (2) has a single argument of type FredEvent,
  36.      * and (3) where the FredListener may be registered with a call on an
  37.      * addFredListener method of the source component and removed with a
  38.      * call on a removeFredListener method.
  39.      *
  40.      * @param sourceClass  The class firing the event.
  41.      * @param eventSetName  The programmatic name of the event.  E.g. "fred".
  42.      *        Note that this should normally start with a lower-case character.
  43.      * @param listenerType  The target interface that events
  44.      *        will get delivered to.
  45.      * @param listenerMethodName  The method that will get called when the event gets
  46.      *        delivered to its target listener interface.
  47.      * @exception IntrospectionException if an exception occurs during
  48.      *              introspection.
  49.      */
  50.     public EventSetDescriptor(Class sourceClass, String eventSetName,
  51.         Class listenerType, String listenerMethodName) 
  52.         throws IntrospectionException {
  53.  
  54.        setName(eventSetName);
  55.  
  56.     // Get a Class object for the listener class.
  57.         this.listenerType = listenerType;
  58.     
  59.     listenerMethods = new Method[1];
  60.     listenerMethods[0] = Introspector.findMethod(listenerType,
  61.                         listenerMethodName, 1);
  62.  
  63.     String listenerClassName = listenerType.getName();
  64.     String tail = listenerClassName.substring(listenerClassName.lastIndexOf('.') + 1);
  65.  
  66.     String addMethodName = "add" + tail;
  67.     addMethod = Introspector.findMethod(sourceClass, addMethodName, 1);
  68.  
  69.     String removeMethodName = "remove" + tail;
  70.     removeMethod = Introspector.findMethod(sourceClass, removeMethodName, 1);
  71.                     
  72.  
  73.     }
  74.  
  75.     /**
  76.      * This constructor creates an EventSetDescriptor from scratch using
  77.      * string names.
  78.      *
  79.      * @param sourceClass  The class firing the event.
  80.      * @param eventSetName The programmatic name of the event set.
  81.      *        Note that this should normally start with a lower-case character.
  82.      * @param listenerType  The Class of the target interface that events
  83.      *        will get delivered to.
  84.      * @param listenerMethodNames The names of the methods that will get called 
  85.      *        when the event gets delivered to its target listener interface.
  86.      * @param addListenerMethodName  The name of the method on the event source
  87.      *        that can be used to register an event listener object.
  88.      * @param removeListenerMethodName  The name of the method on the event source
  89.      *        that can be used to de-register an event listener object.
  90.      * @exception IntrospectionException if an exception occurs during
  91.      *              introspection.
  92.      */
  93.     public EventSetDescriptor(Class sourceClass,
  94.         String eventSetName, 
  95.         Class listenerType,
  96.         String listenerMethodNames[],
  97.         String addListenerMethodName,
  98.         String removeListenerMethodName)
  99.         throws IntrospectionException {
  100.     setName(eventSetName);
  101.     listenerMethods = new Method[listenerMethodNames.length];
  102.     for (int i = 0; i < listenerMethods.length; i++) {
  103.         String listenerName = listenerMethodNames[i];
  104.         if (listenerName == null) {
  105.         throw new NullPointerException();
  106.         }
  107.         listenerMethods[i] = Introspector.findMethod(listenerType,
  108.                             listenerName, 1);
  109.     }
  110.  
  111.     this.addMethod = Introspector.findMethod(sourceClass,
  112.                     addListenerMethodName, 1);
  113.     this.removeMethod = Introspector.findMethod(sourceClass,
  114.                     removeListenerMethodName, 1);
  115.  
  116.     this.listenerType = listenerType;
  117.     }
  118.  
  119.     /**
  120.      * This constructor creates an EventSetDescriptor from scratch using
  121.      * java.lang.reflect.Method and java.lang.Class objects.
  122.      *
  123.      * @param eventSetName The programmatic name of the event set.
  124.      * @param listenerType The Class for the listener interface.
  125.      * @param listenerMethods  An array of Method objects describing each
  126.      *        of the event handling methods in the target listener.
  127.      * @param addListenerMethod  The method on the event source
  128.      *        that can be used to register an event listener object.
  129.      * @param removeListenerMethod  The method on the event source
  130.      *        that can be used to de-register an event listener object.
  131.      * @exception IntrospectionException if an exception occurs during
  132.      *              introspection.
  133.      */
  134.     public EventSetDescriptor(String eventSetName, 
  135.         Class listenerType,
  136.         Method listenerMethods[],
  137.         Method addListenerMethod,
  138.         Method removeListenerMethod) 
  139.         throws IntrospectionException {
  140.     setName(eventSetName);
  141.     this.listenerMethods = listenerMethods;
  142.     this.addMethod = addListenerMethod;
  143.     this.removeMethod = removeListenerMethod;
  144.     this.listenerType = listenerType;
  145.     }
  146.  
  147.     /**
  148.      * This constructor creates an EventSetDescriptor from scratch using
  149.      * java.lang.reflect.MethodDescriptor and java.lang.Class objects.
  150.      *
  151.      * @param eventSetName The programmatic name of the event set.
  152.      * @param listenerType The Class for the listener interface.
  153.      * @param listenerMethodDescriptors  An array of MethodDescriptor objects
  154.      *         describing each of the event handling methods in the
  155.      *           target listener.
  156.      * @param addListenerMethod  The method on the event source
  157.      *        that can be used to register an event listener object.
  158.      * @param removeListenerMethod  The method on the event source
  159.      *        that can be used to de-register an event listener object.
  160.      * @exception IntrospectionException if an exception occurs during
  161.      *              introspection.
  162.      */
  163.     public EventSetDescriptor(String eventSetName, 
  164.         Class listenerType,
  165.         MethodDescriptor listenerMethodDescriptors[],
  166.         Method addListenerMethod,
  167.         Method removeListenerMethod) 
  168.         throws IntrospectionException {
  169.     setName(eventSetName);
  170.     this.listenerMethodDescriptors = listenerMethodDescriptors;
  171.     this.addMethod = addListenerMethod;
  172.     this.removeMethod = removeListenerMethod;
  173.     this.listenerType = listenerType;
  174.     }
  175.  
  176.     /** 
  177.      * @return The Class object for the target interface that will
  178.      * get invoked when the event is fired.
  179.      */
  180.     public Class getListenerType() {
  181.     return listenerType;
  182.     }
  183.  
  184.     /** 
  185.      * @return An array of Method objects for the target methods
  186.      * within the target listener interface that will get called when
  187.      * events are fired.
  188.      */
  189.     public Method[] getListenerMethods() {
  190.     if (listenerMethods == null && listenerMethodDescriptors != null) {
  191.         // Create Method array from MethodDescriptor array.
  192.         listenerMethods = new Method[listenerMethodDescriptors.length];
  193.         for (int i = 0; i < listenerMethods.length; i++) {
  194.         listenerMethods[i] = listenerMethodDescriptors[i].getMethod();
  195.         }
  196.     }
  197.     return listenerMethods;
  198.     }
  199.  
  200.  
  201.     /** 
  202.      * @return An array of MethodDescriptor objects for the target methods
  203.      * within the target listener interface that will get called when
  204.      * events are fired.
  205.      */
  206.     public MethodDescriptor[] getListenerMethodDescriptors() {
  207.     if (listenerMethodDescriptors == null && listenerMethods != null) {
  208.         // Create MethodDescriptor array from Method array.
  209.         listenerMethodDescriptors = 
  210.                 new MethodDescriptor[listenerMethods.length];
  211.         for (int i = 0; i < listenerMethods.length; i++) {
  212.         listenerMethodDescriptors[i] = 
  213.                 new MethodDescriptor(listenerMethods[i]);
  214.         }
  215.     }
  216.     return listenerMethodDescriptors;
  217.     }
  218.  
  219.     /** 
  220.      * @return The method used to register a listener at the event source.
  221.      */
  222.     public Method getAddListenerMethod() {
  223.     return addMethod;
  224.     }
  225.  
  226.     /** 
  227.      * @return The method used to remove a listener at the event source.
  228.      */
  229.     public Method getRemoveListenerMethod() {
  230.     return removeMethod;
  231.     }
  232.  
  233.     /**
  234.      * Mark an event set as unicast (or not).
  235.      *
  236.      * @param unicast  True if the event set is unicast.
  237.      */
  238.  
  239.     public void setUnicast(boolean unicast) {
  240.     this.unicast = unicast;
  241.     }
  242.     
  243.     /**
  244.      * Normally event sources are multicast.  However there are some 
  245.      * exceptions that are strictly unicast.
  246.      *
  247.      * @return  True if the event set is unicast.  Defaults to "false".
  248.      */
  249.  
  250.     public boolean isUnicast() {
  251.     return unicast;
  252.     }
  253.  
  254.     /**
  255.      * Mark an event set as being in the "default" set (or not).
  256.      * By default this is true.
  257.      *
  258.      * @param unicast  True if the event set is unicast.
  259.      */
  260.  
  261.     public void setInDefaultEventSet(boolean inDefaultEventSet) {
  262.     this.inDefaultEventSet = inDefaultEventSet;
  263.     }
  264.     
  265.     /**
  266.      * Report if an event set is in the "default set".
  267.      *
  268.      * @return  True if the event set is in the "default set".  Defaults to "true".
  269.      */
  270.  
  271.     public boolean isInDefaultEventSet() {
  272.     return inDefaultEventSet;
  273.     }
  274.  
  275.     /*
  276.      * Package-private constructor
  277.      * Merge two event set descriptors.  Where they conflict, give the
  278.      * second argument (y) priority over the first argument (x).
  279.      * @param x  The first (lower priority) EventSetDescriptor
  280.      * @param y  The second (higher priority) EventSetDescriptor
  281.      */
  282.  
  283.     EventSetDescriptor(EventSetDescriptor x, EventSetDescriptor y) {
  284.     super(x,y);
  285.     listenerMethodDescriptors = x.listenerMethodDescriptors;
  286.     if (y.listenerMethodDescriptors != null) {
  287.         listenerMethodDescriptors = y.listenerMethodDescriptors;
  288.     }
  289.     if (listenerMethodDescriptors == null) {
  290.         listenerMethods = y.listenerMethods;
  291.     }
  292.     addMethod = y.addMethod;
  293.     removeMethod = y.removeMethod;
  294.     unicast = y.unicast;
  295.     listenerType = y.listenerType;
  296.     if (!x.inDefaultEventSet || !y.inDefaultEventSet) {
  297.         inDefaultEventSet = false;
  298.     }
  299.     }
  300.  
  301.     /*
  302.      * Package-private dup constructor
  303.      * This must isolate the new object from any changes to the old object.
  304.      */
  305.     EventSetDescriptor(EventSetDescriptor old) {
  306.     super(old);
  307.     if (old.listenerMethodDescriptors != null) {
  308.         int len = old.listenerMethodDescriptors.length;
  309.         listenerMethodDescriptors = new MethodDescriptor[len];
  310.         for (int i = 0; i < len; i++) {
  311.         listenerMethodDescriptors[i] = new MethodDescriptor(
  312.                     old.listenerMethodDescriptors[i]);
  313.         }
  314.     }
  315.     if (old.listenerMethods != null) {
  316.         int len = old.listenerMethods.length;
  317.         listenerMethods = new Method[len];
  318.         for (int i = 0; i < len; i++) {
  319.         listenerMethods[i] = old.listenerMethods[i];
  320.         }
  321.     }
  322.     addMethod = old.addMethod;
  323.     removeMethod = old.removeMethod;
  324.     unicast = old.unicast;
  325.     listenerType = old.listenerType;
  326.     inDefaultEventSet = old.inDefaultEventSet;
  327.     }
  328.  
  329.     private Class listenerType;
  330.     private Method[] listenerMethods;
  331.     private MethodDescriptor[] listenerMethodDescriptors;
  332.     private Method addMethod;
  333.     private Method removeMethod;
  334.     private boolean unicast;
  335.     private boolean inDefaultEventSet = true;
  336. }
  337.