| /******************************************************************************* |
| * 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; |
| } |
