/*******************************************************************************
 * Copyright (c) 2006, 2015 IBM Corporation 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:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/

package org.eclipse.ui;

import org.eclipse.ui.part.EditorPart;

/**
 * Represents a source of Saveable objects (units of saveability). Workbench
 * parts that show more than one unit of saveability, or whose units of
 * saveability change over time, should implement this interface in order to
 * provide better integration with workbench facilities like the Save command,
 * prompts to save on part close or shutdown, etc.
 * <p>
 * IMPORTANT: As of 3.2, implementers of <code>ISaveablesSource</code> must
 * satisfy the following conditions:
 * </p>
 * <ul>
 * <li>If ISaveablesSource is implemented by an IWorkbenchPart:
 * <ul>
 * <li>the part must implement <code>ISaveablePart</code></li>
 * <li>if any of its Saveable objects are dirty, the part must return
 * <code>true</code> from {@link ISaveablePart#isDirty()}</li>
 * <li>the part must return <code>true</code> from
 * {@link ISaveablePart#isSaveOnCloseNeeded()} if it is dirty (the default
 * behaviour implemented by {@link EditorPart})</li>
 * <li>the part must not implement {@link ISaveablePart2}</li>
 * </ul>
 * </li>
 * <li>If ISaveablesSource is implemented by a non-part (possible as of 3.2.1
 * and 3.3):
 * <ul>
 * <li>the Workbench's {@link ISaveablesLifecycleListener} (obtained from the
 * Workbench by calling
 * <code>workbench.getService(ISaveablesLifecycleListener.class)</code>) must be
 * notified of any change to the result of {@link #getSaveables()}</li>
 * <li>getActiveSaveables() should be implemented to return an empty array</li>
 * </ul>
 * </ul>
 * <p>
 * If any of these conditions are not met, it is undefined whether the Workbench
 * will prompt to save dirty Saveables when closing parts or the Workbench.
 * </p>
 * <p>
 * These conditions may be relaxed in future releases.
 * </p>
 *
 * @since 3.2
 */
public interface ISaveablesSource {

	/**
	 * Returns the saveables presented by the workbench part. If the return value of
	 * this method changes during the lifetime of this part (i.e. after
	 * initialization and control creation but before disposal) the part must notify
	 * an implicit listener using
	 * {@link ISaveablesLifecycleListener#handleLifecycleEvent(SaveablesLifecycleEvent)}.
	 * <p>
	 * Additions of saveables to the list of saveables of this part are announced
	 * using an event of type {@link SaveablesLifecycleEvent#POST_OPEN}. Removals
	 * are announced in a two-stage process, first using an event of type
	 * {@link SaveablesLifecycleEvent#PRE_CLOSE} followed by an event of type
	 * {@link SaveablesLifecycleEvent#POST_CLOSE}. Since firing the
	 * <code>PRE_CLOSE</code> event may trigger prompts to save dirty saveables, the
	 * cancellation status of the event must be checked by the part after the
	 * notification. When removing only non-dirty saveables, <code>POST_CLOSE</code>
	 * notification is sufficient.
	 * </p>
	 * <p>
	 * The listener is obtained from the part site by calling
	 * <code>partSite.getService(ISaveablesLifecycleListener.class)</code>.
	 * </p>
	 * <p>
	 * The part must not notify from its initialization methods (e.g.
	 * <code>init</code> or <code>createPartControl</code>), or from its dispose
	 * method. Parts that implement {@link IReusableEditor} must notify when their
	 * input is changed through {@link IReusableEditor#setInput(IEditorInput)}.
	 * </p>
	 *
	 * @return the saveables presented by the workbench part
	 *
	 * @see ISaveablesLifecycleListener
	 */
	Saveable[] getSaveables();

	/**
	 * Returns the saveables currently active in the workbench part.
	 * <p>
	 * Certain workbench actions, such as Save, target only the active saveables in
	 * the active part. For example, the active saveables could be determined based
	 * on the current selection in the part.
	 * </p>
	 *
	 * @return the saveables currently active in the workbench part
	 */
	Saveable[] getActiveSaveables();
}