IRefactoringHistoryService


1   /*******************************************************************************
2    * Copyright (c) 2005, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ltk.core.refactoring.history;
12  
13  import java.io.InputStream  ;
14  import java.io.OutputStream  ;
15  
16  import org.eclipse.core.runtime.CoreException;
17  import org.eclipse.core.runtime.IProgressMonitor;
18  
19  import org.eclipse.core.resources.IProject;
20  
21  import org.eclipse.ltk.core.refactoring.IRefactoringCoreStatusCodes;
22  import org.eclipse.ltk.core.refactoring.RefactoringCore;
23  import org.eclipse.ltk.core.refactoring.RefactoringDescriptor;
24  import org.eclipse.ltk.core.refactoring.RefactoringDescriptorProxy;
25  import org.eclipse.ltk.core.refactoring.RefactoringSessionDescriptor;
26  
27  /**
28   * Interface for a refactoring history service. A refactoring history service
29   * provides methods to register refactoring history listeners, refactoring
30   * execution listeners and facilities to query the global refactoring history
31   * index for specific refactoring histories. Additionally, methods are provided
32   * which read or write refactoring information. The refactoring history service
33   * only returns refactorings which have contributed a refactoring descriptor via
34   * their change object.
35   * <p>
36   * An instance of a refactoring history service may be obtained by calling
37   * {@link RefactoringCore#getHistoryService()}.
38   * </p>
39   * <p>
40   * All time stamps are measured as the milliseconds since January 1, 1970,
41   * 00:00:00 GMT.
42   * </p>
43   * <p>
44   * Note: this interface is not intended to be implemented by clients.
45   * </p>
46   * 
47   * @see RefactoringCore
48   * @see IRefactoringHistoryListener
49   * @see IRefactoringExecutionListener
50   * 
51   * @see RefactoringHistory
52   * @see RefactoringDescriptorProxy
53   * 
54   * @since 3.2
55   */
56  public interface IRefactoringHistoryService {
57  
58      /**
59       * Adds the specified refactoring execution listener to this service.
60       * <p>
61       * If the listener is already registered with the service, nothing happens.
62       * </p>
63       * 
64       * @param listener
65       *            the listener to add
66       */
67      public void addExecutionListener(IRefactoringExecutionListener listener);
68  
69      /**
70       * Adds the specified refactoring history listener to this service.
71       * <p>
72       * If the listener is already registered with the service, nothing happens.
73       * </p>
74       * 
75       * @param listener
76       *            the listener to add
77       */
78      public void addHistoryListener(IRefactoringHistoryListener listener);
79  
80      /**
81       * Connects the refactoring history service to the workbench's operation
82       * history if necessary and increments an internal counter.
83       * <p>
84       * If the service is already connected, nothing happens.
85       * </p>
86       * <p>
87       * Every call to {@link #connect()} must be balanced with a corresponding
88       * call to {@link #disconnect()}.
89       * </p>
90       */
91      public void connect();
92  
93      /**
94       * Disconnects the refactoring history service from the workbench's
95       * operation history if necessary and decrements an internal counter.
96       * <p>
97       * If the service is not connected, nothing happens. If the service is
98       * connected, all resources acquired since the corresponding call to
99       * {@link #connect()} are released.
100      * </p>
101      * <p>
102      * Every call to {@link #disconnect()} must be balanced with a corresponding
103      * call to {@link #connect()}.
104      * </p>
105      */
106     public void disconnect();
107 
108     /**
109      * Returns a project refactoring history for the specified project.
110      * <p>
111      * Clients must connect to the refactoring history service first before
112      * calling this method.
113      * </p>
114      * 
115      * @param project
116      *            the project, which must exist
117      * @param monitor
118      *            the progress monitor to use, or <code>null</code> if no
119      *            progress monitoring or cancelation is desired
120      * @return the project refactoring history
121      */
122     public RefactoringHistory getProjectHistory(IProject project, IProgressMonitor monitor);
123 
124     /**
125      * Returns a project refactoring history for the specified project.
126      * <p>
127      * Clients must connect to the refactoring history service first before
128      * calling this method.
129      * </p>
130      * <p>
131      * Note that calling this method with a flag argument unequal to
132      * <code>RefactoringDescriptor#NONE</code> may result in a performance
133      * degradation, since the actual descriptors have to be eagerly resolved.
134      * This in turn results in faster execution of any subsequent calls to
135      * {@link RefactoringDescriptorProxy#requestDescriptor(IProgressMonitor)}
136      * which try to request a descriptor from the returned refactoring history.
137      * </p>
138      * 
139      * @param project
140      *            the project, which must exist
141      * @param start
142      *            the start time stamp, inclusive
143      * @param end
144      *            the end time stamp, inclusive
145      * @param flags
146      *            the refactoring descriptor flags which must be present in
147      *            order to be returned in the refactoring history object, or
148      *            <code>RefactoringDescriptor#NONE</code>
149      * @param monitor
150      *            the progress monitor to use, or <code>null</code> if no
151      *            progress monitoring or cancelation is desired
152      * @return the project refactoring history
153      */
154     public RefactoringHistory getProjectHistory(IProject project, long start, long end, int flags, IProgressMonitor monitor);
155 
156     /**
157      * Returns the combined refactoring history for the specified projects.
158      * <p>
159      * Clients must connect to the refactoring history service first before
160      * calling this method.
161      * </p>
162      * 
163      * @param projects
164      *            the projects, which must exist
165      * @param monitor
166      *            the progress monitor to use, or <code>null</code> if no
167      *            progress monitoring or cancelation is desired
168      * @return the combined refactoring history
169      */
170     public RefactoringHistory getRefactoringHistory(IProject[] projects, IProgressMonitor monitor);
171 
172     /**
173      * Returns the combined refactoring history for the specified projects.
174      * <p>
175      * Clients must connect to the refactoring history service first before
176      * calling this method.
177      * </p>
178      * <p>
179      * Note that calling this method with a flag argument unequal to
180      * <code>RefactoringDescriptor#NONE</code> may result in a performance
181      * degradation, since the actual descriptors have to be eagerly resolved.
182      * This in turn results in faster execution of any subsequent calls to
183      * {@link RefactoringDescriptorProxy#requestDescriptor(IProgressMonitor)}
184      * which try to request a descriptor from the returned refactoring history.
185      * </p>
186      * 
187      * @param projects
188      *            the projects, which must exist
189      * @param start
190      *            the start time stamp, inclusive
191      * @param end
192      *            the end time stamp, inclusive
193      * @param flags
194      *            the refactoring descriptor flags which must be present in
195      *            order to be returned in the refactoring history object, or
196      *            <code>RefactoringDescriptor#NONE</code>
197      * @param monitor
198      *            the progress monitor to use, or <code>null</code> if no
199      *            progress monitoring or cancelation is desired
200      * @return the combined refactoring history
201      */
202     public RefactoringHistory getRefactoringHistory(IProject[] projects, long start, long end, int flags, IProgressMonitor monitor);
203 
204     /**
205      * Returns the workspace refactoring history.
206      * <p>
207      * Clients must connect to the refactoring history service first before
208      * calling this method.
209      * </p>
210      * 
211      * @param monitor
212      *            the progress monitor to use, or <code>null</code> if no
213      *            progress monitoring or cancelation is desired
214      * @return the workspace refactoring history
215      */
216     public RefactoringHistory getWorkspaceHistory(IProgressMonitor monitor);
217 
218     /**
219      * Returns the workspace refactoring history.
220      * <p>
221      * Clients must connect to the refactoring history service first before
222      * calling this method.
223      * </p>
224      * 
225      * @param start
226      *            the start time stamp, inclusive
227      * @param end
228      *            the end time stamp, inclusive
229      * @param monitor
230      *            the progress monitor to use, or <code>null</code> if no
231      *            progress monitoring or cancelation is desired
232      * @return the workspace refactoring history
233      */
234     public RefactoringHistory getWorkspaceHistory(long start, long end, IProgressMonitor monitor);
235 
236     /**
237      * Reads a refactoring history from the input stream.
238      * <p>
239      * The resulting refactoring history contains resolved refactoring
240      * descriptors and should not be held on to.
241      * </p>
242      * <p>
243      * It is the responsibility of the caller to close the input stream.
244      * </p>
245      * 
246      * @param stream
247      *            a <code>UTF-8</code> input stream where to read the
248      *            refactoring history from
249      * @param flags
250      *            the refactoring descriptor flags to filter the refactoring
251      *            descriptors
252      * @return a refactoring history containing the filtered refactoring
253      *         descriptors
254      * @throws CoreException
255      *             if an error occurs while reading form the input stream.
256      *             Reasons include:
257      *             <ul>
258      *             <li>The input stream contains no version information for the
259      *             refactoring history.</li>
260      *             <li>The input stream contains an unsupported version of a
261      *             refactoring history.</li>
262      *             <li>An I/O error occurs while reading the refactoring
263      *             history from the input stream.</li>
264      *             </ul>
265      * 
266      * @see RefactoringDescriptor#NONE
267      * @see RefactoringDescriptor#STRUCTURAL_CHANGE
268      * @see RefactoringDescriptor#BREAKING_CHANGE
269      * 
270      * @see IRefactoringCoreStatusCodes#REFACTORING_HISTORY_IO_ERROR
271      * @see IRefactoringCoreStatusCodes#UNSUPPORTED_REFACTORING_HISTORY_VERSION
272      * @see IRefactoringCoreStatusCodes#MISSING_REFACTORING_HISTORY_VERSION
273      */
274     public RefactoringHistory readRefactoringHistory(InputStream   stream, int flags) throws CoreException;
275 
276     /**
277      * Removes the specified refactoring execution listener from this service.
278      * <p>
279      * If the listener is not registered with the service, nothing happens.
280      * </p>
281      * 
282      * @param listener
283      *            the listener to remove
284      */
285     public void removeExecutionListener(IRefactoringExecutionListener listener);
286 
287     /**
288      * Removes the specified refactoring history listener from this service.
289      * <p>
290      * If the listener is not registered with the service, nothing happens.
291      * </p>
292      * 
293      * @param listener
294      *            the listener to remove
295      */
296     public void removeHistoryListener(IRefactoringHistoryListener listener);
297 
298     /**
299      * Writes the specified refactoring descriptor proxies to the output stream.
300      * Refactoring descriptor proxies which cannot be resolved are automatically
301      * skipped.
302      * <p>
303      * It is the responsibility of the caller to close the output stream.
304      * </p>
305      * 
306      * @param proxies
307      *            the refactoring descriptor proxies
308      * @param stream
309      *            a <code>UTF-8</code> output stream where to write the
310      *            refactoring descriptors to
311      * @param flags
312      *            the flags which must be present in order to be written to the
313      *            output stream, or <code>RefactoringDescriptor#NONE</code>
314      * @param time
315      *            <code>true</code> to write time information associated with
316      *            the refactorings, <code>false</code> otherwise
317      * @param monitor
318      *            the progress monitor to use, or <code>null</code> if no
319      *            progress monitoring or cancelation is desired
320      * @throws CoreException
321      *             if an error occurs while writing to the output stream.
322      *             Reasons include:
323      *             <ul>
324      *             <li>The refactoring descriptors have an illegal format,
325      *             contain illegal arguments or otherwise illegal information.</li>
326      *             <li>An I/O error occurs while writing the refactoring
327      *             descriptors to the output stream.</li>
328      *             </ul>
329      * 
330      * @see RefactoringDescriptor#NONE
331      * @see RefactoringDescriptor#STRUCTURAL_CHANGE
332      * @see RefactoringDescriptor#BREAKING_CHANGE
333      * 
334      * @see IRefactoringCoreStatusCodes#REFACTORING_HISTORY_FORMAT_ERROR
335      * @see IRefactoringCoreStatusCodes#REFACTORING_HISTORY_IO_ERROR
336      */
337     public void writeRefactoringDescriptors(RefactoringDescriptorProxy[] proxies, OutputStream   stream, int flags, boolean time, IProgressMonitor monitor) throws CoreException;
338 
339     /**
340      * Writes the specified refactoring session descriptor to the output stream.
341      * <p>
342      * It is the responsibility of the caller to close the output stream.
343      * </p>
344      * 
345      * @param descriptor
346      *            the refactoring session descriptor to write
347      * @param stream
348      *            a <code>UTF-8</code> output stream where to write the
349      *            refactoring session to
350      * @param time
351      *            <code>true</code> to write time information associated with
352      *            the refactorings, <code>false</code> otherwise
353      * @throws CoreException
354      *             if an error occurs while writing to the output stream.
355      *             Reasons include:
356      *             <ul>
357      *             <li>The refactoring descriptors have an illegal format,
358      *             contain illegal arguments or otherwise illegal information.</li>
359      *             <li>An I/O error occurs while writing the refactoring
360      *             descriptors to the output stream.</li>
361      *             </ul>
362      * 
363      * @see IRefactoringCoreStatusCodes#REFACTORING_HISTORY_FORMAT_ERROR
364      * @see IRefactoringCoreStatusCodes#REFACTORING_HISTORY_IO_ERROR
365      */
366     public void writeRefactoringSession(RefactoringSessionDescriptor descriptor, OutputStream   stream, boolean time) throws CoreException;
367 }
368
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags