Eclipse Platform Release 3.7

## org.eclipse.core.resources
Interface IFile

All Superinterfaces:
  IAdaptable, IEncodedStorage, IResource, ISchedulingRule, IStorage

    public interface IFile

extends IResource, IEncodedStorage, IAdaptable

Files are leaf resources which contain data. The contents of a file resource is stored as a file in the local file system.

Files, like folders, may exist in the workspace but not be local; non-local file resources serve as place-holders for files whose content and properties have not yet been fetched from a repository.

Files implement the `IAdaptable` interface; extensions are managed by the platform's adapter manager.

See Also:
  `Platform.getAdapterManager()`
Restriction:
  This interface is not intended to be implemented by clients.
Restriction:
  This interface is not intended to be extended by clients.

Field Summary
`static int` `ENCODING_ISO_8859_1` Deprecated. see getEncoding for details
`static int` `ENCODING_UNKNOWN` Deprecated. see getEncoding for details
`static int` `ENCODING_US_ASCII` Deprecated. see getEncoding for details
`static int` `ENCODING_UTF_16` Deprecated. see getEncoding for details
`static int` `ENCODING_UTF_16BE` Deprecated. see getEncoding for details
`static int` `ENCODING_UTF_16LE` Deprecated. see getEncoding for details
`static int` `ENCODING_UTF_8` Deprecated. see getEncoding for details

Fields inherited from interface org.eclipse.core.resources.IResource
`ALLOW_MISSING_LOCAL, ALWAYS_DELETE_PROJECT_CONTENT, AVOID_NATURE_CONFIG, BACKGROUND_REFRESH, CHECK_ANCESTORS, DEPTH_INFINITE, DEPTH_ONE, DEPTH_ZERO, DERIVED, FILE, FOLDER, FORCE, HIDDEN, KEEP_HISTORY, NEVER_DELETE_PROJECT_CONTENT, NONE, NULL_STAMP, PROJECT, REPLACE, ROOT, SHALLOW, TEAM_PRIVATE, VIRTUAL`

Method Summary
`void` `appendContents(InputStream source, boolean force, boolean keepHistory, IProgressMonitor monitor)` Appends the entire contents of the given stream to this file.
`void` `appendContents(InputStream source, int updateFlags, IProgressMonitor monitor)` Appends the entire contents of the given stream to this file.
`void` `create(InputStream source, boolean force, IProgressMonitor monitor)` Creates a new file resource as a member of this handle's parent resource.
`void` `create(InputStream source, int updateFlags, IProgressMonitor monitor)` Creates a new file resource as a member of this handle's parent resource.
`void` `createLink(IPath localLocation, int updateFlags, IProgressMonitor monitor)` Creates a new file resource as a member of this handle's parent resource.
`void` `createLink(URI location, int updateFlags, IProgressMonitor monitor)` Creates a new file resource as a member of this handle's parent resource.
`void` `delete(boolean force, boolean keepHistory, IProgressMonitor monitor)` Deletes this file from the workspace.
`String` `getCharset()` Returns the name of a charset to be used when decoding the contents of this file into characters.
`String` `getCharset(boolean checkImplicit)` Returns the name of a charset to be used when decoding the contents of this file into characters.
`String` `getCharsetFor(Reader reader)` Returns the name of a charset to be used to encode the given contents when saving to this file.
`IContentDescription` `getContentDescription()` Returns a description for this file's current contents.
`InputStream` `getContents()` Returns an open input stream on the contents of this file.
`InputStream` `getContents(boolean force)` This refinement of the corresponding `IStorage` method returns an open input stream on the contents of this file.
`int` `getEncoding()` Deprecated. use IFile#getCharset instead
`IPath` `getFullPath()` Returns the full path of this file.
`IFileState[]` `getHistory(IProgressMonitor monitor)` Returns a list of past states of this file known to this workspace.
`String` `getName()` Returns the name of this file.
`boolean` `isReadOnly()` Returns whether this file is read-only.
`void` `move(IPath destination, boolean force, boolean keepHistory, IProgressMonitor monitor)` Moves this resource to be at the given location.
`void` `setCharset(String newCharset)` Deprecated. Replaced by `setCharset(String, IProgressMonitor)` which is a workspace operation and reports changes in resource deltas.
`void` `setCharset(String newCharset, IProgressMonitor monitor)` Sets the charset for this file.
`void` `setContents(IFileState source, boolean force, boolean keepHistory, IProgressMonitor monitor)` Sets the contents of this file to the bytes in the given file state.
`void` `setContents(IFileState source, int updateFlags, IProgressMonitor monitor)` Sets the contents of this file to the bytes in the given file state.
`void` `setContents(InputStream source, boolean force, boolean keepHistory, IProgressMonitor monitor)` Sets the contents of this file to the bytes in the given input stream.
`void` `setContents(InputStream source, int updateFlags, IProgressMonitor monitor)` Sets the contents of this file to the bytes in the given input stream.

Methods inherited from interface org.eclipse.core.resources.IResource

`accept, accept, accept, accept, clearHistory, copy, copy, copy, copy, createMarker, createProxy, delete, delete, deleteMarkers, equals, exists, findMarker, findMarkers, findMaxProblemSeverity, getFileExtension, getLocalTimeStamp, getLocation, getLocationURI, getMarker, getModificationStamp, getParent, getPathVariableManager, getPersistentProperties, getPersistentProperty, getProject, getProjectRelativePath, getRawLocation, getRawLocationURI, getResourceAttributes, getSessionProperties, getSessionProperty, getType, getWorkspace, isAccessible, isDerived, isDerived, isHidden, isHidden, isLinked, isLinked, isLocal, isPhantom, isSynchronized, isTeamPrivateMember, isTeamPrivateMember, isVirtual, move, move, move, move, refreshLocal, revertModificationStamp, setDerived, setDerived, setHidden, setLocal, setLocalTimeStamp, setPersistentProperty, setReadOnly, setResourceAttributes, setSessionProperty, setTeamPrivateMember, touch`

Methods inherited from interface org.eclipse.core.runtime.jobs.ISchedulingRule
`contains, isConflicting`

Field Detail

### ENCODING_UNKNOWN

    static final int ENCODING_UNKNOWN

  Deprecated. see getEncoding for details
  Character encoding constant (value 0) which identifies files that have an unknown character encoding scheme.

  See Also:
    `getEncoding()`, Constant Field Values

### ENCODING_US_ASCII

    static final int ENCODING_US_ASCII

  Deprecated. see getEncoding for details
  Character encoding constant (value 1) which identifies files that are encoded with the US-ASCII character encoding scheme.

  See Also:
    `getEncoding()`, Constant Field Values

### ENCODING_ISO_8859_1

    static final int ENCODING_ISO_8859_1

  Deprecated. see getEncoding for details
  Character encoding constant (value 2) which identifies files that are encoded with the ISO-8859-1 character encoding scheme, also known as ISO-LATIN-1.

  See Also:
    `getEncoding()`, Constant Field Values

### ENCODING_UTF_8

    static final int ENCODING_UTF_8

  Deprecated. see getEncoding for details
  Character encoding constant (value 3) which identifies files that are encoded with the UTF-8 character encoding scheme.

  See Also:
    `getEncoding()`, Constant Field Values

### ENCODING_UTF_16BE

    static final int ENCODING_UTF_16BE

  Deprecated. see getEncoding for details
  Character encoding constant (value 4) which identifies files that are encoded with the UTF-16BE character encoding scheme.

  See Also:
    `getEncoding()`, Constant Field Values

### ENCODING_UTF_16LE

    static final int ENCODING_UTF_16LE

  Deprecated. see getEncoding for details
  Character encoding constant (value 5) which identifies files that are encoded with the UTF-16LE character encoding scheme.

  See Also:
    `getEncoding()`, Constant Field Values

### ENCODING_UTF_16

    static final int ENCODING_UTF_16

  Deprecated. see getEncoding for details
  Character encoding constant (value 6) which identifies files that are encoded with the UTF-16 character encoding scheme.

  See Also:
    `getEncoding()`, Constant Field Values

Method Detail

### appendContents

    void appendContents(InputStream source,
                        boolean force,
                        boolean keepHistory,
                        IProgressMonitor monitor)
                        throws CoreException

  Appends the entire contents of the given stream to this file.

  This is a convenience method, fully equivalent to:

         appendContents(source, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this file's content have been changed.

  This method is long-running; progress and cancelation are provided by the given progress monitor.

  Parameters:
    `source` - an input stream containing the new contents of the file
    `force` - a flag controlling how to deal with resources that are not in sync with the local file system
    `keepHistory` - a flag indicating whether or not to store the current contents in the local history
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - The corresponding location in the local file system is occupied by a directory.
    - The workspace is not in sync with the corresponding location in the local file system and `force` is `false`.
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    - The file modification validator disallowed the change.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  See Also:
    `appendContents(java.io.InputStream,int,IProgressMonitor)`

### appendContents

    void appendContents(InputStream source,
                        int updateFlags,
                        IProgressMonitor monitor)
                        throws CoreException

  Appends the entire contents of the given stream to this file. The stream, which must not be `null`, will get closed whether this method succeeds or fails.

  The `FORCE` update flag controls how this method deals with cases where the workspace is not completely in sync with the local file system. If `FORCE` is not specified, the method will only attempt to overwrite a corresponding file in the local file system provided it is in sync with the workspace. This option ensures there is no unintended data loss; it is the recommended setting. However, if `FORCE` is specified, an attempt will be made to write a corresponding file in the local file system, overwriting any existing one if need be. In either case, if this method succeeds, the resource will be marked as being local (even if it wasn't before).

  If this file is non-local then this method will always fail. The only exception is when `FORCE` is specified and the file exists in the local file system. In this case the file is made local and the given contents are appended.

  The `KEEP_HISTORY` update flag controls whether or not a copy of current contents of this file should be captured in the workspace's local history (properties are not recorded in the local history). The local history mechanism serves as a safety net to help the user recover from mistakes that might otherwise result in data loss. Specifying `KEEP_HISTORY` is recommended except in circumstances where past states of the files are of no conceivable interest to the user. Note that local history is maintained with each individual project, and gets discarded when a project is deleted from the workspace. This flag is ignored if the file was not previously local.

  Update flags other than `FORCE` and `KEEP_HISTORY` are ignored.

  Prior to modifying the contents of this file, the file modification validator (if provided by the VCM plug-in), will be given a chance to perform any last minute preparations. Validation is performed by calling `IFileModificationValidator.validateSave` on this file. If the validation fails, then this operation will fail.

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this file's content have been changed.

  This method is long-running; progress and cancelation are provided by the given progress monitor.

  Parameters:
    `source` - an input stream containing the new contents of the file
    `updateFlags` - bit-wise or of update flag constants (`FORCE` and `KEEP_HISTORY`)
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - The corresponding location in the local file system is occupied by a directory.
    - The workspace is not in sync with the corresponding location in the local file system and `FORCE` is not specified.
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    - The file modification validator disallowed the change.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  Since:
    2.0
  See Also:
    `IResourceRuleFactory.modifyRule(IResource)`

### create

    void create(InputStream source,
                boolean force,
                IProgressMonitor monitor)
                throws CoreException

  Creates a new file resource as a member of this handle's parent resource.

  This is a convenience method, fully equivalent to:

         create(source, (force ? FORCE : IResource.NONE), monitor);

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that the file has been added to its parent.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `source` - an input stream containing the initial contents of the file, or `null` if the file should be marked as not local
    `force` - a flag controlling how to deal with resources that are not in sync with the local file system
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource already exists in the workspace.
    - The parent of this resource does not exist.
    - The parent of this resource is a virtual folder.
    - The project of this resource is not accessible.
    - The parent contains a resource of a different type at the same path as this resource.
    - The name of this resource is not valid (according to `IWorkspace.validateName`).
    - The corresponding location in the local file system is occupied by a directory.
    - The corresponding location in the local file system is occupied by a file and `force` is `false`.
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.

### create

    void create(InputStream source,
                int updateFlags,
                IProgressMonitor monitor)
                throws CoreException

  Creates a new file resource as a member of this handle's parent resource. The resource's contents are supplied by the data in the given stream. This method closes the stream whether it succeeds or fails. If the stream is `null` then a file is not created in the local file system and the created file resource is marked as being non-local.

  The `IResource.FORCE` update flag controls how this method deals with cases where the workspace is not completely in sync with the local file system. If `IResource.FORCE` is not specified, the method will only attempt to write a file in the local file system if it does not already exist. This option ensures there is no unintended data loss; it is the recommended setting. However, if `IResource.FORCE` is specified, this method will attempt to write a corresponding file in the local file system, overwriting any existing one if need be.

  The `IResource.DERIVED` update flag indicates that this resource should immediately be set as a derived resource. Specifying this flag is equivalent to atomically calling `IResource.setDerived(boolean)` with a value of `true` immediately after creating the resource.

  The `IResource.TEAM_PRIVATE` update flag indicates that this resource should immediately be set as a team private resource. Specifying this flag is equivalent to atomically calling `IResource.setTeamPrivateMember(boolean)` with a value of `true` immediately after creating the resource.

  The `IResource.HIDDEN` update flag indicates that this resource should immediately be set as a hidden resource. Specifying this flag is equivalent to atomically calling `IResource.setHidden(boolean)` with a value of `true` immediately after creating the resource.

  Update flags other than those listed above are ignored.

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that the file has been added to its parent.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `source` - an input stream containing the initial contents of the file, or `null` if the file should be marked as not local
    `updateFlags` - bit-wise or of update flag constants (`IResource.FORCE`, `IResource.DERIVED`, and `IResource.TEAM_PRIVATE`)
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource already exists in the workspace.
    - The parent of this resource does not exist.
    - The parent of this resource is a virtual folder.
    - The project of this resource is not accessible.
    - The parent contains a resource of a different type at the same path as this resource.
    - The name of this resource is not valid (according to `IWorkspace.validateName`).
    - The corresponding location in the local file system is occupied by a directory.
    - The corresponding location in the local file system is occupied by a file and `FORCE` is not specified.
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  Since:
    2.0
  See Also:
    `IResourceRuleFactory.createRule(IResource)`

### createLink

    void createLink(IPath localLocation,
                    int updateFlags,
                    IProgressMonitor monitor)
                    throws CoreException

  Creates a new file resource as a member of this handle's parent resource. The file's contents will be located in the file specified by the given file system path. The given path must be either an absolute file system path, or a relative path whose first segment is the name of a workspace path variable.

  The `IResource.ALLOW_MISSING_LOCAL` update flag controls how this method deals with cases where the local file system file to be linked does not exist, or is relative to a workspace path variable that is not defined. If `IResource.ALLOW_MISSING_LOCAL` is specified, the operation will succeed even if the local file is missing, or the path is relative to an undefined variable. If `IResource.ALLOW_MISSING_LOCAL` is not specified, the operation will fail in the case where the local file system file does not exist or the path is relative to an undefined variable.

  The `IResource.REPLACE` update flag controls how this method deals with cases where a resource of the same name as the prospective link already exists. If `IResource.REPLACE` is specified, then the existing linked resource's location is replaced by localLocation's value. This does not cause the underlying file system contents of that resource to be deleted. If `IResource.REPLACE` is not specified, this method will fail if an existing resource exists of the same name.

  The `IResource.HIDDEN` update flag indicates that this resource should immediately be set as a hidden resource. Specifying this flag is equivalent to atomically calling `IResource.setHidden(boolean)` with a value of `true` immediately after creating the resource.

  Update flags other than those listed above are ignored.

  This method synchronizes this resource with the local file system at the given location.

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that the file has been added to its parent.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `localLocation` - a file system path where the file should be linked
    `updateFlags` - bit-wise or of update flag constants (`IResource.ALLOW_MISSING_LOCAL`, `IResource.REPLACE` and `IResource.HIDDEN`)
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource already exists in the workspace.
    - The workspace contains a resource of a different type at the same path as this resource.
    - The parent of this resource does not exist.
    - The parent of this resource is not an open project
    - The name of this resource is not valid (according to `IWorkspace.validateName`).
    - The corresponding location in the local file system does not exist, or is relative to an undefined variable, and `ALLOW_MISSING_LOCAL` is not specified.
    - The corresponding location in the local file system is occupied by a directory (as opposed to a file).
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    - The team provider for the project which contains this folder does not permit linked resources.
    - This folder's project contains a nature which does not permit linked resources.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  Since:
    2.1
  See Also:
    `IResource.isLinked()`, `IResource.ALLOW_MISSING_LOCAL`, `IResource.REPLACE`, `IResource.HIDDEN`

### createLink

    void createLink(URI location,
                    int updateFlags,
                    IProgressMonitor monitor)
                    throws CoreException

  Creates a new file resource as a member of this handle's parent resource. The file's contents will be located in the file specified by the given URI. The given URI must be either absolute, or a relative URI whose first path segment is the name of a workspace path variable.

  The `ALLOW_MISSING_LOCAL` update flag controls how this method deals with cases where the file system file to be linked does not exist, or is relative to a workspace path variable that is not defined. If `ALLOW_MISSING_LOCAL` is specified, the operation will succeed even if the local file is missing, or the path is relative to an undefined variable. If `ALLOW_MISSING_LOCAL` is not specified, the operation will fail in the case where the file system file does not exist or the path is relative to an undefined variable.

  The `IResource.REPLACE` update flag controls how this method deals with cases where a resource of the same name as the prospective link already exists. If `IResource.REPLACE` is specified, then any existing resource with the same name is removed from the workspace to make way for creation of the link. This does not cause the underlying file system contents of that resource to be deleted. If `IResource.REPLACE` is not specified, this method will fail if an existing resource exists of the same name.

  The `IResource.HIDDEN` update flag indicates that this resource should immediately be set as a hidden resource. Specifying this flag is equivalent to atomically calling `IResource.setHidden(boolean)` with a value of `true` immediately after creating the resource.

  Update flags other than those listed above are ignored.

  This method synchronizes this resource with the file system at the given location.

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that the file has been added to its parent.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `location` - a file system URI where the file should be linked
    `updateFlags` - bit-wise or of update flag constants (`IResource.ALLOW_MISSING_LOCAL`, `IResource.REPLACE` and `IResource.HIDDEN`)
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource already exists in the workspace.
    - The workspace contains a resource of a different type at the same path as this resource.
    - The parent of this resource does not exist.
    - The parent of this resource is not an open project
    - The name of this resource is not valid (according to `IWorkspace.validateName`).
    - The corresponding location in the file system does not exist, or is relative to an undefined variable, and `ALLOW_MISSING_LOCAL` is not specified.
    - The corresponding location in the file system is occupied by a directory (as opposed to a file).
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    - The team provider for the project which contains this folder does not permit linked resources.
    - This folder's project contains a nature which does not permit linked resources.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  Since:
    3.2
  See Also:
    `IResource.isLinked()`, `IResource.ALLOW_MISSING_LOCAL`, `IResource.REPLACE`, `IResource.HIDDEN`

### delete

    void delete(boolean force,
                boolean keepHistory,
                IProgressMonitor monitor)
                throws CoreException

  Deletes this file from the workspace.

  This is a convenience method, fully equivalent to:

         delete((keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this folder has been removed from its parent.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `force` - a flag controlling whether resources that are not in sync with the local file system will be tolerated
    `keepHistory` - a flag controlling whether files under this folder should be stored in the workspace's local history
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource could not be deleted for some reason.
    - This resource is out of sync with the local file system and `force` is `false`.
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  See Also:
    `IResource.delete(int,IProgressMonitor)`, `IResourceRuleFactory.deleteRule(IResource)`

### getCharset

    String getCharset()
                      throws CoreException

  Returns the name of a charset to be used when decoding the contents of this file into characters.

  This refinement of the corresponding `IEncodedStorage` method is a convenience method, fully equivalent to:

         getCharset(true);

  Note 1: this method does not check whether the result is a supported charset name. Callers should be prepared to handle `UnsupportedEncodingException` where this charset is used.

  Note 2: this method returns a cached value for the encoding that may be out of date if the file is not synchronized with the local file system and the encoding has since changed in the file system.

  Specified by:
    `getCharset` in interface `IEncodedStorage`
  Returns:
    the name of a charset
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource could not be read.
    - This resource is not local.
    - The corresponding location in the local file system is occupied by a directory.
  Since:
    3.0
  See Also:
    `getCharset(boolean)`, `IEncodedStorage.getCharset()`, `IContainer.getDefaultCharset()`

### getCharset

    String getCharset(boolean checkImplicit)
                      throws CoreException

  Returns the name of a charset to be used when decoding the contents of this file into characters.

  If checkImplicit is `false`, this method will return the charset defined by calling `setCharset`, provided this file exists, or `null` otherwise.

  If checkImplicit is `true`, this method uses the following algorithm to determine the charset to be returned:

  1. the charset defined by calling #setCharset, if any, and this file exists, or
  2. the charset automatically discovered based on this file's contents, if one can be determined, or
  3. the default encoding for this file's parent (as defined by `IContainer#getDefaultCharset`).

  Note 1: this method does not check whether the result is a supported charset name. Callers should be prepared to handle `UnsupportedEncodingException` where this charset is used.

  Note 2: this method returns a cached value for the encoding that may be out of date if the file is not synchronized with the local file system and the encoding has since changed in the file system.

  Returns:
    the name of a charset, or `null`
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource could not be read.
    - This resource is not local.
    - The corresponding location in the local file system is occupied by a directory.
  Since:
    3.0
  See Also:
    `IEncodedStorage.getCharset()`, `IContainer.getDefaultCharset()`

### getCharsetFor

    String getCharsetFor(Reader reader)
                         throws CoreException

  Returns the name of a charset to be used to encode the given contents when saving to this file. This file does not have to exist. The character stream is not automatically closed.

  This method uses the following algorithm to determine the charset to be returned:

  1. if this file exists, the charset returned by IFile#getCharset(false), if one is defined, or
  2. the charset automatically discovered based on the file name and the given contents, if one can be determined, or
  3. the default encoding for the parent resource (as defined by `IContainer#getDefaultCharset`).

  Note: this method does not check whether the result is a supported charset name. Callers should be prepared to handle `UnsupportedEncodingException` where this charset is used.

  Parameters:
    `reader` - a character stream containing the contents to be saved into this file
  Returns:
    the name of a charset
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - The given character stream could not be read.
  Since:
    3.1
  See Also:
    `getCharset(boolean)`, `IContainer.getDefaultCharset()`

### getContentDescription

    IContentDescription getContentDescription()
                                              throws CoreException

  Returns a description for this file's current contents. Returns `null` if a description cannot be obtained.

  Calling this method produces a similar effect as calling `getDescriptionFor(getContents(), getName(), IContentDescription.ALL)` on `IContentTypeManager`, but provides better opportunities for improved performance. Therefore, when manipulating `IFile`s, clients should call this method instead of `IContentTypeManager.getDescriptionFor`.

  Returns:
    a description for this file's current contents, or `null`
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - This resource could not be read.
    - This resource is not local.
    - The workspace is not in sync with the corresponding location in the local file system and `ResourcesPlugin.PREF_LIGHTWEIGHT_AUTO_REFRESH` is disabled.
    - The corresponding location in the local file system is occupied by a directory.
  Since:
    3.0
  See Also:
    `IContentDescription`, `IContentTypeMatcher.getDescriptionFor(InputStream, String, QualifiedName[])`

### getContents

    InputStream getContents()
                            throws CoreException

  Returns an open input stream on the contents of this file.

  This refinement of the corresponding `IStorage` method is a convenience method returning an open input stream. It's equivalent to:

         getContents(RefreshManager#PREF_LIGHTWEIGHT_AUTO_REFRESH);

  If lightweight auto-refresh is not enabled this method will throw a CoreException when opening out-of-sync resources.

  The client is responsible for closing the stream when finished.

  Specified by:
    `getContents` in interface `IStorage`
  Returns:
    an input stream containing the contents of the file
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - This resource is not local.
    - The file-system resource is not a file.
    - The workspace is not in sync with the corresponding location in the local file system (and `ResourcesPlugin.PREF_LIGHTWEIGHT_AUTO_REFRESH` is disabled).

### getContents

    InputStream getContents(boolean force)
                            throws CoreException

  This refinement of the corresponding `IStorage` method returns an open input stream on the contents of this file. The client is responsible for closing the stream when finished. If force is `true` the file is opened and an input stream returned regardless of the sync state of the file. The file is not synchronized with the workspace. If force is `false` the method fails if not in sync.

  Parameters:
    `force` - a flag controlling how to deal with resources that are not in sync with the local file system
  Returns:
    an input stream containing the contents of the file
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - This resource is not local.
    - The workspace is not in sync with the corresponding location in the local file system and force is `false`.

### getEncoding

    int getEncoding()
                    throws CoreException

  Deprecated. use IFile#getCharset instead

  Returns a constant identifying the character encoding of this file, or ENCODING_UNKNOWN if it could not be determined. The returned constant will be one of the ENCODING_* constants defined on IFile. This method attempts to guess the file's character encoding by analyzing the first few bytes of the file. If no identifying pattern is found at the beginning of the file, ENC_UNKNOWN will be returned. This method will not attempt any complex analysis of the file to make a guess at the encoding that is used.

  Returns:
    The character encoding of this file
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - This resource could not be read.
    - This resource is not local.
    - The corresponding location in the local file system is occupied by a directory.

### getFullPath

    IPath getFullPath()

  Returns the full path of this file. This refinement of the corresponding `IStorage` and `IResource` methods links the semantics of resource and storage object paths such that `IFile`s always have a path and that path is relative to the containing workspace.

  Specified by:
    `getFullPath` in interface `IResource`
  Specified by:
    `getFullPath` in interface `IStorage`
  Returns:
    the absolute path of this resource
  See Also:
    `IResource.getFullPath()`, `IStorage.getFullPath()`

### getHistory

    IFileState[] getHistory(IProgressMonitor monitor)
                            throws CoreException

  Returns a list of past states of this file known to this workspace. Recently added states first.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Returns:
    an array of states of this file
  Throws:
    `CoreException` - if this method fails.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.

### getName

    String getName()

  Returns the name of this file. This refinement of the corresponding `IStorage` and `IResource` methods links the semantics of resource and storage object names such that `IFile`s always have a name and that name equivalent to the last segment of its full path.

  Specified by:
    `getName` in interface `IResource`
  Specified by:
    `getName` in interface `IStorage`
  Returns:
    the name of the resource
  See Also:
    `IResource.getName()`, `IStorage.getName()`

### isReadOnly

    boolean isReadOnly()

  Returns whether this file is read-only. This refinement of the corresponding `IStorage` and `IResource` methods links the semantics of read-only resources and read-only storage objects.

  Specified by:
    `isReadOnly` in interface `IResource`
  Specified by:
    `isReadOnly` in interface `IStorage`
  Returns:
    `true` if this resource is read-only, `false` otherwise
  See Also:
    `IResource.isReadOnly()`, `IStorage.isReadOnly()`

### move

    void move(IPath destination,
              boolean force,
              boolean keepHistory,
              IProgressMonitor monitor)
              throws CoreException

  Moves this resource to be at the given location.

  This is a convenience method, fully equivalent to:

         move(destination, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this file has been removed from its parent and a new file has been added to the parent of the destination.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `destination` - the destination path
    `force` - a flag controlling whether resources that are not in sync with the local file system will be tolerated
    `keepHistory` - a flag controlling whether files under this folder should be stored in the workspace's local history
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this resource could not be moved. Reasons include:
    - This resource does not exist.
    - This resource is not local.
    - The resource corresponding to the parent destination path does not exist.
    - The resource corresponding to the parent destination path is a closed project.
    - A resource at destination path does exist.
    - A resource of a different type exists at the destination path.
    - This resource is out of sync with the local file system and `force` is `false`.
    - The workspace and the local file system are out of sync at the destination resource or one of its descendents.
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  See Also:
    `IResource.move(IPath,int,IProgressMonitor)`, `IResourceRuleFactory.moveRule(IResource, IResource)`

### setCharset

    void setCharset(String newCharset)
                    throws CoreException

  Deprecated. Replaced by `setCharset(String, IProgressMonitor)` which is a workspace operation and reports changes in resource deltas.

  Sets the charset for this file. Passing a value of `null` will remove the charset setting for this resource.

  Parameters:
    `newCharset` - a charset name, or `null`
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - An error happened while persisting this setting.
  Since:
    3.0
  See Also:
    `getCharset()`

### setCharset

    void setCharset(String newCharset,
                    IProgressMonitor monitor)
                    throws CoreException

  Sets the charset for this file. Passing a value of `null` will remove the charset setting for this resource.

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this file's encoding has changed.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `newCharset` - a charset name, or `null`
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - An error happened while persisting this setting.
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
  Since:
    3.0
  See Also:
    `getCharset()`, `IResourceRuleFactory.charsetRule(IResource)`

### setContents

    void setContents(InputStream source,
                     boolean force,
                     boolean keepHistory,
                     IProgressMonitor monitor)
                     throws CoreException

  Sets the contents of this file to the bytes in the given input stream.

  This is a convenience method, fully equivalent to:

         setContents(source, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this file's contents have been changed.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `source` - an input stream containing the new contents of the file
    `force` - a flag controlling how to deal with resources that are not in sync with the local file system
    `keepHistory` - a flag indicating whether or not store the current contents in the local history
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - The corresponding location in the local file system is occupied by a directory.
    - The workspace is not in sync with the corresponding location in the local file system and `force` is `false`.
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    - The file modification validator disallowed the change.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  See Also:
    `setContents(java.io.InputStream,int,IProgressMonitor)`

### setContents

    void setContents(IFileState source,
                     boolean force,
                     boolean keepHistory,
                     IProgressMonitor monitor)
                     throws CoreException

  Sets the contents of this file to the bytes in the given file state.

  This is a convenience method, fully equivalent to:

         setContents(source, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this file's content have been changed.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `source` - a previous state of this resource
    `force` - a flag controlling how to deal with resources that are not in sync with the local file system
    `keepHistory` - a flag indicating whether or not store the current contents in the local history
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - The state does not exist.
    - The corresponding location in the local file system is occupied by a directory.
    - The workspace is not in sync with the corresponding location in the local file system and `force` is `false`.
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    - The file modification validator disallowed the change.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  See Also:
    `setContents(IFileState,int,IProgressMonitor)`

### setContents

    void setContents(InputStream source,
                     int updateFlags,
                     IProgressMonitor monitor)
                     throws CoreException

  Sets the contents of this file to the bytes in the given input stream. The stream will get closed whether this method succeeds or fails. If the stream is `null` then the content is set to be the empty sequence of bytes.

  The `FORCE` update flag controls how this method deals with cases where the workspace is not completely in sync with the local file system. If `FORCE` is not specified, the method will only attempt to overwrite a corresponding file in the local file system provided it is in sync with the workspace. This option ensures there is no unintended data loss; it is the recommended setting. However, if `FORCE` is specified, an attempt will be made to write a corresponding file in the local file system, overwriting any existing one if need be. In either case, if this method succeeds, the resource will be marked as being local (even if it wasn't before).

  The `KEEP_HISTORY` update flag controls whether or not a copy of current contents of this file should be captured in the workspace's local history (properties are not recorded in the local history). The local history mechanism serves as a safety net to help the user recover from mistakes that might otherwise result in data loss. Specifying `KEEP_HISTORY` is recommended except in circumstances where past states of the files are of no conceivable interest to the user. Note that local history is maintained with each individual project, and gets discarded when a project is deleted from the workspace. This flag is ignored if the file was not previously local.

  Update flags other than `FORCE` and `KEEP_HISTORY` are ignored.

  Prior to modifying the contents of this file, the file modification validator (if provided by the VCM plug-in), will be given a chance to perform any last minute preparations. Validation is performed by calling `IFileModificationValidator.validateSave` on this file. If the validation fails, then this operation will fail.

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this file's content have been changed.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `source` - an input stream containing the new contents of the file
    `updateFlags` - bit-wise or of update flag constants (`FORCE` and `KEEP_HISTORY`)
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - The corresponding location in the local file system is occupied by a directory.
    - The workspace is not in sync with the corresponding location in the local file system and `FORCE` is not specified.
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    - The file modification validator disallowed the change.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  Since:
    2.0
  See Also:
    `IResourceRuleFactory.modifyRule(IResource)`

### setContents

    void setContents(IFileState source,
                     int updateFlags,
                     IProgressMonitor monitor)
                     throws CoreException

  Sets the contents of this file to the bytes in the given file state.

  The `FORCE` update flag controls how this method deals with cases where the workspace is not completely in sync with the local file system. If `FORCE` is not specified, the method will only attempt to overwrite a corresponding file in the local file system provided it is in sync with the workspace. This option ensures there is no unintended data loss; it is the recommended setting. However, if `FORCE` is specified, an attempt will be made to write a corresponding file in the local file system, overwriting any existing one if need be. In either case, if this method succeeds, the resource will be marked as being local (even if it wasn't before).

  The `KEEP_HISTORY` update flag controls whether or not a copy of current contents of this file should be captured in the workspace's local history (properties are not recorded in the local history). The local history mechanism serves as a safety net to help the user recover from mistakes that might otherwise result in data loss. Specifying `KEEP_HISTORY` is recommended except in circumstances where past states of the files are of no conceivable interest to the user. Note that local history is maintained with each individual project, and gets discarded when a project is deleted from the workspace. This flag is ignored if the file was not previously local.

  Update flags other than `FORCE` and `KEEP_HISTORY` are ignored.

  Prior to modifying the contents of this file, the file modification validator (if provided by the VCM plug-in), will be given a chance to perform any last minute preparations. Validation is performed by calling `IFileModificationValidator.validateSave` on this file. If the validation fails, then this operation will fail.

  This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this file's content have been changed.

  This method is long-running; progress and cancellation are provided by the given progress monitor.

  Parameters:
    `source` - a previous state of this resource
    `updateFlags` - bit-wise or of update flag constants (`FORCE` and `KEEP_HISTORY`)
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `CoreException` - if this method fails. Reasons include:
    - This resource does not exist.
    - The state does not exist.
    - The corresponding location in the local file system is occupied by a directory.
    - The workspace is not in sync with the corresponding location in the local file system and `FORCE` is not specified.
    - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.
    - The file modification validator disallowed the change.
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  Since:
    2.0
  See Also:
    `IResourceRuleFactory.modifyRule(IResource)`

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.