org.eclipse.jface.viewers.deferred.IConcurrentModel Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.jface Show documentation
This is org.eclipse.jface jar used by Scout SDK
The newest version!
/*******************************************************************************
 * Copyright (c) 2004, 2015 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.viewers.deferred;


/**
 * Interface for a set of unordered elements that can fire change notifications.
 * IConcurrentModel returns its contents asynchronous. Rather than implementing
 * "get" methods, listeners can request an update and the model fires back
 * information at its earliest convenience.
 *
 * 
 * The model is allowed to send back notifications to its listeners in any thread,
 * and the listeners must not assume that the notifications will arrive in the UI
 * thread.
 * 
 *
 * 
 * Not intended to be implemented by clients. Clients should subclass
 * AbstractConcurrentModel instead.
 * 
 *
 * @since 3.1
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IConcurrentModel {

    /**
     * Requests that the receiver to call the given listener's setContents(...)
     * method at its earliest convenience. The receiver is allowed to compute the
     * elements asynchronously. That is, it can compute the result in a background
     * thread and call setContents(...) once the result is ready. If the result is
     * too large to return in one batch, it can call setContents with an empty array
     * followed by a sequence of adds.
     * 
     * Has no effect if an update is already queued for an identical listener.
     * 
     *
     * @param listener listener whose setContents method should be called. The
     * listener must have been previously registered with addListener.
     */
    public void requestUpdate(IConcurrentModelListener listener);

    /**
     * Adds a listener to this model. The listener should be given the model's
     * current contents (either through setContents or a sequence of adds) at the
     * receiver's earliest convenience. The receiver will notify the listener
     * about any changes in state until the listener is removed.
     *
     * 
     * Has no effect if an identical listener is already registered.
     * 
     *
     * @param listener listener to add
     */
    public void addListener(IConcurrentModelListener listener);

    /**
     * Removes a listener from this model. The receiver will stop sending
     * notifications to the given listener as soon as possible (although
     * some additional notifications may still if arrive if the receiver
     * was in the process of sending notifications in another thread).
     * Any pending updates for this listener will be cancelled.
     * 
     * Has no effect if the given listener is not known to this model.
     * 
     *
     * @param listener listener to remove
     */
    public void removeListener(IConcurrentModelListener listener);
}