ca.odell.glazedlists.event.ListEventListener Maven / Gradle / Ivy

/* Glazed Lists                                                 (c) 2003-2006 */
/* http://publicobject.com/glazedlists/                      publicobject.com,*/
/*                                                     O'Dell Engineering Ltd.*/
package ca.odell.glazedlists.event;

// standard java event and observer
import java.util.EventListener;

/**
 * Listens and responds to changes in a dynamic list of objects. This could be
 * implemented by a GUI widget such as a table or combo box to repaint, add, or
 * remove elements when the underlying data changes.
 *
 * List changes are represented by a {@link ListEvent}.
 *
 * 
When a thread requires notification on the Swing thread for GUI display, the
 * user should not add the implementation of this interface as a listener
 * directly. Instead use a EventThreadProxy, which receives
 * events on the list thread and then fires them on the Swing thread.
 *
 * @see Glazed Lists Tutorial
 * @see ListEvent
 *
 * @author Jesse Wilson
 */
public interface ListEventListener extends EventListener {

    /**
     * When the underlying list changes, this notification allows the
     * object to repaint itself or update itself as necessary.
     *
     * It is mandatory that the calling thread has obtained the write lock
     * on the source list. This is because the calling thread will have written
     * to the source list to cause this event. This condition guarantees that
     * no writes can occur while the listener is handling this event.
     * It is an error to write to the source list while processing an event.
     *
     * @param listChanges a {@link ListEvent} describing the changes to the list
     */
    public void listChanged(ListEvent listChanges);
}