org.eclipse.platform/org.eclipse.ltk.core.refactoring/3.10.300 : org/eclipse/ltk/core/refactoring/history/IRefactoringHistoryService.java

IRefactoringHistoryService

http://www.eclipse.org/platform: Refactoring Core (Eclipse Foundation)

Eclipse Public License - v 2.0

Copyright (c) 2005, 2008 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
/*******************************************************************************
 * Copyright (c) 2005, 2008 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.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.
 An instance of a refactoring history service may be obtained by calling RefactoringCore.getHistoryService(). 

All time stamps are measured as the milliseconds since January 1, 1970,
00:00:00 GMT.


Note: this interface is not intended to be implemented by clients.

See Also: RefactoringCore
IRefactoringHistoryListener
IRefactoringExecutionListener
RefactoringHistory
RefactoringDescriptorProxy
Since: 3.2
@noimplement This interface is not intended to be implemented by clients.
@noextend This interface is not intended to be extended by clients./**
 * 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
 *
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IRefactoringHistoryService {

	Adds the specified refactoring execution listener to this service.

If the listener is already registered with the service, nothing happens.

Params: listener – 
           the listener to add/**
	 * 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.

If the listener is already registered with the service, nothing happens.

Params: listener – 
           the listener to add/**
	 * 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 listener 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.

If the service is already connected, nothing happens.

 Every call to connect() must be balanced with a corresponding call to disconnect(). 
/**
	 * 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.
 If the service is not connected, nothing happens. If the service is connected, all resources acquired since the corresponding call to connect() are released. 
 Every call to disconnect() must be balanced with a corresponding call to 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.

Clients must connect to the refactoring history service first before
calling this method.

Params: project – 
           the project, which must exist
monitor – 
           the progress monitor to use, or null if no
           progress monitoring or cancelation is desired
Returns: the project refactoring history/**
	 * 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.

Clients must connect to the refactoring history service first before
calling this method.


Note that calling this method with a flag argument unequal to
RefactoringDescriptor#NONE 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 RefactoringDescriptorProxy.requestDescriptor(IProgressMonitor) which try to request a descriptor from the returned refactoring history. 
Params: project – 
           the project, which must exist
start – 
           the start time stamp, inclusive
end – 
           the end time stamp, inclusive
flags – 
           the refactoring descriptor flags which must be present in
           order to be returned in the refactoring history object, or
           RefactoringDescriptor#NONE
monitor – 
           the progress monitor to use, or null if no
           progress monitoring or cancelation is desired
Returns: the project refactoring history/**
	 * 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.

Clients must connect to the refactoring history service first before
calling this method.

Params: projects – 
           the projects, which must exist
monitor – 
           the progress monitor to use, or null if no
           progress monitoring or cancelation is desired
Returns: the combined refactoring history/**
	 * 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.

Clients must connect to the refactoring history service first before
calling this method.


Note that calling this method with a flag argument unequal to
RefactoringDescriptor#NONE 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 RefactoringDescriptorProxy.requestDescriptor(IProgressMonitor) which try to request a descriptor from the returned refactoring history. 
Params: projects – 
           the projects, which must exist
start – 
           the start time stamp, inclusive
end – 
           the end time stamp, inclusive
flags – 
           the refactoring descriptor flags which must be present in
           order to be returned in the refactoring history object, or
           RefactoringDescriptor#NONE
monitor – 
           the progress monitor to use, or null if no
           progress monitoring or cancelation is desired
Returns: the combined refactoring history/**
	 * 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.

Clients must connect to the refactoring history service first before
calling this method.

Params: monitor – 
           the progress monitor to use, or null if no
           progress monitoring or cancelation is desired
Returns: the workspace refactoring history/**
	 * 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.

Clients must connect to the refactoring history service first before
calling this method.

Params: start – 
           the start time stamp, inclusive
end – 
           the end time stamp, inclusive
monitor – 
           the progress monitor to use, or null if no
           progress monitoring or cancelation is desired
Returns: the workspace refactoring history/**
	 * 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.

The resulting refactoring history contains resolved refactoring
descriptors and should not be held on to.


It is the responsibility of the caller to close the input stream.

Params: stream – 
           a UTF-8 input stream where to read the
           refactoring history from
flags – 
           the refactoring descriptor flags to filter the refactoring
           descriptors
Throws: CoreException – 
            if an error occurs while reading form the input stream.
            Reasons include:
            
            The input stream contains no version information for the
            refactoring history.
            The input stream contains an unsupported version of a
            refactoring history.
            An I/O error occurs while reading the refactoring
            history from the input stream.
            
See Also: RefactoringDescriptor.NONE
RefactoringDescriptor.STRUCTURAL_CHANGE
RefactoringDescriptor.BREAKING_CHANGE
IRefactoringCoreStatusCodes.REFACTORING_HISTORY_IO_ERROR
IRefactoringCoreStatusCodes.UNSUPPORTED_REFACTORING_HISTORY_VERSION
IRefactoringCoreStatusCodes.MISSING_REFACTORING_HISTORY_VERSION
Returns: a refactoring history containing the filtered refactoring
        descriptors/**
	 * 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.

If the listener is not registered with the service, nothing happens.

Params: listener – 
           the listener to remove/**
	 * 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.

If the listener is not registered with the service, nothing happens.

Params: listener – 
           the listener to remove/**
	 * 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.

It is the responsibility of the caller to close the output stream.

Params: proxies – 
           the refactoring descriptor proxies
stream – 
           a UTF-8 output stream where to write the
           refactoring descriptors to
flags – 
           the flags which must be present in order to be written to the
           output stream, or RefactoringDescriptor#NONE
time – 
           true to write time information associated with
           the refactorings, false otherwise
monitor – 
           the progress monitor to use, or null if no
           progress monitoring or cancelation is desired
Throws: CoreException – 
            if an error occurs while writing to the output stream.
            Reasons include:
            
            The refactoring descriptors have an illegal format,
            contain illegal arguments or otherwise illegal information.
            An I/O error occurs while writing the refactoring
            descriptors to the output stream.
            
See Also: RefactoringDescriptor.NONE
RefactoringDescriptor.STRUCTURAL_CHANGE
RefactoringDescriptor.BREAKING_CHANGE
IRefactoringCoreStatusCodes.REFACTORING_HISTORY_FORMAT_ERROR
IRefactoringCoreStatusCodes.REFACTORING_HISTORY_IO_ERROR/**
	 * 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.

It is the responsibility of the caller to close the output stream.

Params: descriptor – 
           the refactoring session descriptor to write
stream – 
           a UTF-8 output stream where to write the
           refactoring session to
time – 
           true to write time information associated with
           the refactorings, false otherwise
Throws: CoreException – 
            if an error occurs while writing to the output stream.
            Reasons include:
            
            The refactoring descriptors have an illegal format,
            contain illegal arguments or otherwise illegal information.
            An I/O error occurs while writing the refactoring
            descriptors to the output stream.
            
See Also: IRefactoringCoreStatusCodes.REFACTORING_HISTORY_FORMAT_ERROR
IRefactoringCoreStatusCodes.REFACTORING_HISTORY_IO_ERROR/**
	 * 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;
}

See Also:	RefactoringCore IRefactoringHistoryListener IRefactoringExecutionListener RefactoringHistory RefactoringDescriptorProxy
Since:	3.2
@noimplement	This interface is not intended to be implemented by clients.
@noextend	This interface is not intended to be extended by clients.

Params:	project – the project, which must exist monitor – the progress monitor to use, or `null` if no progress monitoring or cancelation is desired
Returns:	the project refactoring history

Params:	projects – the projects, which must exist monitor – the progress monitor to use, or `null` if no progress monitoring or cancelation is desired
Returns:	the combined refactoring history

Params:	monitor – the progress monitor to use, or `null` if no progress monitoring or cancelation is desired
Returns:	the workspace refactoring history

Params:	start – the start time stamp, inclusive end – the end time stamp, inclusive monitor – the progress monitor to use, or `null` if no progress monitoring or cancelation is desired
Returns:	the workspace refactoring history

Params:	stream – a `UTF-8` input stream where to read the refactoring history from flags – the refactoring descriptor flags to filter the refactoring descriptors
Throws:	CoreException – if an error occurs while reading form the input stream. Reasons include: The input stream contains no version information for the refactoring history. The input stream contains an unsupported version of a refactoring history. An I/O error occurs while reading the refactoring history from the input stream.
See Also:	RefactoringDescriptor.NONE RefactoringDescriptor.STRUCTURAL_CHANGE RefactoringDescriptor.BREAKING_CHANGE IRefactoringCoreStatusCodes.REFACTORING_HISTORY_IO_ERROR IRefactoringCoreStatusCodes.UNSUPPORTED_REFACTORING_HISTORY_VERSION IRefactoringCoreStatusCodes.MISSING_REFACTORING_HISTORY_VERSION
Returns:	a refactoring history containing the filtered refactoring descriptors

Params:	proxies – the refactoring descriptor proxies stream – a `UTF-8` output stream where to write the refactoring descriptors to flags – the flags which must be present in order to be written to the output stream, or `RefactoringDescriptor#NONE` time – `true` to write time information associated with the refactorings, `false` otherwise monitor – the progress monitor to use, or `null` if no progress monitoring or cancelation is desired
Throws:	CoreException – if an error occurs while writing to the output stream. Reasons include: The refactoring descriptors have an illegal format, contain illegal arguments or otherwise illegal information. An I/O error occurs while writing the refactoring descriptors to the output stream.
See Also:	RefactoringDescriptor.NONE RefactoringDescriptor.STRUCTURAL_CHANGE RefactoringDescriptor.BREAKING_CHANGE IRefactoringCoreStatusCodes.REFACTORING_HISTORY_FORMAT_ERROR IRefactoringCoreStatusCodes.REFACTORING_HISTORY_IO_ERROR

Params:	descriptor – the refactoring session descriptor to write stream – a `UTF-8` output stream where to write the refactoring session to time – `true` to write time information associated with the refactorings, `false` otherwise
Throws:	CoreException – if an error occurs while writing to the output stream. Reasons include: The refactoring descriptors have an illegal format, contain illegal arguments or otherwise illegal information. An I/O error occurs while writing the refactoring descriptors to the output stream.
See Also:	IRefactoringCoreStatusCodes.REFACTORING_HISTORY_FORMAT_ERROR IRefactoringCoreStatusCodes.REFACTORING_HISTORY_IO_ERROR

/

org.eclipse.platform/ org.eclipse.ltk.core.refactoring/ 3.10.300/ org/eclipse/ltk/core/refactoring/history/IRefactoringHistoryService.java