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