/* ******************************************************************************
* Copyright (c) 2006-2012 XMind Ltd. and others.
*
* This file is a part of XMind 3. XMind releases 3 and
* above are dual-licensed under the Eclipse Public License (EPL),
* which is available at http://www.eclipse.org/legal/epl-v10.html
* and the GNU Lesser General Public License (LGPL),
* which is available at http://www.gnu.org/licenses/lgpl.html
* See http://www.xmind.net/license.html for details.
*
* Contributors:
* XMind Ltd. - initial API and implementation
*******************************************************************************/
package org.xmind.core.command;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.IStatus;
import org.osgi.util.tracker.ServiceTracker;
/**
* The command handling service. The service will look up registered command
* handlers and delegate the execution of the command to the best matched
* command handler.
*
* <p>
* Note that <code>ICommandHandler</code> and <code>IReturnValueConsumer</code>
* must take the responsibility to stop execution when the cancellation of the
* given progress monitor is detected.
* </p>
*
* <p>
* To register a command handler, extend the
* <code>org.xmind.core.command.handlers</code> extension point.
* </p>
*
* <p>
* This service is registered as an OSGi service, so it can be retrieved via
* {@link ServiceTracker}. Example:
*
* <pre>
* ServiceTracker commandServiceTracker;
*
* public void start(BundleContext bundleContext) throws Exception {
* commandServiceTracker = new ServiceTracker(bundleContext,
* ICommandService.class.getName(), null);
* commandServiceTracker.open();
* }
*
* public void stop(BundleContext bundleContext) throws Exception {
* if (commandServiceTracker != null) {
* commandServiceTracker.close();
* commandServiceTracker = null;
* }
* }
*
* public ICommandService getCommandService() {
* if (commandServiceTracker != null) {
* return (ICommandService) commandServiceTracker.getService();
* }
* return null;
* }
* </pre>
*
* </p>
*
* @author Frank Shaka
* @since 3.4.0
* @see ICommandHandler
*/
public interface ICommandService {
/**
* Integer constant indicating that no handlers are available for executing
* a command. Value is <code>10001</code>. Used as the 'code' of a return
* value with {@link IStatus#WARNING} severity.
*/
int CODE_NO_HANDLERS = 10001;
/**
* Integer constant indicating that a command is not handled by any of the
* handlers. Value is <code>10002</code>. Used as the 'code' of a return
* value with {@link IStatus#WARNING} severity.
*/
int CODE_NOT_HANDLED = 10002;
/**
* Executes a command synchronously. This method may take a long time to
* finish and will block the current thread, so it is recommended to run it
* in a separate thread of an {@link org.eclipse.core.runtime.jobs.Job}.
*
* <p>
* The return value may contain cached resources which is cleaned right
* before the method <code>execute()</code> returns, so the client may want
* to pass in an <code>IReturnValueConsumer</code> to consume the cached
* resources before they are cleaned.
* </p>
*
* @param monitor
* the progress monitor, or <code>null</code> if the progress
* monitoring is not required
* @param command
* the command to handle
* @param returnValueConsumer
* the return value consumer
* @return the return value, never <code>null</code>
*/
IStatus execute(IProgressMonitor monitor, ICommand command,
IReturnValueConsumer returnValueConsumer);
}