/*
* Copyright 2000-2016 Vaadin Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.vaadin.event;
import java.io.Serializable;
import java.lang.reflect.Method;
import com.vaadin.shared.Registration;
/**
* <p>
* Interface for classes supporting registration of methods as event receivers.
* </p>
*
* <p>
* For more information on the inheritable event mechanism see the
* {@link com.vaadin.event com.vaadin.event package documentation}.
* </p>
*
* @author Vaadin Ltd.
* @since 3.0
*/
public interface MethodEventSource extends Serializable {
/**
* <p>
* Registers a new event listener with the specified activation method to
* listen events generated by this component. If the activation method does
* not have any arguments the event object will not be passed to it when
* it's called.
* </p>
*
* <p>
* For more information on the inheritable event mechanism see the
* {@link com.vaadin.event com.vaadin.event package documentation}.
* </p>
*
* @param eventType
* the type of the listened event. Events of this type or its
* subclasses activate the listener.
* @param object
* the object instance who owns the activation method.
* @param method
* the activation method.
* @return a registration object for removing the listener
* @throws java.lang.IllegalArgumentException
* unless <code>method</code> has exactly one match in
* <code>object</code>
* @throws NullPointerException
* if {@code object} is {@code null}
* @since 8.0
*/
public Registration addListener(Class<?> eventType, Object object,
Method method);
/**
* <p>
* Registers a new listener with the specified activation method to listen
* events generated by this component. If the activation method does not
* have any arguments the event object will not be passed to it when it's
* called.
* </p>
*
* <p>
* This version of <code>addListener</code> gets the name of the activation
* method as a parameter. The actual method is reflected from
* <code>object</code>, and unless exactly one match is found,
* <code>java.lang.IllegalArgumentException</code> is thrown.
* </p>
*
* <p>
* For more information on the inheritable event mechanism see the
* {@link com.vaadin.event com.vaadin.event package documentation}.
* </p>
*
* @param eventType
* the type of the listened event. Events of this type or its
* subclasses activate the listener.
* @param object
* the object instance who owns the activation method.
* @param methodName
* the name of the activation method.
* @return a registration object for removing the listener
* @throws java.lang.IllegalArgumentException
* unless <code>method</code> has exactly one match in
* <code>object</code>
* @throws NullPointerException
* if {@code object} is {@code null}
* @since 8.0
*/
public Registration addListener(Class<?> eventType, Object object,
String methodName);
/**
* Removes all registered listeners matching the given parameters. Since
* this method receives the event type and the listener object as
* parameters, it will unregister all <code>object</code>'s methods that are
* registered to listen to events of type <code>eventType</code> generated
* by this component.
*
* <p>
* For more information on the inheritable event mechanism see the
* {@link com.vaadin.event com.vaadin.event package documentation}.
* </p>
*
* @param eventType
* the exact event type the <code>object</code> listens to.
* @param target
* the target object that has registered to listen to events of
* type <code>eventType</code> with one or more methods.
*/
public void removeListener(Class<?> eventType, Object target);
/**
* Removes one registered listener method. The given method owned by the
* given object will no longer be called when the specified events are
* generated by this component.
*
* <p>
* For more information on the inheritable event mechanism see the
* {@link com.vaadin.event com.vaadin.event package documentation}.
* </p>
*
* @param eventType
* the exact event type the <code>object</code> listens to.
* @param target
* the target object that has registered to listen to events of
* type eventType with one or more methods.
* @param method
* the method owned by the target that's registered to listen to
* events of type eventType.
* @deprecated use a {@link Registration} returned by
* {@link #addListener(Class, Object, Method)}
*/
@Deprecated
public void removeListener(Class<?> eventType, Object target,
Method method);
/**
* <p>
* Removes one registered listener method. The given method owned by the
* given object will no longer be called when the specified events are
* generated by this component.
* </p>
*
* <p>
* This version of <code>removeListener</code> gets the name of the
* activation method as a parameter. The actual method is reflected from the
* target, and unless exactly one match is found,
* <code>java.lang.IllegalArgumentException</code> is thrown.
* </p>
*
* <p>
* For more information on the inheritable event mechanism see the
* {@link com.vaadin.event com.vaadin.event package documentation}.
* </p>
*
* @param eventType
* the exact event type the <code>object</code> listens to.
* @param target
* the target object that has registered to listen to events of
* type <code>eventType</code> with one or more methods.
* @param methodName
* the name of the method owned by <code>target</code> that's
* registered to listen to events of type <code>eventType</code>.
* @deprecated use a {@link Registration} returned by
* {@link #addListener(Class, Object, String)}
*/
@Deprecated
public void removeListener(Class<?> eventType, Object target,
String methodName);
}