path: root/tests/plugins/org.eclipse.tcf.debug.test/src/org/eclipse/tcf/debug/test/util/Callback.java

/*******************************************************************************
 * Copyright (c) 2006, 2012 Wind River Systems 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:
 *     Wind River Systems - initial API and implementation
 *******************************************************************************/
package org.eclipse.tcf.debug.test.util;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CancellationException;

import org.eclipse.tcf.protocol.Protocol;

/**
 * Copied and apdapted from org.eclipse.cdt.dsf.concurrent.
 * 
 * Used to monitor the result of an asynchronous request.  Because of the
 * asynchronous nature of DSF code, a very large number of methods needs to 
 * signal the result of an operation through a call-back.  This class is the base 
 * class for such call backs.  
 * <p>
 * The intended use of this class, is that a client who is calling an asynchronous 
 * method, will sub-class Callback, and implement the method {@link #handleCompleted()}, 
 * or any of the other <code>handle...</code> methods, in order to interpret the 
 * results of the request.  The object implementing the asynchronous method is required 
 * to call the {@link #done()} method on the request monitor object that it received 
 * as an argument.  
 * </p>
 * <p>
 * The error the returned by #getError() can be used to 
 * determine the success or failure of the asynchronous operation.  By convention
 * the error value returned by asynchronous method should be interpreted as follows:
 * <ul>
 * <li><code>null</code> - Result is a success.  In DataCallback, getData() should
 *     return a value.</li>
 * <li>non-<code>null</code> - An error condition that should probably be reported 
 *     to the user.</li>
 * <li><code>CancellationException</code> - The request was canceled, and the 
 *     asynchronous method was not completed.</li>
 * </ul>  
 * </p>
 * <p>
 * The Callback constructor accepts an optional "parent" request monitor.  If a 
 * parent monitor is specified, it will automatically be invoked by this monitor when 
 * the request is completed.  The parent option is useful when implementing a method 
 * which is asynchronous (and accepts a request monitor as an argument) and which itself 
 * calls another asynchronous method to complete its operation.  For example, in the 
 * request monitor implementation below, the implementation only needs to override 
 * <code>handleSuccess()</code>, because the base implementation will handle notifying the 
 * parent <code>rm</code> in case the <code>getIngredients()</code> call fails. 
 * <pre>
 *     public void createCupCakes(final DataCallback<CupCake[]> rm) {
 *         getIngredients(new DataCallback<Ingredients>(fExecutor, rm) {
 *                 public void handleSuccess() {
 *                     rm.setData( new CupCake(getData().getFlour(), getData().getSugar(), 
 *                                             getData().getBakingPowder()));
 *                     rm.done();  
 *                 }
 *             });
 *     }
 * </pre>
 * </p>
 * 
 * @since 1.0
 */
public class Callback {
    
    /**
     * Interface used by Callback to notify when a given request monitor
     * is canceled.  
     * 
     * @see Callback
     */
    public static interface ICanceledListener {
        
        /**
         * Called when the given request monitor is canceled.
         */
        public void requestCanceled(Callback rm);
    }

    /**
     * The request monitor which was used to call into the method that created this 
     * monitor.  
     */
    private final Callback fParentCallback;

    private List<ICanceledListener> fCancelListeners;
    
    /**
     * Status 
     */
    private Throwable fError = null;
    private boolean fCanceled = false;
    private boolean fDone = false;

    private final ICanceledListener fCanceledListener;
    
	/**
	 * This field is never read by any code; its purpose is strictly to assist
	 * developers debug DPF code. Developer can select this field in the
	 * Variables view and see a monitor backtrace in the details pane. See
	 * {@link DsfExecutable#DEBUG_MONITORS}.
	 * 
	 * <p>
	 * This field is set only when tracing is enabled.
	 */
	@SuppressWarnings("unused")
	private String fMonitorBacktrace;

    public Callback() {
        this(null);
    }
	
	/**
	 * Constructor with an optional parent monitor.
	 * 
	 * @param executor
	 *            This executor will be used to invoke the runnable that will
	 *            allow processing the completion code of this request monitor.
	 *            I.e., the runnable will call {@link #handleCompleted()}.
	 * @param parentCallback
	 *            An optional parent request monitor. By default, our completion
	 *            handlers invoke the parent monitor's <code>done</code> method,
	 *            thus allowing monitors to be daisy chained. If this request is
	 *            unsuccessful, its status is set into the parent monitor.
	 *            Parameter may be null.
	 */
    public Callback(Callback parentCallback) {
        fParentCallback = parentCallback;
        
        // If the parent rm is not null, add ourselves as a listener so that 
        // this request monitor will automatically be canceled when the parent
        // is canceled.
        if (fParentCallback != null) {
            fCanceledListener = new ICanceledListener() {
                public void requestCanceled(Callback rm) {
                    cancel();
                }
            };

            fParentCallback.addCancelListener(fCanceledListener);
        } else {
            fCanceledListener = null;
        }
    }
    
    /** 
     * Sets the status of the result of the request.  If status is OK, this 
     * method does not need to be called. 
     */
    public synchronized void setError(Throwable error) { 
        fError = error; 
    }
    
    /** Returns the status of the completed method. */
    public synchronized Throwable getError() {
        if (isCanceled()) {
            return new CancellationException();
        }
        return fError; 
    }

	/**
	 * Sets this request monitor as canceled and calls the cancel listeners if
	 * any.
	 * <p>
	 * Note: Calling cancel() does not automatically complete the
	 * Callback. The asynchronous call still has to call done().
	 * </p>
	 * <p>
	 * Note: logically a request should only be canceled by the client that
	 * issued the request in the first place. After a request is canceled, the
	 * method that is fulfilling the request may call
	 * {@link #setError(Throwable)} with <code>CancelledException</code>
	 * to indicate that it recognized that the given request was canceled and it
	 * did not perform the given operation.
	 * </p>
	 * <p>
	 * Canceling a monitor effectively cancels all descendant monitors, by
	 * virtue of the default implementation of {@link #isCanceled()}, which
	 * checks not only its own state but that of its parent. However, only the
	 * cancel listeners of the monitor directly canceled will be called.
	 * </p>
	 */
    public void cancel() {
        ICanceledListener[] listeners = null;
        synchronized (this) {
            // Check to make sure the request monitor wasn't previously canceled.
            if (!fCanceled) {
                fCanceled = true;
                if (fCancelListeners != null) {
                    listeners = fCancelListeners.toArray(new ICanceledListener[fCancelListeners.size()]);
                }
            }
        }

        // Call the listeners outside of a synchronized section to reduce the 
        // risk of deadlocks.
        if (listeners != null) {
            for (ICanceledListener listener : listeners) {
                listener.requestCanceled(this);
            }
        }
    }
    
    /**
     * Returns whether the request was canceled.  Even if the request is
     * canceled by the client, the implementor handling the request should 
     * still call {@link #done()} in order to complete handling 
     * of the request monitor. 
     * 
     * <p>
     * A request monitor is considered canceled if either it or its parent was canceled.
     * </p> 
     */
    public boolean isCanceled() {
        boolean canceled = false;
        
        // Avoid holding onto this lock while calling parent RM, which may 
        // acquire other locks (bug 329488).
        synchronized(this) {
            canceled = fCanceled;
        }
        return canceled || (fParentCallback != null && fParentCallback.isCanceled());
    }
    
    /**
     * Adds the given listener to list of listeners that are notified when this 
     * request monitor is directly canceled.
     */
    public synchronized void addCancelListener(ICanceledListener listener) {
        if (fCancelListeners == null) {
            fCancelListeners = new ArrayList<ICanceledListener>(1);
        }
        fCancelListeners.add(listener);
    }

    /**
     * Removes the given listener from the list of listeners that are notified 
     * when this request monitor is directly canceled.
     */
    public synchronized void removeCancelListener(ICanceledListener listener) {
        if (fCancelListeners != null) {
            fCancelListeners.remove(listener);
        }
    }

    public void done(Throwable error) {
        setError(error);
        done();
    }
    
    /**
     * Marks this request as completed.  Once this method is called, the
     * monitor submits a runnable to the DSF Executor to call the 
     * <code>handle...</code> methods.  
     * <p>
     * Note: This method should be called once and only once, for every request 
     * issued.  Even if the request was canceled.
     * </p>  
     */
    public void done() {
        synchronized(this) {
            assert Protocol.getEventQueue().isDispatchThread();
            
            if (fDone) {
                throw new IllegalStateException("Callback: " + this + ", done() method called more than once");  //$NON-NLS-1$//$NON-NLS-2$
            }
            fDone = true;
            
            // This Callback is done, it can no longer be canceled.
            // We must clear the list of cancelListeners because it causes a
            // circular reference between parent and child Callback, which
            // causes a memory leak.
            fCancelListeners = null;
            
            if (fParentCallback != null) {
                fParentCallback.removeCancelListener(fCanceledListener);
            }
        }
        
        handleCompleted();
    }

    @Override
    public String toString() {
        return "Callback (" + super.toString() + "): " + getError(); //$NON-NLS-1$ //$NON-NLS-2$
    }

	/**
	 * Checks whether the given request monitor completed with success or
	 * failure result. If the request monitor was canceled it is considered a
	 * failure, regardless of the status. If the status has a severity higher
	 * than INFO (i.e., WARNING, ERROR or CANCEL), it is considered a failure.
	 */
    public synchronized boolean isSuccess() {
        return !isCanceled() && getError() == null ; 
    }

	/**
	 * First tier handler for the completion of the request. By default, the
	 * {@link #done()} method drives this method on the executor specified at
	 * construction time. By default, this handler merely calls a more
	 * specialized handler, which in turn may call an even more specialized
	 * handler, and so on, thus giving a subclass the ability to
	 * compartmentalize its completion logic by overriding specific handlers.
	 * All handlers are named <code>handleXxxxx</code>. More specifically, the
	 * base implementation calls {@link #handleSuccess()} if the request
	 * succeeded, and calls {@link #handleFailure()} otherwise. <br>
	 * 
	 * The complete hierarchy of handlers is as follows: <br>
	 * <pre>
	 * + handleCompleted 
	 *   - handleSuccess 
	 *   + handleFailure 
	 *     - handleCancel
	 *     + handleErrororWarning 
	 *       - handleError 
	 *       - handleWarning
	 * </pre>
	 * 
	 * <p>
	 * Note: Sub-classes may override this method.
	 */
    protected void handleCompleted() {
        if (isSuccess()) {
            handleSuccess();
        } else {
            handleFailure();
        } 
    }
    
    /**
     * Default handler for a successful the completion of a request.  If this 
     * monitor has a parent monitor that was configured by the constructor, that 
     * parent monitor is notified.  Otherwise this method does nothing. 
     * {@link #handleFailure()} or cancel otherwise.
     * <br>
     * Note: Sub-classes may override this method.
     */
    protected void handleSuccess() {
        if (fParentCallback != null) {
            fParentCallback.done();
        }
    }
    
    /**
     * The default implementation of a cancellation or an error result of a 
     * request.  The implementation delegates to {@link #handleCancel()} and
     * {@link #handleErrorOrWarning()} as needed.
     * <br>
     * Note: Sub-classes may override this method.
     */
    protected void handleFailure() {
        assert !isSuccess();
        
        if (isCanceled()) {
            handleCancel();
        } else {
            handleError();
        } 
    }
    
    /**
     * The default implementation of an error result of a request.  If this 
     * monitor has a parent monitor that was configured by the constructor, that 
     * parent monitor is configured with a new status containing this error.
     * Otherwise the error is logged.  
     * <br>
     * Note: Sub-classes may override this method.
     */    
    protected void handleError() {
        if (fParentCallback != null) {
            fParentCallback.setError(getError());
            fParentCallback.done();
        } else {
            Protocol.log("Unhandled error in callback " + toString(), getError());
        }
    }
    

	/**
	 * Default completion handler for a canceled request. If this monitor was
	 * constructed with a parent monitor, the status is propagated up to it.
	 * Otherwise this method does nothing. <br>
	 * Note: Sub-classes may override this method.
	 */
    protected void handleCancel() {
        if (fParentCallback != null) {
            if (getError() instanceof CancellationException && !fParentCallback.isCanceled()) {
                Protocol.log("Sub-request " + toString() + " was canceled and not handled.'", getError());
            } else {
                fParentCallback.setError(getError());
            }
            fParentCallback.done();
        }
    }
}