Java > Open Source Codes > org > eclipse > core > resources > IFile


1 /*******************************************************************************
2  * Copyright (c) 2000, 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.resources;
12
13 import java.io.InputStream ;
14 import java.io.Reader ;
15 import java.net.URI ;
16 import org.eclipse.core.runtime.*;
17 import org.eclipse.core.runtime.content.IContentDescription;
18 import org.eclipse.core.runtime.content.IContentTypeManager;
19
20 /**
21  * Files are leaf resources which contain data.
22  * The contents of a file resource is stored as a file in the local
23  * file system.
24  * <p>
25  * Files, like folders, may exist in the workspace but
26  * not be local; non-local file resources serve as place-holders for
27  * files whose content and properties have not yet been fetched from
28  * a repository.
29  * </p>
30  * <p>
31  * This interface is not intended to be implemented by clients.
32  * </p>
33  * <p>
34  * Files implement the <code>IAdaptable</code> interface;
35  * extensions are managed by the platform's adapter manager.
36  * </p>
37  *
38  * @see Platform#getAdapterManager()
39  */
40 public interface IFile extends IResource, IEncodedStorage, IAdaptable {
41     /**
42      * Character encoding constant (value 0) which identifies
43      * files that have an unknown character encoding scheme.
44      *
45      * @see IFile#getEncoding()
46      * @deprecated see getEncoding for details
47      */
48     public int ENCODING_UNKNOWN = 0;
49     /**
50      * Character encoding constant (value 1) which identifies
51      * files that are encoded with the US-ASCII character encoding scheme.
52      *
53      * @see IFile#getEncoding()
54      * @deprecated see getEncoding for details
55      */
56     public int ENCODING_US_ASCII = 1;
57     /**
58      * Character encoding constant (value 2) which identifies
59      * files that are encoded with the ISO-8859-1 character encoding scheme,
60      * also known as ISO-LATIN-1.
61      *
62      * @see IFile#getEncoding()
63      * @deprecated see getEncoding for details
64      */
65     public int ENCODING_ISO_8859_1 = 2;
66     /**
67      * Character encoding constant (value 3) which identifies
68      * files that are encoded with the UTF-8 character encoding scheme.
69      *
70      * @see IFile#getEncoding()
71      * @deprecated see getEncoding for details
72      */
73     public int ENCODING_UTF_8 = 3;
74     /**
75      * Character encoding constant (value 4) which identifies
76      * files that are encoded with the UTF-16BE character encoding scheme.
77      *
78      * @see IFile#getEncoding()
79      * @deprecated see getEncoding for details
80      */
81     public int ENCODING_UTF_16BE = 4;
82     /**
83      * Character encoding constant (value 5) which identifies
84      * files that are encoded with the UTF-16LE character encoding scheme.
85      *
86      * @see IFile#getEncoding()
87      * @deprecated see getEncoding for details
88      */
89     public int ENCODING_UTF_16LE = 5;
90     /**
91      * Character encoding constant (value 6) which identifies
92      * files that are encoded with the UTF-16 character encoding scheme.
93      *
94      * @see IFile#getEncoding()
95      * @deprecated see getEncoding for details
96      */
97     public int ENCODING_UTF_16 = 6;
98
99     /**
100      * Appends the entire contents of the given stream to this file.
101      * <p>
102      * This is a convenience method, fully equivalent to:
103      * <pre>
104      * appendContents(source, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);
105      * </pre>
106      * </p>
107      * <p>
108      * This method changes resources; these changes will be reported
109      * in a subsequent resource change event, including an indication
110      * that this file's content have been changed.
111      * </p>
112      * <p>
113      * This method is long-running; progress and cancelation are provided
114      * by the given progress monitor.
115      * </p>
116      *
117      * @param source an input stream containing the new contents of the file
118      * @param force a flag controlling how to deal with resources that
119      * are not in sync with the local file system
120      * @param keepHistory a flag indicating whether or not to store
121      * the current contents in the local history
122      * @param monitor a progress monitor, or <code>null</code> if progress
123      * reporting is not desired
124      * @exception CoreException if this method fails. Reasons include:
125      * <ul>
126      * <li> This resource does not exist.</li>
127      * <li> The corresponding location in the local file system
128      * is occupied by a directory.</li>
129      * <li> The workspace is not in sync with the corresponding location
130      * in the local file system and <code>force </code> is <code>false</code>.</li>
131      * <li> Resource changes are disallowed during certain types of resource change
132      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
133      * <li> The file modification validator disallowed the change.</li>
134      * </ul>
135      * @exception OperationCanceledException if the operation is canceled.
136      * Cancelation can occur even if no progress monitor is provided.
137      * @see #appendContents(java.io.InputStream,int,IProgressMonitor)
138      */
139     public void appendContents(InputStream source, boolean force, boolean keepHistory, IProgressMonitor monitor) throws CoreException;
140
141     /**
142      * Appends the entire contents of the given stream to this file.
143      * The stream, which must not be <code>null</code>, will get closed
144      * whether this method succeeds or fails.
145      * <p>
146      * The <code>FORCE</code> update flag controls how this method deals with
147      * cases where the workspace is not completely in sync with the local file
148      * system. If <code>FORCE</code> is not specified, the method will only attempt
149      * to overwrite a corresponding file in the local file system provided
150      * it is in sync with the workspace. This option ensures there is no
151      * unintended data loss; it is the recommended setting.
152      * However, if <code>FORCE</code> is specified, an attempt will be made
153      * to write a corresponding file in the local file system, overwriting any
154      * existing one if need be. In either case, if this method succeeds, the
155      * resource will be marked as being local (even if it wasn't before).
156      * </p>
157      * <p>
158      * If this file is non-local then this method will always fail. The only exception
159      * is when <code>FORCE</code> is specified and the file exists in the local
160      * file system. In this case the file is made local and the given contents are appended.
161      * </p>
162      * <p>
163      * The <code>KEEP_HISTORY</code> update flag controls whether or not a copy of
164      * current contents of this file should be captured in the workspace's local
165      * history (properties are not recorded in the local history). The local history
166      * mechanism serves as a safety net to help the user recover from mistakes that
167      * might otherwise result in data loss. Specifying <code>KEEP_HISTORY</code>
168      * is recommended except in circumstances where past states of the files are of
169      * no conceivable interest to the user. Note that local history is maintained
170      * with each individual project, and gets discarded when a project is deleted
171      * from the workspace. This flag is ignored if the file was not previously local.
172      * </p>
173      * <p>
174      * Update flags other than <code>FORCE</code> and <code>KEEP_HISTORY</code>
175      * are ignored.
176      * </p>
177      * <p>
178      * Prior to modifying the contents of this file, the file modification validator (if provided
179      * by the VCM plug-in), will be given a chance to perform any last minute preparations. Validation
180      * is performed by calling <code>IFileModificationValidator.validateSave</code> on this file.
181      * If the validation fails, then this operation will fail.
182      * </p>
183      * <p>
184      * This method changes resources; these changes will be reported
185      * in a subsequent resource change event, including an indication
186      * that this file's content have been changed.
187      * </p>
188      * <p>
189      * This method is long-running; progress and cancelation are provided
190      * by the given progress monitor.
191      * </p>
192      *
193      * @param source an input stream containing the new contents of the file
194      * @param updateFlags bit-wise or of update flag constants
195      * (<code>FORCE</code> and <code>KEEP_HISTORY</code>)
196      * @param monitor a progress monitor, or <code>null</code> if progress
197      * reporting is not desired
198      * @exception CoreException if this method fails. Reasons include:
199      * <ul>
200      * <li> This resource does not exist.</li>
201      * <li> The corresponding location in the local file system
202      * is occupied by a directory.</li>
203      * <li> The workspace is not in sync with the corresponding location
204      * in the local file system and <code>FORCE</code> is not specified.</li>
205      * <li> Resource changes are disallowed during certain types of resource change
206      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
207      * <li> The file modification validator disallowed the change.</li>
208      * </ul>
209      * @exception OperationCanceledException if the operation is canceled.
210      * Cancelation can occur even if no progress monitor is provided.
211      * @see IResourceRuleFactory#modifyRule(IResource)
212      * @since 2.0
213      */
214     public void appendContents(InputStream source, int updateFlags, IProgressMonitor monitor) throws CoreException;
215
216     /**
217      * Creates a new file resource as a member of this handle's parent resource.
218      * <p>
219      * This is a convenience method, fully equivalent to:
220      * <pre>
221      * create(source, (force ? FORCE : IResource.NONE), monitor);
222      * </pre>
223      * </p>
224      * <p>
225      * This method changes resources; these changes will be reported
226      * in a subsequent resource change event, including an indication
227      * that the file has been added to its parent.
228      * </p>
229      * <p>
230      * This method is long-running; progress and cancellation are provided
231      * by the given progress monitor.
232      * </p>
233      *
234      * @param source an input stream containing the initial contents of the file,
235      * or <code>null</code> if the file should be marked as not local
236      * @param force a flag controlling how to deal with resources that
237      * are not in sync with the local file system
238      * @param monitor a progress monitor, or <code>null</code> if progress
239      * reporting is not desired
240      * @exception CoreException if this method fails. Reasons include:
241      * <ul>
242      * <li> This resource already exists in the workspace.</li>
243      * <li> The parent of this resource does not exist.</li>
244      * <li> The project of this resource is not accessible.</li>
245      * <li> The parent contains a resource of a different type
246      * at the same path as this resource.</li>
247      * <li> The name of this resource is not valid (according to
248      * <code>IWorkspace.validateName</code>).</li>
249      * <li> The corresponding location in the local file system is occupied
250      * by a directory.</li>
251      * <li> The corresponding location in the local file system is occupied
252      * by a file and <code>force </code> is <code>false</code>.</li>
253      * <li> Resource changes are disallowed during certain types of resource change
254      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
255      * </ul>
256      * @exception OperationCanceledException if the operation is canceled.
257      * Cancelation can occur even if no progress monitor is provided.
258      */
259     public void create(InputStream source, boolean force, IProgressMonitor monitor) throws CoreException;
260
261     /**
262      * Creates a new file resource as a member of this handle's parent resource.
263      * The resource's contents are supplied by the data in the given stream.
264      * This method closes the stream whether it succeeds or fails.
265      * If the stream is <code>null</code> then a file is not created in the local
266      * file system and the created file resource is marked as being non-local.
267      * <p>
268      * The {@link IResource#FORCE} update flag controls how this method deals with
269      * cases where the workspace is not completely in sync with the local file
270      * system. If {@link IResource#FORCE} is not specified, the method will only attempt
271      * to write a file in the local file system if it does not already exist.
272      * This option ensures there is no unintended data loss; it is the recommended
273      * setting. However, if {@link IResource#FORCE} is specified, this method will
274      * attempt to write a corresponding file in the local file system,
275      * overwriting any existing one if need be.
276      * </p>
277      * <p>
278      * The {@link IResource#DERIVED} update flag indicates that this resource
279      * should immediately be set as a derived resource. Specifying this flag
280      * is equivalent to atomically calling {@link IResource#setDerived(boolean)}
281      * with a value of <code>true</code> immediately after creating the resource.
282      * </p>
283      * <p>
284      * The {@link IResource#TEAM_PRIVATE} update flag indicates that this resource
285      * should immediately be set as a team private resource. Specifying this flag
286      * is equivalent to atomically calling {@link IResource#setTeamPrivateMember(boolean)}
287      * with a value of <code>true</code> immediately after creating the resource.
288      * </p>
289      * <p>
290      * Update flags other than those listed above are ignored.
291      * </p>
292      * <p>
293      * This method changes resources; these changes will be reported
294      * in a subsequent resource change event, including an indication
295      * that the file has been added to its parent.
296      * </p>
297      * <p>
298      * This method is long-running; progress and cancellation are provided
299      * by the given progress monitor.
300      * </p>
301      *
302      * @param source an input stream containing the initial contents of the file,
303      * or <code>null</code> if the file should be marked as not local
304      * @param updateFlags bit-wise or of update flag constants
305      * ({@link IResource#FORCE}, {@link IResource#DERIVED}, and {@link IResource#TEAM_PRIVATE})
306      * @param monitor a progress monitor, or <code>null</code> if progress
307      * reporting is not desired
308      * @exception CoreException if this method fails. Reasons include:
309      * <ul>
310      * <li> This resource already exists in the workspace.</li>
311      * <li> The parent of this resource does not exist.</li>
312      * <li> The project of this resource is not accessible.</li>
313      * <li> The parent contains a resource of a different type
314      * at the same path as this resource.</li>
315      * <li> The name of this resource is not valid (according to
316      * <code>IWorkspace.validateName</code>).</li>
317      * <li> The corresponding location in the local file system is occupied
318      * by a directory.</li>
319      * <li> The corresponding location in the local file system is occupied
320      * by a file and <code>FORCE</code> is not specified.</li>
321      * <li> Resource changes are disallowed during certain types of resource change
322      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
323      * </ul>
324      * @exception OperationCanceledException if the operation is canceled.
325      * Cancelation can occur even if no progress monitor is provided.
326      * @see IResourceRuleFactory#createRule(IResource)
327      * @since 2.0
328      */
329     public void create(InputStream source, int updateFlags, IProgressMonitor monitor) throws CoreException;
330
331     /**
332      * Creates a new file resource as a member of this handle's parent resource.
333      * The file's contents will be located in the file specified by the given
334      * file system path. The given path must be either an absolute file system
335      * path, or a relative path whose first segment is the name of a workspace path
336      * variable.
337      * <p>
338      * The {@link IResource#ALLOW_MISSING_LOCAL} update flag controls how this
339      * method deals with cases where the local file system file to be linked does
340      * not exist, or is relative to a workspace path variable that is not defined.
341      * If {@link IResource#ALLOW_MISSING_LOCAL} is specified, the operation will succeed
342      * even if the local file is missing, or the path is relative to an undefined
343      * variable. If {@link IResource#ALLOW_MISSING_LOCAL} is not specified, the operation
344      * will fail in the case where the local file system file does not exist or the
345      * path is relative to an undefined variable.
346      * </p>
347      * <p>
348      * The {@link IResource#REPLACE} update flag controls how this
349      * method deals with cases where a resource of the same name as the
350      * prospective link already exists. If {@link IResource#REPLACE}
351      * is specified, then any existing resource with the same name is removed
352      * from the workspace to make way for creation of the link. This does <b>not</b>
353      * cause the underlying file system contents of that resource to be deleted.
354      * If {@link IResource#REPLACE} is not specified, this method will
355      * fail if an existing resource exists of the same name.
356      * </p>
357      * <p>
358      * Update flags other than {@link IResource#ALLOW_MISSING_LOCAL} or
359      * {@link IResource#REPLACE} are ignored.
360      * </p>
361      * <p>
362      * This method synchronizes this resource with the local file system at the given
363      * location.
364      * </p>
365      * <p>
366      * This method changes resources; these changes will be reported
367      * in a subsequent resource change event, including an indication
368      * that the file has been added to its parent.
369      * </p>
370      * <p>
371      * This method is long-running; progress and cancellation are provided
372      * by the given progress monitor.
373      * </p>
374      *
375      * @param localLocation a file system path where the file should be linked
376      * @param updateFlags bit-wise or of update flag constants
377      * ({@link IResource#ALLOW_MISSING_LOCAL} and {@link IResource#REPLACE})
378      * @param monitor a progress monitor, or <code>null</code> if progress
379      * reporting is not desired
380      * @exception CoreException if this method fails. Reasons include:
381      * <ul>
382      * <li> This resource already exists in the workspace.</li>
383      * <li> The workspace contains a resource of a different type
384      * at the same path as this resource.</li>
385      * <li> The parent of this resource does not exist.</li>
386      * <li> The parent of this resource is not an open project</li>
387      * <li> The name of this resource is not valid (according to
388      * <code>IWorkspace.validateName</code>).</li>
389      * <li> The corresponding location in the local file system does not exist, or
390      * is relative to an undefined variable, and <code>ALLOW_MISSING_LOCAL</code> is
391      * not specified.</li>
392      * <li> The corresponding location in the local file system is occupied
393      * by a directory (as opposed to a file).</li>
394      * <li> Resource changes are disallowed during certain types of resource change
395      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
396      * <li>The team provider for the project which contains this folder does not permit
397      * linked resources.</li>
398      * <li>This folder's project contains a nature which does not permit linked resources.</li>
399      * </ul>
400      * @exception OperationCanceledException if the operation is canceled.
401      * Cancelation can occur even if no progress monitor is provided.
402      * @see IResource#isLinked()
403      * @see IResource#ALLOW_MISSING_LOCAL
404      * @since 2.1
405      */
406     public void createLink(IPath localLocation, int updateFlags, IProgressMonitor monitor) throws CoreException;
407
408     /**
409      * Creates a new file resource as a member of this handle's parent resource.
410      * The file's contents will be located in the file specified by the given
411      * URI. The given URI must be either absolute, or a relative URI whose first path
412      * segment is the name of a workspace path variable.
413      * <p>
414      * The <code>ALLOW_MISSING_LOCAL</code> update flag controls how this
415      * method deals with cases where the file system file to be linked does
416      * not exist, or is relative to a workspace path variable that is not defined.
417      * If <code>ALLOW_MISSING_LOCAL</code> is specified, the operation will succeed
418      * even if the local file is missing, or the path is relative to an undefined
419      * variable. If <code>ALLOW_MISSING_LOCAL</code> is not specified, the operation
420      * will fail in the case where the file system file does not exist or the
421      * path is relative to an undefined variable.
422      * </p>
423      * <p>
424      * The {@link IResource#REPLACE} update flag controls how this
425      * method deals with cases where a resource of the same name as the
426      * prospective link already exists. If {@link IResource#REPLACE}
427      * is specified, then any existing resource with the same name is removed
428      * from the workspace to make way for creation of the link. This does <b>not</b>
429      * cause the underlying file system contents of that resource to be deleted.
430      * If {@link IResource#REPLACE} is not specified, this method will
431      * fail if an existing resource exists of the same name.
432      * </p>
433      * <p>
434      * Update flags other than {@link IResource#ALLOW_MISSING_LOCAL} or
435      * {@link IResource#REPLACE} are ignored.
436      * </p>
437      * <p>
438      * This method synchronizes this resource with the file system at the given
439      * location.
440      * </p>
441      * <p>
442      * This method changes resources; these changes will be reported
443      * in a subsequent resource change event, including an indication
444      * that the file has been added to its parent.
445      * </p>
446      * <p>
447      * This method is long-running; progress and cancellation are provided
448      * by the given progress monitor.
449      * </p>
450      *
451      * @param location a file system URI where the file should be linked
452      * @param updateFlags bit-wise or of update flag constants
453      * ({@link IResource#ALLOW_MISSING_LOCAL} and {@link IResource#REPLACE})
454      * @param monitor a progress monitor, or <code>null</code> if progress
455      * reporting is not desired
456      * @exception CoreException if this method fails. Reasons include:
457      * <ul>
458      * <li> This resource already exists in the workspace.</li>
459      * <li> The workspace contains a resource of a different type
460      * at the same path as this resource.</li>
461      * <li> The parent of this resource does not exist.</li>
462      * <li> The parent of this resource is not an open project</li>
463      * <li> The name of this resource is not valid (according to
464      * <code>IWorkspace.validateName</code>).</li>
465      * <li> The corresponding location in the file system does not exist, or
466      * is relative to an undefined variable, and <code>ALLOW_MISSING_LOCAL</code> is
467      * not specified.</li>
468      * <li> The corresponding location in the file system is occupied
469      * by a directory (as opposed to a file).</li>
470      * <li> Resource changes are disallowed during certain types of resource change
471      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
472      * <li>The team provider for the project which contains this folder does not permit
473      * linked resources.</li>
474      * <li>This folder's project contains a nature which does not permit linked resources.</li>
475      * </ul>
476      * @exception OperationCanceledException if the operation is canceled.
477      * Cancelation can occur even if no progress monitor is provided.
478      * @see IResource#isLinked()
479      * @see IResource#ALLOW_MISSING_LOCAL
480      * @since 3.2
481      */
482     public void createLink(URI location, int updateFlags, IProgressMonitor monitor) throws CoreException;
483
484     /**
485      * Deletes this file from the workspace.
486      * <p>
487      * This is a convenience method, fully equivalent to:
488      * <pre>
489      * delete((keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);
490      * </pre>
491      * </p>
492      * <p>
493      * This method changes resources; these changes will be reported
494      * in a subsequent resource change event, including an indication
495      * that this folder has been removed from its parent.
496      * </p>
497      * <p>
498      * This method is long-running; progress and cancellation are provided
499      * by the given progress monitor.
500      * </p>
501      *
502      * @param force a flag controlling whether resources that are not
503      * in sync with the local file system will be tolerated
504      * @param keepHistory a flag controlling whether files under this folder
505      * should be stored in the workspace's local history
506      * @param monitor a progress monitor, or <code>null</code> if progress
507      * reporting is not desired
508      * @exception CoreException if this method fails. Reasons include:
509      * <ul>
510      * <li> This resource could not be deleted for some reason.</li>
511      * <li> This resource is out of sync with the local file system
512      * and <code>force</code> is <code>false</code>.</li>
513      * <li> Resource changes are disallowed during certain types of resource change
514      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
515      * </ul>
516      * @exception OperationCanceledException if the operation is canceled.
517      * Cancelation can occur even if no progress monitor is provided.
518      * @see IResource#delete(int,IProgressMonitor)
519      * @see IResourceRuleFactory#deleteRule(IResource)
520      */
521     public void delete(boolean force, boolean keepHistory, IProgressMonitor monitor) throws CoreException;
522
523     /**
524      * Returns the name of a charset to be used when decoding the contents of this
525      * file into characters.
526      * <p>
527      * This refinement of the corresponding <code>IEncodingStorage</code> method
528      * is a convenience method, fully equivalent to:
529      * <pre>
530      * getCharset(true);
531      * </pre>
532      * </p><p>
533      * <b>Note</b>: this method does not check whether the result is a supported
534      * charset name. Callers should be prepared to handle
535      * <code>UnsupportedEncodingException</code> where this charset is used.
536      * </p>
537      *
538      * @return the name of a charset
539      * @exception CoreException if this method fails. Reasons include:
540      * <ul>
541      * <li> This resource could not be read.</li>
542      * <li> This resource is not local.</li>
543      * <li> The corresponding location in the local file system
544      * is occupied by a directory.</li>
545      * </ul>
546      * @see IFile#getCharset(boolean)
547      * @see IEncodedStorage#getCharset()
548      * @see IContainer#getDefaultCharset()
549      * @since 3.0
550      */
551     public String getCharset() throws CoreException;
552
553     /**
554      * Returns the name of a charset to be used when decoding the contents of this
555      * file into characters.
556      * <p>
557      * If checkImplicit is <code>false</code>, this method will return the
558      * charset defined by calling <code>setCharset</code>, provided this file
559      * exists, or <code>null</code> otherwise.
560      * </p><p>
561      * If checkImplicit is <code>true</code>, this method uses the following
562      * algorithm to determine the charset to be returned:
563      * <ol>
564      * <li>the charset defined by calling #setCharset, if any, and this file
565      * exists, or</li>
566      * <li>the charset automatically discovered based on this file's contents,
567      * if one can be determined, or</li>
568      * <li>the default encoding for this file's parent (as defined by
569      * <code>IContainer#getDefaultCharset</code>).</li>
570      * </ol>
571      * </p><p>
572      * <b>Note</b>: this method does not check whether the result is a supported
573      * charset name. Callers should be prepared to handle
574      * <code>UnsupportedEncodingException</code> where this charset is used.
575      * </p>
576      *
577      * @return the name of a charset, or <code>null</code>
578      * @exception CoreException if this method fails. Reasons include:
579      * <ul>
580      * <li> This resource could not be read.</li>
581      * <li> This resource is not local.</li>
582      * <li> The corresponding location in the local file system
583      * is occupied by a directory.</li>
584      * </ul>
585      * @see IEncodedStorage#getCharset()
586      * @see IContainer#getDefaultCharset()
587      * @since 3.0
588      */
589     public String getCharset(boolean checkImplicit) throws CoreException;
590     
591     /**
592      * Returns the name of a charset to be used to encode the given contents
593      * when saving to this file. This file does not have to exist. The character stream is <em>not</em> automatically closed.
594      * <p>
595      * This method uses the following algorithm to determine the charset to be returned:
596      * <ol>
597      * <li>if this file exists, the charset returned by IFile#getCharset(false), if one is defined, or</li>
598      * <li>the charset automatically discovered based on the file name and the given contents,
599      * if one can be determined, or</li>
600      * <li>the default encoding for the parent resource (as defined by
601      * <code>IContainer#getDefaultCharset</code>).</li>
602      * </ol>
603      * </p><p>
604      * <b>Note</b>: this method does not check whether the result is a supported
605      * charset name. Callers should be prepared to handle
606      * <code>UnsupportedEncodingException</code> where this charset is used.
607      * </p>
608      *
609      * @param reader a character stream containing the contents to be saved into this file
610      * @return the name of a charset
611      * @exception CoreException if this method fails. Reasons include:
612      * <ul>
613      * <li>The given character stream could not be read.</li>
614      * </ul>
615      * @see #getCharset(boolean)
616      * @see IContainer#getDefaultCharset()
617      * @since 3.1
618      */
619     public String getCharsetFor(Reader reader) throws CoreException;
620
621     /**
622      * Returns a description for this file's current contents. Returns
623      * <code>null</code> if a description cannot be obtained.
624      * <p>
625      * Calling this method produces a similar effect as calling
626      * <code>getDescriptionFor(getContents(), getName(), IContentDescription.ALL)</code>
627      * on <code>IContentTypeManager</code>, but provides better
628      * opportunities for improved performance. Therefore, when manipulating
629      * <code>IFile</code>s, clients should call this method instead of
630      * <code>IContentTypeManager.getDescriptionFor</code>.
631      * </p>
632      *
633      * @return a description for this file's current contents, or
634      * <code>null</code>
635      * @exception CoreException if this method fails. Reasons include:
636      * <ul>
637      * <li> This resource does not exist.</li>
638      * <li> This resource could not be read.</li>
639      * <li> This resource is not local.</li>
640      * <li> The corresponding location in the local file system
641      * is occupied by a directory.</li>
642      * </ul>
643      * @see IContentDescription
644      * @see IContentTypeManager#getDescriptionFor(InputStream, String, QualifiedName[])
645      * @since 3.0
646      */
647     public IContentDescription getContentDescription() throws CoreException;
648
649     /**
650      * Returns an open input stream on the contents of this file.
651      * This refinement of the corresponding <code>IStorage</code> method
652      * returns an open input stream on the contents of this file.
653      * The client is responsible for closing the stream when finished.
654      *
655      * @return an input stream containing the contents of the file
656      * @exception CoreException if this method fails. Reasons include:
657      * <ul>
658      * <li> This resource does not exist.</li>
659      * <li> This resource is not local.</li>
660      * <li> The workspace is not in sync with the corresponding location
661      * in the local file system.</li>
662      * </ul>
663      */
664     public InputStream getContents() throws CoreException;
665
666     /**
667      * This refinement of the corresponding <code>IStorage</code> method
668      * returns an open input stream on the contents of this file.
669      * The client is responsible for closing the stream when finished.
670      * If force is <code>true</code> the file is opened and an input
671      * stream returned regardless of the sync state of the file. The file
672      * is not synchronized with the workspace.
673      * If force is <code>false</code> the method fails if not in sync.
674      *
675      * @param force a flag controlling how to deal with resources that
676      * are not in sync with the local file system
677      * @return an input stream containing the contents of the file
678      * @exception CoreException if this method fails. Reasons include:
679      * <ul>
680      * <li> This resource does not exist.</li>
681      * <li> This resource is not local.</li>
682      * <li> The workspace is not in sync with the corresponding location
683      * in the local file system and force is <code>false</code>.</li>
684      * </ul>
685      */
686     public InputStream getContents(boolean force) throws CoreException;
687
688     /**
689      * Returns a constant identifying the character encoding of this file, or
690      * ENCODING_UNKNOWN if it could not be determined. The returned constant
691      * will be one of the ENCODING_* constants defined on IFile.
692      *
693      * This method attempts to guess the file's character encoding by analyzing
694      * the first few bytes of the file. If no identifying pattern is found at the
695      * beginning of the file, ENC_UNKNOWN will be returned. This method will
696      * not attempt any complex analysis of the file to make a guess at the
697      * encoding that is used.
698      *
699      * @return The character encoding of this file
700      * @exception CoreException if this method fails. Reasons include:
701      * <ul>
702      * <li> This resource does not exist.</li>
703      * <li> This resource could not be read.</li>
704      * <li> This resource is not local.</li>
705      * <li> The corresponding location in the local file system
706      * is occupied by a directory.</li>
707      * </ul>
708      * @deprecated use IFile#getCharset instead
709      */
710     public int getEncoding() throws CoreException;
711
712     /**
713      * Returns the full path of this file.
714      * This refinement of the corresponding <code>IStorage</code> and <code>IResource</code>
715      * methods links the semantics of resource and storage object paths such that
716      * <code>IFile</code>s always have a path and that path is relative to the
717      * containing workspace.
718      *
719      * @see IResource#getFullPath()
720      * @see IStorage#getFullPath()
721      */
722     public IPath getFullPath();
723
724     /**
725      * Returns a list of past states of this file known to this workspace.
726      * Recently added states first.
727      * <p>
728      * This method is long-running; progress and cancellation are provided
729      * by the given progress monitor.
730      * </p>
731      *
732      * @param monitor a progress monitor, or <code>null</code> if progress
733      * reporting is not desired
734      * @return an array of states of this file
735      * @exception CoreException if this method fails.
736      * @exception OperationCanceledException if the operation is canceled.
737      * Cancelation can occur even if no progress monitor is provided.
738      */
739     public IFileState[] getHistory(IProgressMonitor monitor) throws CoreException;
740
741     /**
742      * Returns the name of this file.
743      * This refinement of the corresponding <code>IStorage</code> and <code>IResource</code>
744      * methods links the semantics of resource and storage object names such that
745      * <code>IFile</code>s always have a name and that name equivalent to the
746      * last segment of its full path.
747      *
748      * @see IResource#getName()
749      * @see IStorage#getName()
750      */
751     public String getName();
752
753     /**
754      * Returns whether this file is read-only.
755      * This refinement of the corresponding <code>IStorage</code> and <code>IResource</code>
756      * methods links the semantics of read-only resources and read-only storage objects.
757      *
758      * @see IResource#isReadOnly()
759      * @see IStorage#isReadOnly()
760      */
761     public boolean isReadOnly();
762
763     /**
764      * Moves this resource to be at the given location.
765      * <p>
766      * This is a convenience method, fully equivalent to:
767      * <pre>
768      * move(destination, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);
769      * </pre>
770      * </p>
771      * <p>
772      * This method changes resources; these changes will be reported
773      * in a subsequent resource change event, including an indication
774      * that this file has been removed from its parent and a new file
775      * has been added to the parent of the destination.
776      * </p>
777      * <p>
778      * This method is long-running; progress and cancellation are provided
779      * by the given progress monitor.
780      * </p>
781      *
782      * @param destination the destination path
783      * @param force a flag controlling whether resources that are not
784      * in sync with the local file system will be tolerated
785      * @param keepHistory a flag controlling whether files under this folder
786      * should be stored in the workspace's local history
787      * @param monitor a progress monitor, or <code>null</code> if progress
788      * reporting is not desired
789      * @exception CoreException if this resource could not be moved. Reasons include:
790      * <ul>
791      * <li> This resource does not exist.</li>
792      * <li> This resource is not local.</li>
793      * <li> The resource corresponding to the parent destination path does not exist.</li>
794      * <li> The resource corresponding to the parent destination path is a closed
795      * project.</li>
796      * <li> A resource at destination path does exist.</li>
797      * <li> A resource of a different type exists at the destination path.</li>
798      * <li> This resource is out of sync with the local file system
799      * and <code>force</code> is <code>false</code>.</li>
800      * <li> The workspace and the local file system are out of sync
801      * at the destination resource or one of its descendents.</li>
802      * <li> Resource changes are disallowed during certain types of resource change
803      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
804      * </ul>
805      * @exception OperationCanceledException if the operation is canceled.
806      * Cancelation can occur even if no progress monitor is provided.
807      *
808      * @see IResource#move(IPath,int,IProgressMonitor)
809      * @see IResourceRuleFactory#moveRule(IResource, IResource)
810      */
811     public void move(IPath destination, boolean force, boolean keepHistory, IProgressMonitor monitor) throws CoreException;
812
813     /**
814      * Sets the charset for this file. Passing a value of <code>null</code>
815      * will remove the charset setting for this resource.
816      *
817      * @param newCharset a charset name, or <code>null</code>
818      * @exception CoreException if this method fails. Reasons include:
819      * <ul>
820      * <li> This resource does not exist.</li>
821      * <li> An error happened while persisting this setting.</li>
822      * </ul>
823      * @see #getCharset()
824      * @since 3.0
825      * @deprecated Replaced by {@link #setCharset(String, IProgressMonitor)} which
826      * is a workspace operation and reports changes in resource deltas.
827      */
828     public void setCharset(String newCharset) throws CoreException;
829
830     /**
831      * Sets the charset for this file. Passing a value of <code>null</code>
832      * will remove the charset setting for this resource.
833      * <p>
834      * This method changes resources; these changes will be reported
835      * in a subsequent resource change event, including an indication
836      * that this file's encoding has changed.
837      * </p>
838      * <p>
839      * This method is long-running; progress and cancellation are provided
840      * by the given progress monitor.
841      * </p>
842      *
843      * @param newCharset a charset name, or <code>null</code>
844      * @param monitor a progress monitor, or <code>null</code> if progress
845      * reporting is not desired
846      * @exception OperationCanceledException if the operation is canceled.
847      * Cancelation can occur even if no progress monitor is provided.
848      * @exception CoreException if this method fails. Reasons include:
849      * <ul>
850      * <li> This resource does not exist.</li>
851      * <li> An error happened while persisting this setting.</li>
852      * <li> Resource changes are disallowed during certain types of resource change
853      * event notification. See {@link IResourceChangeEvent} for more details.</li>
854      * </ul>
855      * @see #getCharset()
856      * @see IResourceRuleFactory#charsetRule(IResource)
857      * @since 3.0
858      */
859     public void setCharset(String newCharset, IProgressMonitor monitor) throws CoreException;
860
861     /**
862      * Sets the contents of this file to the bytes in the given input stream.
863      * <p>
864      * This is a convenience method, fully equivalent to:
865      * <pre>
866      * setContents(source, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);
867      * </pre>
868      * </p>
869      * <p>
870      * This method changes resources; these changes will be reported
871      * in a subsequent resource change event, including an indication
872      * that this file's contents have been changed.
873      * </p>
874      * <p>
875      * This method is long-running; progress and cancellation are provided
876      * by the given progress monitor.
877      * </p>
878      *
879      * @param source an input stream containing the new contents of the file
880      * @param force a flag controlling how to deal with resources that
881      * are not in sync with the local file system
882      * @param keepHistory a flag indicating whether or not store
883      * the current contents in the local history
884      * @param monitor a progress monitor, or <code>null</code> if progress
885      * reporting is not desired
886      * @exception CoreException if this method fails. Reasons include:
887      * <ul>
888      * <li> This resource does not exist.</li>
889      * <li> The corresponding location in the local file system
890      * is occupied by a directory.</li>
891      * <li> The workspace is not in sync with the corresponding location
892      * in the local file system and <code>force </code> is <code>false</code>.</li>
893      * <li> Resource changes are disallowed during certain types of resource change
894      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
895      * <li> The file modification validator disallowed the change.</li>
896      * </ul>
897      * @exception OperationCanceledException if the operation is canceled.
898      * Cancelation can occur even if no progress monitor is provided.
899      * @see #setContents(java.io.InputStream,int,IProgressMonitor)
900      */
901     public void setContents(InputStream source, boolean force, boolean keepHistory, IProgressMonitor monitor) throws CoreException;
902
903     /**
904      * Sets the contents of this file to the bytes in the given file state.
905      * <p>
906      * This is a convenience method, fully equivalent to:
907      * <pre>
908      * setContents(source, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);
909      * </pre>
910      * </p>
911      * <p>
912      * This method changes resources; these changes will be reported
913      * in a subsequent resource change event, including an indication
914      * that this file's content have been changed.
915      * </p>
916      * <p>
917      * This method is long-running; progress and cancellation are provided
918      * by the given progress monitor.
919      * </p>
920      *
921      * @param source a previous state of this resource
922      * @param force a flag controlling how to deal with resources that
923      * are not in sync with the local file system
924      * @param keepHistory a flag indicating whether or not store
925      * the current contents in the local history
926      * @param monitor a progress monitor, or <code>null</code> if progress
927      * reporting is not desired
928      * @exception CoreException if this method fails. Reasons include:
929      * <ul>
930      * <li> This resource does not exist.</li>
931      * <li> The state does not exist.</li>
932      * <li> The corresponding location in the local file system
933      * is occupied by a directory.</li>
934      * <li> The workspace is not in sync with the corresponding location
935      * in the local file system and <code>force </code> is <code>false</code>.</li>
936      * <li> Resource changes are disallowed during certain types of resource change
937      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
938      * <li> The file modification validator disallowed the change.</li>
939      * </ul>
940      * @exception OperationCanceledException if the operation is canceled.
941      * Cancelation can occur even if no progress monitor is provided.
942      * @see #setContents(IFileState,int,IProgressMonitor)
943      */
944     public void setContents(IFileState source, boolean force, boolean keepHistory, IProgressMonitor monitor) throws CoreException;
945
946     /**
947      * Sets the contents of this file to the bytes in the given input stream.
948      * The stream will get closed whether this method succeeds or fails.
949      * If the stream is <code>null</code> then the content is set to be the
950      * empty sequence of bytes.
951      * <p>
952      * The <code>FORCE</code> update flag controls how this method deals with
953      * cases where the workspace is not completely in sync with the local file
954      * system. If <code>FORCE</code> is not specified, the method will only attempt
955      * to overwrite a corresponding file in the local file system provided
956      * it is in sync with the workspace. This option ensures there is no
957      * unintended data loss; it is the recommended setting.
958      * However, if <code>FORCE</code> is specified, an attempt will be made
959      * to write a corresponding file in the local file system, overwriting any
960      * existing one if need be. In either case, if this method succeeds, the
961      * resource will be marked as being local (even if it wasn't before).
962      * </p>
963      * <p>
964      * The <code>KEEP_HISTORY</code> update flag controls whether or not a copy of
965      * current contents of this file should be captured in the workspace's local
966      * history (properties are not recorded in the local history). The local history
967      * mechanism serves as a safety net to help the user recover from mistakes that
968      * might otherwise result in data loss. Specifying <code>KEEP_HISTORY</code>
969      * is recommended except in circumstances where past states of the files are of
970      * no conceivable interest to the user. Note that local history is maintained
971      * with each individual project, and gets discarded when a project is deleted
972      * from the workspace. This flag is ignored if the file was not previously local.
973      * </p>
974      * <p>
975      * Update flags other than <code>FORCE</code> and <code>KEEP_HISTORY</code>
976      * are ignored.
977      * </p>
978      * <p>
979      * Prior to modifying the contents of this file, the file modification validator (if provided
980      * by the VCM plug-in), will be given a chance to perform any last minute preparations. Validation
981      * is performed by calling <code>IFileModificationValidator.validateSave</code> on this file.
982      * If the validation fails, then this operation will fail.
983      * </p>
984      * <p>
985      * This method changes resources; these changes will be reported
986      * in a subsequent resource change event, including an indication
987      * that this file's content have been changed.
988      * </p>
989      * <p>
990      * This method is long-running; progress and cancellation are provided
991      * by the given progress monitor.
992      * </p>
993      *
994      * @param source an input stream containing the new contents of the file
995      * @param updateFlags bit-wise or of update flag constants
996      * (<code>FORCE</code> and <code>KEEP_HISTORY</code>)
997      * @param monitor a progress monitor, or <code>null</code> if progress
998      * reporting is not desired
999      * @exception CoreException if this method fails. Reasons include:
1000     * <ul>
1001     * <li> This resource does not exist.</li>
1002     * <li> The corresponding location in the local file system
1003     * is occupied by a directory.</li>
1004     * <li> The workspace is not in sync with the corresponding location
1005     * in the local file system and <code>FORCE</code> is not specified.</li>
1006     * <li> Resource changes are disallowed during certain types of resource change
1007     * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
1008     * <li> The file modification validator disallowed the change.</li>
1009     * </ul>
1010     * @exception OperationCanceledException if the operation is canceled.
1011     * Cancelation can occur even if no progress monitor is provided.
1012     * @see IResourceRuleFactory#modifyRule(IResource)
1013     * @since 2.0
1014     */
1015    public void setContents(InputStream source, int updateFlags, IProgressMonitor monitor) throws CoreException;
1016
1017    /**
1018     * Sets the contents of this file to the bytes in the given file state.
1019     * <p>
1020     * The <code>FORCE</code> update flag controls how this method deals with
1021     * cases where the workspace is not completely in sync with the local file
1022     * system. If <code>FORCE</code> is not specified, the method will only attempt
1023     * to overwrite a corresponding file in the local file system provided
1024     * it is in sync with the workspace. This option ensures there is no
1025     * unintended data loss; it is the recommended setting.
1026     * However, if <code>FORCE</code> is specified, an attempt will be made
1027     * to write a corresponding file in the local file system, overwriting any
1028     * existing one if need be. In either case, if this method succeeds, the
1029     * resource will be marked as being local (even if it wasn't before).
1030     * </p>
1031     * <p>
1032     * The <code>KEEP_HISTORY</code> update flag controls whether or not a copy of
1033     * current contents of this file should be captured in the workspace's local
1034     * history (properties are not recorded in the local history). The local history
1035     * mechanism serves as a safety net to help the user recover from mistakes that
1036     * might otherwise result in data loss. Specifying <code>KEEP_HISTORY</code>
1037     * is recommended except in circumstances where past states of the files are of
1038     * no conceivable interest to the user. Note that local history is maintained
1039     * with each individual project, and gets discarded when a project is deleted
1040     * from the workspace. This flag is ignored if the file was not previously local.
1041     * </p>
1042     * <p>
1043     * Update flags other than <code>FORCE</code> and <code>KEEP_HISTORY</code>
1044     * are ignored.
1045     * </p>
1046     * <p>
1047     * Prior to modifying the contents of this file, the file modification validator (if provided
1048     * by the VCM plug-in), will be given a chance to perform any last minute preparations. Validation
1049     * is performed by calling <code>IFileModificationValidator.validateSave</code> on this file.
1050     * If the validation fails, then this operation will fail.
1051     * </p>
1052     * <p>
1053     * This method changes resources; these changes will be reported
1054     * in a subsequent resource change event, including an indication
1055     * that this file's content have been changed.
1056     * </p>
1057     * <p>
1058     * This method is long-running; progress and cancellation are provided
1059     * by the given progress monitor.
1060     * </p>
1061     *
1062     * @param source a previous state of this resource
1063     * @param updateFlags bit-wise or of update flag constants
1064     * (<code>FORCE</code> and <code>KEEP_HISTORY</code>)
1065     * @param monitor a progress monitor, or <code>null</code> if progress
1066     * reporting is not desired
1067     * @exception CoreException if this method fails. Reasons include:
1068     * <ul>
1069     * <li> This resource does not exist.</li>
1070     * <li> The state does not exist.</li>
1071     * <li> The corresponding location in the local file system
1072     * is occupied by a directory.</li>
1073     * <li> The workspace is not in sync with the corresponding location
1074     * in the local file system and <code>FORCE</code> is not specified.</li>
1075     * <li> Resource changes are disallowed during certain types of resource change
1076     * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
1077     * <li> The file modification validator disallowed the change.</li>
1078     * </ul>
1079     * @exception OperationCanceledException if the operation is canceled.
1080     * Cancelation can occur even if no progress monitor is provided.
1081     * @see IResourceRuleFactory#modifyRule(IResource)
1082     * @since 2.0
1083     */
1084    public void setContents(IFileState source, int updateFlags, IProgressMonitor monitor) throws CoreException;
1085}
1086

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags