001: /* *************************************************************************
002:
003: Millstone(TM)
004: Open Sourced User Interface Library for
005: Internet Development with Java
006:
007: Millstone is a registered trademark of IT Mill Ltd
008: Copyright (C) 2000-2005 IT Mill Ltd
009:
010: *************************************************************************
011:
012: This library is free software; you can redistribute it and/or
013: modify it under the terms of the GNU Lesser General Public
014: license version 2.1 as published by the Free Software Foundation.
015:
016: This library is distributed in the hope that it will be useful,
017: but WITHOUT ANY WARRANTY; without even the implied warranty of
018: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019: Lesser General Public License for more details.
020:
021: You should have received a copy of the GNU Lesser General Public
022: License along with this library; if not, write to the Free Software
023: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
024:
025: *************************************************************************
026:
027: For more information, contact:
028:
029: IT Mill Ltd phone: +358 2 4802 7180
030: Ruukinkatu 2-4 fax: +358 2 4802 7181
031: 20540, Turku email: info@itmill.com
032: Finland company www: www.itmill.com
033:
034: Primary source for MillStone information and releases: www.millstone.org
035:
036: ********************************************************************** */
037:
038: package org.millstone.base.event;
039:
040: import java.lang.reflect.Method;
041:
042: /** <p>Interface for classes supporting registeration of methods as event
043: * receivers.</p>
044: *
045: * <p>For more information on the MillStone inheritable event mechanism
046: * see the
047: * {@link org.millstone.base.event org.millstone.base.event package documentation}.</p>
048: *
049: * @author IT Mill Ltd.
050: * @version 3.1.1
051: * @since 3.0
052: */
053: public interface MethodEventSource {
054:
055: /** <p>Registers a new event listener with the specified activation
056: * method to listen events generated by this component. If the
057: * activation method does not have any arguments the event object will
058: * not be passed to it when it's called.</p>
059: *
060: * <p>For more information on the MillStone inheritable event mechanism
061: * see the
062: * {@link org.millstone.base.event org.millstone.base.event package documentation}.</p>
063: *
064: * @param eventType type of the listened event. Events of this type or
065: * its subclasses activate the listener.
066: * @param object the object instance who owns the activation method
067: * @param method the activation method
068: * @throws java.lang.IllegalArgumentException unless <code>method</code>
069: * has exactly one match in <code>object</code>
070: */
071: public void addListener(Class eventType, Object object,
072: Method method);
073:
074: /** <p>Registers a new listener with the specified activation method to
075: * listen events generated by this component. If the activation method
076: * does not have any arguments the event object will not be passed to it
077: * when it's called.</p>
078: *
079: * <p>This version of <code>addListener</code> gets the name of the
080: * activation method as a parameter. The actual method is reflected from
081: * <code>object</code>, and unless exactly one match is found,
082: * <code>java.lang.IllegalArgumentException</code> is thrown.</p>
083: *
084: * <p>For more information on the MillStone inheritable event mechanism
085: * see the
086: * {@link org.millstone.base.event org.millstone.base.event package documentation}.</p>
087: *
088: * @param eventType type of the listened event. Events of this type or
089: * its subclasses activate the listener.
090: * @param object the object instance who owns the activation method
091: * @param methodName the name of the activation method
092: * @throws java.lang.IllegalArgumentException unless <code>method</code>
093: * has exactly one match in <code>object</code>
094: */
095: public void addListener(Class eventType, Object object,
096: String methodName);
097:
098: /** Removes all registered listeners matching the given parameters.
099: * Since this method receives the event type and the listener object as
100: * parameters, it will unregister all <code>object</code>'s methods that
101: * are registered to listen to events of type <code>eventType</code>
102: * generated by this component.
103: *
104: * <p>For more information on the MillStone inheritable event mechanism
105: * see the
106: * {@link org.millstone.base.event org.millstone.base.event package documentation}.</p>
107: *
108: * @param eventType exact event type the <code>object</code> listens to
109: * @param target target object that has registered to listen to events
110: * of type <code>eventType</code> with one or more methods
111: */
112: public void removeListener(Class eventType, Object target);
113:
114: /** Removes one registered listener method. The given method owned by
115: * the given object will no longer be called when the specified events
116: * are generated by this component.
117: *
118: * <p>For more information on the MillStone inheritable event mechanism
119: * see the
120: * {@link org.millstone.base.event org.millstone.base.event package documentation}.</p>
121: *
122: * @param eventType exact event type the <code>object</code> listens to
123: * @param target target object that has registered to listen to events
124: * of type <code>eventType</code> with one or more methods
125: * @param method the method owned by <code>target</code> that's
126: * registered to listen to events of type <code>eventType</code>
127: */
128: public void removeListener(Class eventType, Object target,
129: Method method);
130:
131: /** <p>Removes one registered listener method. The given method owned by
132: * the given object will no longer be called when the specified events
133: * are generated by this component.</p>
134: *
135: * <p>This version of <code>removeListener</code> gets the name of the
136: * activation method as a parameter. The actual method is reflected from
137: * <code>target</code>, and unless exactly one match is found,
138: * <code>java.lang.IllegalArgumentException</code> is thrown.</p>
139: *
140: * <p>For more information on the MillStone inheritable event mechanism
141: * see the
142: * {@link org.millstone.base.event org.millstone.base.event package documentation}.</p>
143: *
144: * @param eventType exact event type the <code>object</code> listens to
145: * @param target target object that has registered to listen to events
146: * of type <code>eventType</code> with one or more methods
147: * @param methodName name of the method owned by <code>target</code>
148: * that's registered to listen to events of type <code>eventType</code>
149: */
150: public void removeListener(Class eventType, Object target,
151: String methodName);
152: }
|