/*******************************************************************************
 * Copyright (c) 2005, 2006 IBM Corporation 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:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.ltk.core.refactoring.history;

import java.io.InputStream;
import java.io.OutputStream;

import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IProgressMonitor;

import org.eclipse.core.resources.IProject;

import org.eclipse.ltk.core.refactoring.IRefactoringCoreStatusCodes;
import org.eclipse.ltk.core.refactoring.RefactoringCore;
import org.eclipse.ltk.core.refactoring.RefactoringDescriptor;
import org.eclipse.ltk.core.refactoring.RefactoringDescriptorProxy;
import org.eclipse.ltk.core.refactoring.RefactoringSessionDescriptor;

/**
 * Interface for a refactoring history service. A refactoring history service
 * provides methods to register refactoring history listeners, refactoring
 * execution listeners and facilities to query the global refactoring history
 * index for specific refactoring histories. Additionally, methods are provided
 * which read or write refactoring information. The refactoring history service
 * only returns refactorings which have contributed a refactoring descriptor via
 * their change object.
 * <p>
 * An instance of a refactoring history service may be obtained by calling
 * {@link RefactoringCore#getHistoryService()}.
 * </p>
 * <p>
 * All time stamps are measured as the milliseconds since January 1, 1970,
 * 00:00:00 GMT.
 * </p>
 * <p>
 * Note: this interface is not intended to be implemented by clients.
 * </p>
 * 
 * @see RefactoringCore
 * @see IRefactoringHistoryListener
 * @see IRefactoringExecutionListener
 * 
 * @see RefactoringHistory
 * @see RefactoringDescriptorProxy
 * 
 * @since 3.2
 */
public interface IRefactoringHistoryService {

	/**
	 * Adds the specified refactoring execution listener to this service.
	 * <p>
	 * If the listener is already registered with the service, nothing happens.
	 * </p>
	 * 
	 * @param listener
	 *            the listener to add
	 */
	public void addExecutionListener(IRefactoringExecutionListener listener);

	/**
	 * Adds the specified refactoring history listener to this service.
	 * <p>
	 * If the listener is already registered with the service, nothing happens.
	 * </p>
	 * 
	 * @param listener
	 *            the participant to add
	 */
	public void addHistoryListener(IRefactoringHistoryListener listener);

	/**
	 * Connects the refactoring history service to the workbench's operation
	 * history if necessary and increments an internal counter.
	 * <p>
	 * If the service is already connected, nothing happens.
	 * </p>
	 * <p>
	 * Every call to {@link #connect()} must be balanced with a corresponding
	 * call to {@link #disconnect()}.
	 * </p>
	 */
	public void connect();

	/**
	 * Disconnects the refactoring history service from the workbench's
	 * operation history if necessary and decrements an internal counter.
	 * <p>
	 * If the service is not connected, nothing happens. If the service is
	 * connected, all resources acquired since the corresponding call to
	 * {@link #connect()} are released.
	 * </p>
	 * <p>
	 * Every call to {@link #disconnect()} must be balanced with a corresponding
	 * call to {@link #connect()}.
	 * </p>
	 */
	public void disconnect();

	/**
	 * Returns a project refactoring history for the specified project.
	 * <p>
	 * Clients must connect to the refactoring history service first before
	 * calling this method.
	 * </p>
	 * 
	 * @param project
	 *            the project, which must exist
	 * @param monitor
	 *            the progress monitor to use, or <code>null</code> if no
	 *            progress monitoring or cancelation is desired
	 * @return the project refactoring history
	 */
	public RefactoringHistory getProjectHistory(IProject project, IProgressMonitor monitor);

	/**
	 * Returns a project refactoring history for the specified project.
	 * <p>
	 * Clients must connect to the refactoring history service first before
	 * calling this method.
	 * </p>
	 * <p>
	 * Note that calling this method with a flag argument unequal to
	 * <code>RefactoringDescriptor#NONE</code> may result in a performance
	 * degradation, since the actual descriptors have to be eagerly resolved.
	 * This in turn results in faster execution of any subsequent calls to
	 * {@link RefactoringDescriptorProxy#requestDescriptor(IProgressMonitor)}
	 * which try to request a descriptor from the returned refactoring history.
	 * </p>
	 * 
	 * @param project
	 *            the project, which must exist
	 * @param start
	 *            the start time stamp, inclusive
	 * @param end
	 *            the end time stamp, inclusive
	 * @param flags
	 *            the refactoring descriptor flags which must be present in
	 *            order to be returned in the refactoring history object, or
	 *            <code>RefactoringDescriptor#NONE</code>
	 * @param monitor
	 *            the progress monitor to use, or <code>null</code> if no
	 *            progress monitoring or cancelation is desired
	 * @return the project refactoring history
	 */
	public RefactoringHistory getProjectHistory(IProject project, long start, long end, int flags, IProgressMonitor monitor);

	/**
	 * Returns the combined refactoring history for the specified projects.
	 * <p>
	 * Clients must connect to the refactoring history service first before
	 * calling this method.
	 * </p>
	 * 
	 * @param projects
	 *            the projects, which must exist
	 * @param monitor
	 *            the progress monitor to use, or <code>null</code> if no
	 *            progress monitoring or cancelation is desired
	 * @return the combined refactoring history
	 */
	public RefactoringHistory getRefactoringHistory(IProject[] projects, IProgressMonitor monitor);

	/**
	 * Returns the combined refactoring history for the specified projects.
	 * <p>
	 * Clients must connect to the refactoring history service first before
	 * calling this method.
	 * </p>
	 * <p>
	 * Note that calling this method with a flag argument unequal to
	 * <code>RefactoringDescriptor#NONE</code> may result in a performance
	 * degradation, since the actual descriptors have to be eagerly resolved.
	 * This in turn results in faster execution of any subsequent calls to
	 * {@link RefactoringDescriptorProxy#requestDescriptor(IProgressMonitor)}
	 * which try to request a descriptor from the returned refactoring history.
	 * </p>
	 * 
	 * @param projects
	 *            the projects, which must exist
	 * @param start
	 *            the start time stamp, inclusive
	 * @param end
	 *            the end time stamp, inclusive
	 * @param flags
	 *            the refactoring descriptor flags which must be present in
	 *            order to be returned in the refactoring history object, or
	 *            <code>RefactoringDescriptor#NONE</code>
	 * @param monitor
	 *            the progress monitor to use, or <code>null</code> if no
	 *            progress monitoring or cancelation is desired
	 * @return the combined refactoring history
	 */
	public RefactoringHistory getRefactoringHistory(IProject[] projects, long start, long end, int flags, IProgressMonitor monitor);

	/**
	 * Returns the workspace refactoring history.
	 * <p>
	 * Clients must connect to the refactoring history service first before
	 * calling this method.
	 * </p>
	 * 
	 * @param monitor
	 *            the progress monitor to use, or <code>null</code> if no
	 *            progress monitoring or cancelation is desired
	 * @return the workspace refactoring history
	 */
	public RefactoringHistory getWorkspaceHistory(IProgressMonitor monitor);

	/**
	 * Returns the workspace refactoring history.
	 * <p>
	 * Clients must connect to the refactoring history service first before
	 * calling this method.
	 * </p>
	 * 
	 * @param start
	 *            the start time stamp, inclusive
	 * @param end
	 *            the end time stamp, inclusive
	 * @param monitor
	 *            the progress monitor to use, or <code>null</code> if no
	 *            progress monitoring or cancelation is desired
	 * @return the workspace refactoring history
	 */
	public RefactoringHistory getWorkspaceHistory(long start, long end, IProgressMonitor monitor);

	/**
	 * Reads a refactoring history from the input stream.
	 * <p>
	 * The resulting refactoring history contains resolved refactoring
	 * descriptors and should not be held on to.
	 * </p>
	 * <p>
	 * It is the responsibility of the caller to close the input stream.
	 * </p>
	 * 
	 * @param stream
	 *            a <code>UTF-8</code> input stream where to read the
	 *            refactoring history from
	 * @param flags
	 *            the refactoring descriptor flags to filter the refactoring
	 *            descriptors
	 * @return a refactoring history containing the filtered refactoring
	 *         descriptors
	 * @throws CoreException
	 *             if an error occurs while reading form the input stream.
	 *             Reasons include:
	 *             <ul>
	 *             <li>The input stream contains no version information for the
	 *             refactoring history.</li>
	 *             <li>The input stream contains an unsupported version of a
	 *             refactoring history.</li>
	 *             <li>An I/O error occurs while reading the refactoring
	 *             history from the input stream.</li>
	 *             </ul>
	 * 
	 * @see RefactoringDescriptor#NONE
	 * @see RefactoringDescriptor#STRUCTURAL_CHANGE
	 * @see RefactoringDescriptor#BREAKING_CHANGE
	 * 
	 * @see IRefactoringCoreStatusCodes#REFACTORING_HISTORY_IO_ERROR
	 * @see IRefactoringCoreStatusCodes#UNSUPPORTED_REFACTORING_HISTORY_VERSION
	 * @see IRefactoringCoreStatusCodes#MISSING_REFACTORING_HISTORY_VERSION
	 */
	public RefactoringHistory readRefactoringHistory(InputStream stream, int flags) throws CoreException;

	/**
	 * Removes the specified refactoring execution listener from this service.
	 * <p>
	 * If the listener is not registered with the service, nothing happens.
	 * </p>
	 * 
	 * @param listener
	 *            the listener to remove
	 */
	public void removeExecutionListener(IRefactoringExecutionListener listener);

	/**
	 * Removes the specified refactoring history listener from this service.
	 * <p>
	 * If the listener is not registered with the service, nothing happens.
	 * </p>
	 * 
	 * @param listener
	 *            the listener to remove
	 */
	public void removeHistoryListener(IRefactoringHistoryListener listener);

	/**
	 * Writes the specified refactoring descriptor proxies to the output stream.
	 * Refactoring descriptor proxies which cannot be resolved are automatically
	 * skipped.
	 * <p>
	 * It is the responsibility of the caller to close the output stream.
	 * </p>
	 * 
	 * @param proxies
	 *            the refactoring descriptor proxies
	 * @param stream
	 *            a <code>UTF-8</code> output stream where to write the
	 *            refactoring descriptors to
	 * @param flags
	 *            the flags which must be present in order to be written to the
	 *            output stream, or <code>RefactoringDescriptor#NONE</code>
	 * @param time
	 *            <code>true</code> to write time information associated with
	 *            the refactorings, <code>false</code> otherwise
	 * @param monitor
	 *            the progress monitor to use, or <code>null</code> if no
	 *            progress monitoring or cancelation is desired
	 * @throws CoreException
	 *             if an error occurs while writing to the output stream.
	 *             Reasons include:
	 *             <ul>
	 *             <li>The refactoring descriptors have an illegal format,
	 *             contain illegal arguments or otherwise illegal information.</li>
	 *             <li>An I/O error occurs while writing the refactoring
	 *             descriptors to the output stream.</li>
	 *             </ul>
	 * 
	 * @see RefactoringDescriptor#NONE
	 * @see RefactoringDescriptor#STRUCTURAL_CHANGE
	 * @see RefactoringDescriptor#BREAKING_CHANGE
	 * 
	 * @see IRefactoringCoreStatusCodes#REFACTORING_HISTORY_FORMAT_ERROR
	 * @see IRefactoringCoreStatusCodes#REFACTORING_HISTORY_IO_ERROR
	 */
	public void writeRefactoringDescriptors(RefactoringDescriptorProxy[] proxies, OutputStream stream, int flags, boolean time, IProgressMonitor monitor) throws CoreException;

	/**
	 * Writes the specified refactoring session descriptor to the output stream.
	 * <p>
	 * It is the responsibility of the caller to close the output stream.
	 * </p>
	 * 
	 * @param descriptor
	 *            the refactoring session descriptor to write
	 * @param stream
	 *            a <code>UTF-8</code> output stream where to write the
	 *            refactoring session to
	 * @param time
	 *            <code>true</code> to write time information associated with
	 *            the refactorings, <code>false</code> otherwise
	 * @throws CoreException
	 *             if an error occurs while writing to the output stream.
	 *             Reasons include:
	 *             <ul>
	 *             <li>The refactoring descriptors have an illegal format,
	 *             contain illegal arguments or otherwise illegal information.</li>
	 *             <li>An I/O error occurs while writing the refactoring
	 *             descriptors to the output stream.</li>
	 *             </ul>
	 * 
	 * @see IRefactoringCoreStatusCodes#REFACTORING_HISTORY_FORMAT_ERROR
	 * @see IRefactoringCoreStatusCodes#REFACTORING_HISTORY_IO_ERROR
	 */
	public void writeRefactoringSession(RefactoringSessionDescriptor descriptor, OutputStream stream, boolean time) throws CoreException;
}
