KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > internal > localstore > IHistoryStore


1 /*******************************************************************************
2  * Copyright (c) 2004, 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.core.internal.localstore;
12
13 import java.io.InputStream JavaDoc;
14 import java.util.Set JavaDoc;
15 import org.eclipse.core.filesystem.IFileInfo;
16 import org.eclipse.core.filesystem.IFileStore;
17 import org.eclipse.core.internal.resources.IManager;
18 import org.eclipse.core.resources.IFileState;
19 import org.eclipse.core.resources.IResource;
20 import org.eclipse.core.runtime.*;
21
22 /**
23  * The history store is an association of paths to file states.
24  * Typically the path is the full path of a resource in the workspace.
25  * <p>
26  * History store policies are stored in the org.eclipse.core.resources'
27  * plug-in preferences.
28  * </p>
29  *
30  * @since 3.1
31  */
32 public interface IHistoryStore extends IManager {
33
34     /**
35      * Add an entry to the history store, represented by the given key. Return the
36      * file state for the newly created entry or<code>null</code> if it couldn't
37      * be created.
38      * <p>
39      * Note: Depending on the history store implementation, some of the history
40      * store policies can be applied during this method call to determine whether
41      * or not the entry should be added to the store.
42      * </p>
43      * @param key full workspace path to resource being logged
44      * @param localFile local file system file handle
45      * @param fileInfo The IFileInfo for the entry
46      * @return the file state or <code>null</code>
47      *
48      * TODO: should this method take a progress monitor?
49      *
50      * TODO: look at #getFileFor(). Is there a case where we wouldn't want to
51      * copy over the file attributes to the local history? If we did that here then
52      * we wouldn't have to have that other API.
53      */
54     public IFileState addState(IPath key, IFileStore localFile, IFileInfo fileInfo, boolean moveContents);
55
56     /**
57      * Returns the paths of all files with entries in this history store at or below
58      * the given workspace resource path to the given depth. Returns an
59      * empty set if there are none.
60      * <p>
61      * This method is long-running; progress and cancellation are provided
62      * by the given progress monitor.
63      * </p>
64      * @param path full workspace path to resource
65      * @param depth depth limit: one of <code>DEPTH_ZERO</code>, <code>DEPTH_ONE</code>
66      * or <code>DEPTH_INFINITE</code>
67      * @param monitor a progress monitor, or <code>null</code> if progress
68      * reporting is not desired
69      * @return the set of paths for files that have at least one history entry
70      * (element type: <code>IPath</code>)
71      */
72     public Set JavaDoc allFiles(IPath path, int depth, IProgressMonitor monitor);
73
74     /**
75      * Clean this store applying the current policies.
76      * <p>
77      * Note: The history store policies are stored as part of
78      * the org.eclipse.core.resource plug-in's preferences and
79      * include such settings as: maximum file size, maximum number
80      * of states per file, file expiration date, etc.
81      * </p>
82      * <p>
83      * Note: Depending on the implementation of the history store,
84      * if all the history store policies are applying when the entries
85      * are first added to the store then this method might be a no-op.
86      * </p>
87      * <p>
88      * This method is long-running; progress and cancellation are provided
89      * by the given progress monitor.
90      * </p>
91      * @param monitor a progress monitor, or <code>null</code> if progress
92      * reporting is not desired
93      */
94     public void clean(IProgressMonitor monitor);
95
96     /**
97      * Closes the history store for the given resource.
98      */
99     public void closeHistoryStore(IResource resource);
100     
101     /**
102      * Copies the history store information from the source path given destination path.
103      * Note that destination may already have some history store information. Also note
104      * that this is a DEPTH_INFINITY operation. That is, history will be copied for partial
105      * matches of the source path.
106      *
107      * @param source the resource containing the original copy of the history store information
108      * @param destination the target resource where to copy the history
109      * @param moving whether the history is being copied due to a resource move
110      *
111      * TODO: should this method take a progress monitor?
112      */
113     public void copyHistory(IResource source, IResource destination, boolean moving);
114
115     /**
116      * Verifies existence of specified resource in the history store. Returns
117      * <code>true</code> if the file state exists and <code>false</code>
118      * otherwise.
119      * <p>
120      * Note: This method cannot take a progress monitor since it is surfaced
121      * to the real API via IFileState#exists() which doesn't take a progress
122      * monitor.
123      * </p>
124      * @param target the file state to be verified
125      * @return <code>true</code> if file state exists,
126      * and <code>false</code> otherwise
127      */
128     public boolean exists(IFileState target);
129
130     /**
131      * Returns an input stream containing the file contents of the specified state.
132      * The user is responsible for closing the returned stream.
133      * <p>
134      * Note: This method cannot take a progress monitor since it is
135      * surfaced through to the real API via IFileState#getContents which
136      * doesn't take one.
137      * </p>
138      * @param target File state for which an input stream is requested
139      * @return the stream for requested file state
140      */
141     public InputStream JavaDoc getContents(IFileState target) throws CoreException;
142
143     /**
144      * Returns an array of all states available for the specified resource path or
145      * an empty array if none.
146      * <p>
147      * This method is long-running; progress and cancellation are provided
148      * by the given progress monitor.
149      * </p>
150      * @param path the resource path
151      * @param monitor a progress monitor, or <code>null</code> if progress
152      * reporting is not desired
153      * @return the list of file states
154      */
155     public IFileState[] getStates(IPath path, IProgressMonitor monitor);
156
157     /**
158      * Remove all of the file states for the given resource path and
159      * all its children. If the workspace root path is the given argument,
160      * then all history for this store is removed.
161      * <p>
162      * This method is long-running; progress and cancellation are provided
163      * by the given progress monitor.
164      * </p>
165      * @param path the resource path whose history is to be removed
166      * @param monitor a progress monitor, or <code>null</code> if progress
167      * reporting is not desired
168      */
169     public void remove(IPath path, IProgressMonitor monitor);
170
171     /**
172      * Go through the history store and remove all of the unreferenced states.
173      *
174      * As of 3.0, this method is used for testing purposes only. Otherwise the history
175      * store is garbage collected during the #clean method.
176      */
177     public void removeGarbage();
178 }
179
Popular Tags