/*******************************************************************************
 * Copyright (c) 2006, 2015 Wind River Systems and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     Wind River Systems - initial API and implementation
 *******************************************************************************/
package org.eclipse.cdt.dsf.debug.service.command;

import org.eclipse.cdt.dsf.concurrent.ConfinedToDsfExecutor;

/**
 * Synchronous listener to commands being sent and received.
 * All the registered listeners will be called in the same
 * dispatch cycle as when the result of the command is submitted.
 *
 * @since 1.0
 */

@ConfinedToDsfExecutor("")
public interface ICommandListener {
	/**
	 * Notifies that the specified command has been added to the Command Queue.
	 * It has not yet been sent. In this state the command can be examined  and
	 * possibly withdrawn because it has been coalesced with another command.
	 *
	 * @return None
	 * @param command Command which has been added to the Queue
	 */
	public void commandQueued(ICommandToken token);

	/**
	 * Notification that the given command was sent to the debugger. At this
	 * point the command is no longer in the Command Queue and should not be
	 * examined. The only thing which can be done is to try and cancel the
	 * command.
	 *
	 * @return None
	 * @param command
	 */
	public void commandSent(ICommandToken token);

	/**
	 * Notifies that the specified command has been removed from the
	 * Command Queue. This notification means that the command has
	 * been removed from the queue and not sent to the backend. The
	 * user has specifically removed it, perhaps because it has been
	 * combined with another. Or some state change has occurred and
	 * there is no longer a need to get this particular set of data.
	 *
	 * @return None
	 * @param Command which has been sent to the backend
	 */
	public void commandRemoved(ICommandToken token);

	/**
	 * Notifies that the specified command has been completed.
	 *
	 * @return None
	 * @param Command which has been sent to the backend
	 */
	public void commandDone(ICommandToken token, ICommandResult result);
}
