IIntentCallback.java

/*******************************************************************************
 * Copyright 2013 Geoscience Australia
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 ******************************************************************************/
package au.gov.ga.earthsci.intent;

import java.util.List;

/**
 * Callback of an {@link Intent}, used to get a result from the handling of an
 * Intent. This called by an {@link IIntentHandler} to notify the caller of the
 * result.
 * 
 * @author Michael de Hoog (michael.dehoog@ga.gov.au)
 */
public interface IIntentCallback
{
	/**
	 * Called by the Intent manager after it has calculated which filters can
	 * handle the given intent. If multiple filters are found, the intent system
	 * will display a dialog, allowing the user to select which filter to use.
	 * The dialog is shown after this function is called. If <code>false</code>
	 * is returned, the intent is canceled (and the dialog is not shown).
	 * 
	 * @param filters
	 *            Filters that can handle the intent
	 * @param intent
	 *            Intent for which the filters have been found
	 * @return True if the intent should continue, false to cancel the intent
	 */
	boolean filters(List<IntentFilter> filters, Intent intent);

	/**
	 * Called by the Intent manager immediately prior to calling a filter's
	 * intent handler (ie starting the intent). If <code>false</code> is
	 * returned, the intent is canceled.
	 * 
	 * @param filter
	 *            Filter that has been selected to handle the intent
	 * @param handler
	 *            Handler that will handle the intent
	 * @param intent
	 *            Intent that will be started
	 * @return True if the intent should continue, false to cancel the intent
	 */
	boolean starting(IntentFilter filter, IIntentHandler handler, Intent intent);

	/**
	 * Called by the Intent handler when it has completed successfully. If the
	 * handler didn't produce a result, result will be null.
	 * <p/>
	 * If the result is of an unknown type, it should be handled gracefully,
	 * such as passing it to the dispatch system.
	 * <p/>
	 * It is possible for this to be called twice. For example, if the Intent
	 * handler loads a result from a cache, and then the cache is refreshed by
	 * retrieving a newer version, this will also be called with the newer
	 * result.
	 * 
	 * @param result
	 *            Result of the Intent
	 * @param intent
	 *            Intent that completed
	 */
	void completed(Object result, Intent intent);

	/**
	 * Called when the Intent handler failed with an error.
	 * 
	 * @param e
	 *            Error generated from handling the Intent
	 * @param intent
	 *            Intent that failed
	 */
	void error(Exception e, Intent intent);

	/**
	 * Called by the Intent handler when it is canceled.
	 * <p/>
	 * For example, could mean that a retrieval required to complete the intent
	 * was canceled.
	 * 
	 * @param intent
	 *            Intent whose handler was canceled
	 */
	void canceled(Intent intent);

	/**
	 * Called by the Intent handler when it is aborted.
	 * <p/>
	 * Generally means that the user canceled an interactive intent handler.
	 * This method should clean up any model changed, as if the Intent never
	 * occurred.
	 * 
	 * @param intent
	 *            Intent whose handler was aborted
	 */
	void aborted(Intent intent);
}