source: trunk/src/gcc/libjava/java/beans/EventSetDescriptor.java@ 1213

Last change on this file since 1213 was 2, checked in by bird, 23 years ago

Initial revision
  • Property cvs2svn:cvs-rev set to 1.1
  • Property svn:eol-style set to native
  • Property svn:executable set to *
File size: 19.3 KB
Line 
1/* java.beans.EventSetDescriptor
2 Copyright (C) 1998 Free Software Foundation, Inc.
3
4This file is part of GNU Classpath.
5
6GNU Classpath is free software; you can redistribute it and/or modify
7it under the terms of the GNU General Public License as published by
8the Free Software Foundation; either version 2, or (at your option)
9any later version.
10
11GNU Classpath is distributed in the hope that it will be useful, but
12WITHOUT ANY WARRANTY; without even the implied warranty of
13MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14General Public License for more details.
15
16You should have received a copy of the GNU General Public License
17along with GNU Classpath; see the file COPYING. If not, write to the
18Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
1902111-1307 USA.
20
21Linking this library statically or dynamically with other modules is
22making a combined work based on this library. Thus, the terms and
23conditions of the GNU General Public License cover the whole
24combination.
25
26As a special exception, the copyright holders of this library give you
27permission to link this library with independent modules to produce an
28executable, regardless of the license terms of these independent
29modules, and to copy and distribute the resulting executable under
30terms of your choice, provided that you also meet, for each linked
31independent module, the terms and conditions of the license of that
32module. An independent module is a module which is not derived from
33or based on this library. If you modify this library, you may extend
34this exception to your version of the library, but you are not
35obligated to do so. If you do not wish to do so, delete this
36exception statement from your version. */
37
38
39package java.beans;
40
41import java.util.*;
42import java.lang.reflect.*;
43import gnu.java.lang.*;
44
45/**
46 ** EventSetDescriptor describes the hookup between an event source
47 ** class and an event listener class.
48 **
49 ** EventSets have several attributes: the listener class, the events
50 ** that can be fired to the listener (methods in the listener class), and
51 ** an add and remove listener method from the event firer's class.<P>
52 **
53 ** The methods have these constraints on them:<P>
54 ** <UL>
55 ** <LI>event firing methods: must have <CODE>void</CODE> return value. Any
56 ** parameters and exceptions are allowed. May be public, protected or
57 ** package-protected. (Don't ask me why that is, I'm just following the spec.
58 ** The only place it is even mentioned is in the Java Beans white paper, and
59 ** there it is only implied.)</LI>
60 ** <LI>add listener method: must have <CODE>void</CODE> return value. Must
61 ** take exactly one argument, of the listener class's type. May fire either
62 ** zero exceptions, or one exception of type <CODE>java.util.TooManyListenersException</CODE>.
63 ** Must be public.</LI>
64 ** <LI>remove listener method: must have <CODE>void</CODE> return value.
65 ** Must take exactly one argument, of the listener class's type. May not
66 ** fire any exceptions. Must be public.</LI>
67 ** </UL>
68 **
69 ** A final constraint is that event listener classes must extend from EventListener.<P>
70 **
71 ** There are also various design patterns associated with some of the methods
72 ** of construction. Those are explained in more detail in the appropriate
73 ** constructors.<P>
74 **
75 ** <STRONG>Documentation Convention:</STRONG> for proper
76 ** Internalization of Beans inside an RAD tool, sometimes there
77 ** are two names for a property or method: a programmatic, or
78 ** locale-independent name, which can be used anywhere, and a
79 ** localized, display name, for ease of use. In the
80 ** documentation I will specify different String values as
81 ** either <EM>programmatic</EM> or <EM>localized</EM> to
82 ** make this distinction clear.
83 **
84 ** @author John Keiser
85 ** @since JDK1.1
86 ** @version 1.1.0, 31 May 1998
87 **/
88
89public class EventSetDescriptor extends FeatureDescriptor {
90 private Method addListenerMethod;
91 private Method removeListenerMethod;
92 private Class listenerType;
93 private MethodDescriptor[] listenerMethodDescriptors;
94 private Method[] listenerMethods;
95
96 private boolean unicast;
97 private boolean inDefaultEventSet = true;
98
99 /** Create a new EventSetDescriptor.
100 ** This version of the constructor enforces the rules imposed on the methods
101 ** described at the top of this class, as well as searching for:<P>
102 ** <OL>
103 ** <LI>The event-firing method must be non-private with signature
104 ** <CODE>void &lt;listenerMethodName&gt;(&lt;eventSetName&gt;Event)</CODE>
105 ** (where <CODE>&lt;eventSetName&gt;</CODE> has its first character capitalized
106 ** by the constructor and the Event is a descendant of
107 ** <CODE>java.util.EventObject</CODE>) in class <CODE>listenerType</CODE>
108 ** (any exceptions may be thrown).
109 ** <B>Implementation note:</B> Note that there could conceivably be multiple
110 ** methods with this type of signature (example: java.util.MouseEvent vs.
111 ** my.very.own.MouseEvent). In this implementation, all methods fitting the
112 ** description will be put into the <CODE>EventSetDescriptor</CODE>, even
113 ** though the spec says only one should be chosen (they probably weren't thinking as
114 ** pathologically as I was). I don't like arbitrarily choosing things.
115 ** If your class has only one such signature, as most do, you'll have no problems.</LI>
116 ** <LI>The add and remove methods must be public and named
117 ** <CODE>void add&lt;eventSetName&gt;Listener(&lt;listenerType&gt;)</CODE> and
118 ** <CODE>void remove&lt;eventSetName&gt;Listener(&lt;listenerType&gt;)</CODE> in
119 ** in class <CODE>eventSourceClass</CODE>, where
120 ** <CODE>&lt;eventSetName&gt;</CODE> will have its first letter capitalized.
121 ** Standard exception rules (see class description) apply.</LI>
122 ** </OL>
123 ** @param eventSourceClass the class containing the add/remove listener methods.
124 ** @param eventSetName the programmatic name of the event set, generally starting
125 ** with a lowercase letter (i.e. fooManChu instead of FooManChu). This will be used
126 ** to generate the name of the event object as well as the names of the add and
127 ** remove methods.
128 ** @param listenerType the class containing the event firing method.
129 ** @param listenerMethodName the name of the event firing method.
130 ** @exception IntrospectionException if listenerType is not an EventListener,
131 ** or if methods are not found or are invalid.
132 **/
133 public EventSetDescriptor(Class eventSourceClass,
134 String eventSetName,
135 Class listenerType,
136 String listenerMethodName) throws IntrospectionException {
137 setName(eventSetName);
138 if(!java.util.EventListener.class.isAssignableFrom(listenerType)) {
139 throw new IntrospectionException("Listener type is not an EventListener.");
140 }
141
142 String[] names = new String[1];
143 names[0] = listenerMethodName;
144
145 try {
146 eventSetName = Character.toUpperCase(eventSetName.charAt(0)) + eventSetName.substring(1);
147 } catch(StringIndexOutOfBoundsException e) {
148 eventSetName = "";
149 }
150
151 findMethods(eventSourceClass,listenerType,names,"add"+eventSetName+"Listener","remove"+eventSetName+"Listener",eventSetName+"Event");
152 this.listenerType = listenerType;
153 checkAddListenerUnicast();
154 if(this.removeListenerMethod.getExceptionTypes().length > 0) {
155 throw new IntrospectionException("Listener remove method throws exceptions.");
156 }
157 }
158
159 /** Create a new EventSetDescriptor.
160 ** This form of the constructor allows you to specify the names of the methods and adds
161 ** no new constraints on top of the rules already described at the top of the class.<P>
162 **
163 ** @param eventSourceClass the class containing the add and remove listener methods.
164 ** @param eventSetName the programmatic name of the event set, generally starting
165 ** with a lowercase letter (i.e. fooManChu instead of FooManChu).
166 ** @param listenerType the class containing the event firing methods.
167 ** @param listenerMethodNames the names of the even firing methods.
168 ** @param addListenerMethodName the name of the add listener method.
169 ** @param removeListenerMethodName the name of the remove listener method.
170 ** @exception IntrospectionException if listenerType is not an EventListener
171 ** or if methods are not found or are invalid.
172 **/
173 public EventSetDescriptor(Class eventSourceClass,
174 String eventSetName,
175 Class listenerType,
176 String[] listenerMethodNames,
177 String addListenerMethodName,
178 String removeListenerMethodName) throws IntrospectionException {
179 setName(eventSetName);
180 if(!java.util.EventListener.class.isAssignableFrom(listenerType)) {
181 throw new IntrospectionException("Listener type is not an EventListener.");
182 }
183
184 findMethods(eventSourceClass,listenerType,listenerMethodNames,addListenerMethodName,removeListenerMethodName,null);
185 this.listenerType = listenerType;
186 checkAddListenerUnicast();
187 if(this.removeListenerMethod.getExceptionTypes().length > 0) {
188 throw new IntrospectionException("Listener remove method throws exceptions.");
189 }
190 }
191
192 /** Create a new EventSetDescriptor.
193 ** This form of constructor allows you to explicitly say which methods do what, and
194 ** no reflection is done by the EventSetDescriptor. The methods are, however,
195 ** checked to ensure that they follow the rules set forth at the top of the class.
196 ** @param eventSetName the programmatic name of the event set, generally starting
197 ** with a lowercase letter (i.e. fooManChu instead of FooManChu).
198 ** @param listenerType the class containing the listenerMethods.
199 ** @param listenerMethods the event firing methods.
200 ** @param addListenerMethod the add listener method.
201 ** @param removeListenerMethod the remove listener method.
202 ** @exception IntrospectionException if the listenerType is not an EventListener,
203 ** or any of the methods are invalid.
204 **/
205 public EventSetDescriptor(String eventSetName,
206 Class listenerType,
207 Method[] listenerMethods,
208 Method addListenerMethod,
209 Method removeListenerMethod) throws IntrospectionException {
210 setName(eventSetName);
211 if(!java.util.EventListener.class.isAssignableFrom(listenerType)) {
212 throw new IntrospectionException("Listener type is not an EventListener.");
213 }
214
215 this.listenerMethods = listenerMethods;
216 this.addListenerMethod = addListenerMethod;
217 this.removeListenerMethod = removeListenerMethod;
218 this.listenerType = listenerType;
219 checkMethods();
220 checkAddListenerUnicast();
221 if(this.removeListenerMethod.getExceptionTypes().length > 0) {
222 throw new IntrospectionException("Listener remove method throws exceptions.");
223 }
224 }
225
226 /** Create a new EventSetDescriptor.
227 ** This form of constructor allows you to explicitly say which methods do what, and
228 ** no reflection is done by the EventSetDescriptor. The methods are, however,
229 ** checked to ensure that they follow the rules set forth at the top of the class.
230 ** @param eventSetName the programmatic name of the event set, generally starting
231 ** with a lowercase letter (i.e. fooManChu instead of FooManChu).
232 ** @param listenerType the class containing the listenerMethods.
233 ** @param listenerMethodDescriptors the event firing methods.
234 ** @param addListenerMethod the add listener method.
235 ** @param removeListenerMethod the remove listener method.
236 ** @exception IntrospectionException if the listenerType is not an EventListener,
237 ** or any of the methods are invalid.
238 **/
239 public EventSetDescriptor(String eventSetName,
240 Class listenerType,
241 MethodDescriptor[] listenerMethodDescriptors,
242 Method addListenerMethod,
243 Method removeListenerMethod) throws IntrospectionException {
244 setName(eventSetName);
245 if(!java.util.EventListener.class.isAssignableFrom(listenerType)) {
246 throw new IntrospectionException("Listener type is not an EventListener.");
247 }
248
249 this.listenerMethodDescriptors = listenerMethodDescriptors;
250 this.listenerMethods = new Method[listenerMethodDescriptors.length];
251 for(int i=0;i<this.listenerMethodDescriptors.length;i++) {
252 this.listenerMethods[i] = this.listenerMethodDescriptors[i].getMethod();
253 }
254
255 this.addListenerMethod = addListenerMethod;
256 this.removeListenerMethod = removeListenerMethod;
257 this.listenerType = listenerType;
258 checkMethods();
259 checkAddListenerUnicast();
260 if(this.removeListenerMethod.getExceptionTypes().length > 0) {
261 throw new IntrospectionException("Listener remove method throws exceptions.");
262 }
263 }
264
265 /** Get the class that contains the event firing methods. **/
266 public Class getListenerType() {
267 return listenerType;
268 }
269
270 /** Get the event firing methods. **/
271 public Method[] getListenerMethods() {
272 return listenerMethods;
273 }
274
275 /** Get the event firing methods as MethodDescriptors. **/
276 public MethodDescriptor[] getListenerMethodDescriptors() {
277 if(listenerMethodDescriptors == null) {
278 listenerMethodDescriptors = new MethodDescriptor[listenerMethods.length];
279 for(int i=0;i<listenerMethods.length;i++) {
280 listenerMethodDescriptors[i] = new MethodDescriptor(listenerMethods[i]);
281 }
282 }
283 return listenerMethodDescriptors;
284 }
285
286 /** Get the add listener method. **/
287 public Method getAddListenerMethod() {
288 return addListenerMethod;
289 }
290
291 /** Get the remove listener method. **/
292 public Method getRemoveListenerMethod() {
293 return removeListenerMethod;
294 }
295
296 /** Set whether or not multiple listeners may be added.
297 ** @param unicast whether or not multiple listeners may be added.
298 **/
299 public void setUnicast(boolean unicast) {
300 this.unicast = unicast;
301 }
302
303 /** Get whether or not multiple listeners may be added. (Defaults to false.) **/
304 public boolean isUnicast() {
305 return unicast;
306 }
307
308 /** Set whether or not this is in the default event set.
309 ** @param inDefaultEventSet whether this is in the default event set.
310 **/
311 public void setInDefaultEventSet(boolean inDefaultEventSet) {
312 this.inDefaultEventSet = inDefaultEventSet;
313 }
314
315 /** Get whether or not this is in the default event set. (Defaults to true.)**/
316 public boolean isInDefaultEventSet() {
317 return inDefaultEventSet;
318 }
319
320 private void checkAddListenerUnicast() throws IntrospectionException {
321 Class[] addListenerExceptions = this.addListenerMethod.getExceptionTypes();
322 if(addListenerExceptions.length > 1) {
323 throw new IntrospectionException("Listener add method throws too many exceptions.");
324 } else if(addListenerExceptions.length == 1
325 && !java.util.TooManyListenersException.class.isAssignableFrom(addListenerExceptions[0])) {
326 throw new IntrospectionException("Listener add method throws too many exceptions.");
327 }
328 }
329
330 private void checkMethods() throws IntrospectionException {
331 if(!addListenerMethod.getDeclaringClass().isAssignableFrom(removeListenerMethod.getDeclaringClass())
332 && !removeListenerMethod.getDeclaringClass().isAssignableFrom(addListenerMethod.getDeclaringClass())) {
333 throw new IntrospectionException("add and remove listener methods do not come from the same class. This is bad.");
334 }
335 if(!addListenerMethod.getReturnType().equals(java.lang.Void.TYPE)
336 || addListenerMethod.getParameterTypes().length != 1
337 || !listenerType.equals(addListenerMethod.getParameterTypes()[0])
338 || !Modifier.isPublic(addListenerMethod.getModifiers())) {
339 throw new IntrospectionException("Add Listener Method invalid.");
340 }
341 if(!removeListenerMethod.getReturnType().equals(java.lang.Void.TYPE)
342 || removeListenerMethod.getParameterTypes().length != 1
343 || !listenerType.equals(removeListenerMethod.getParameterTypes()[0])
344 || removeListenerMethod.getExceptionTypes().length > 0
345 || !Modifier.isPublic(removeListenerMethod.getModifiers())) {
346 throw new IntrospectionException("Remove Listener Method invalid.");
347 }
348
349 for(int i=0;i<listenerMethods.length;i++) {
350 if(!listenerMethods[i].getReturnType().equals(java.lang.Void.TYPE)
351 || Modifier.isPrivate(listenerMethods[i].getModifiers())) {
352 throw new IntrospectionException("Event Method " + listenerMethods[i].getName() + " non-void or private.");
353 }
354 if(!listenerMethods[i].getDeclaringClass().isAssignableFrom(listenerType)) {
355 throw new IntrospectionException("Event Method " + listenerMethods[i].getName() + " not from class " + listenerType.getName());
356 }
357 }
358 }
359
360 private void findMethods(Class eventSourceClass,
361 Class listenerType,
362 String listenerMethodNames[],
363 String addListenerMethodName,
364 String removeListenerMethodName,
365 String absurdEventClassCheckName) throws IntrospectionException {
366
367 /* Find add listener method and remove listener method. */
368 Class[] listenerArgList = new Class[1];
369 listenerArgList[0] = listenerType;
370 try {
371 this.addListenerMethod = eventSourceClass.getMethod(addListenerMethodName,listenerArgList);
372 } catch(SecurityException E) {
373 throw new IntrospectionException("SecurityException trying to access method " + addListenerMethodName + ".");
374 } catch(NoSuchMethodException E) {
375 throw new IntrospectionException("Could not find method " + addListenerMethodName + ".");
376 }
377
378 if(this.addListenerMethod == null || !this.addListenerMethod.getReturnType().equals(java.lang.Void.TYPE)) {
379 throw new IntrospectionException("Add listener method does not exist, is not public, or is not void.");
380 }
381
382 try {
383 this.removeListenerMethod = eventSourceClass.getMethod(removeListenerMethodName,listenerArgList);
384 } catch(SecurityException E) {
385 throw new IntrospectionException("SecurityException trying to access method " + removeListenerMethodName + ".");
386 } catch(NoSuchMethodException E) {
387 throw new IntrospectionException("Could not find method " + removeListenerMethodName + ".");
388 }
389 if(this.removeListenerMethod == null || !this.removeListenerMethod.getReturnType().equals(java.lang.Void.TYPE)) {
390 throw new IntrospectionException("Remove listener method does not exist, is not public, or is not void.");
391 }
392
393 /* Find the listener methods. */
394 Method[] methods;
395 try {
396 methods = ClassHelper.getAllMethods(listenerType);
397 } catch(SecurityException E) {
398 throw new IntrospectionException("Security: You cannot access fields in this class.");
399 }
400
401 Vector chosenMethods = new Vector();
402 boolean[] listenerMethodFound = new boolean[listenerMethodNames.length];
403 for(int i=0;i<methods.length;i++) {
404 if(Modifier.isPrivate(methods[i].getModifiers())) {
405 continue;
406 }
407 Method currentMethod = methods[i];
408 Class retval = currentMethod.getReturnType();
409 if(retval.equals(java.lang.Void.TYPE)) {
410 for(int j=0;j<listenerMethodNames.length;j++) {
411 if(currentMethod.getName().equals(listenerMethodNames[j])
412 && (absurdEventClassCheckName == null
413 || (currentMethod.getParameterTypes().length == 1
414 && ((currentMethod.getParameterTypes()[0]).getName().equals(absurdEventClassCheckName)
415 || (currentMethod.getParameterTypes()[0]).getName().endsWith("."+absurdEventClassCheckName)
416 )
417 )
418 )
419 ) {
420 chosenMethods.addElement(currentMethod);
421 listenerMethodFound[j] = true;
422 }
423 }
424 }
425 }
426
427 /* Make sure we found all the methods we were looking for. */
428 for(int i=0;i<listenerMethodFound.length;i++) {
429 if(!listenerMethodFound[i]) {
430 throw new IntrospectionException("Could not find event method " + listenerMethodNames[i]);
431 }
432 }
433
434 /* Now that we've chosen the listener methods we want, store them. */
435 this.listenerMethods = new Method[chosenMethods.size()];
436 for(int i=0;i<chosenMethods.size();i++) {
437 this.listenerMethods[i] = (Method)chosenMethods.elementAt(i);
438 }
439 }
440}
Note: See TracBrowser for help on using the repository browser.