Copyright (c) 2000, 2015 IBM Corporation and others.
 This program and the accompanying materials
 are made available under the terms of the Eclipse Public License 2.0
 which accompanies this distribution, and is available at
 https://www.eclipse.org/legal/epl-2.0/
 SPDX-License-Identifier: EPL-2.0
 Contributors:
    IBM Corporation - initial API and implementation
    James Blackburn (Broadcom Corp.) - ongoing development
    Sergey Prigogin (Google) - [462440] IFile#getContents methods should specify the status codes for its exceptions
/*******************************************************************************
 *  Copyright (c) 2000, 2015 IBM Corporation and others.
 *
 *  This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License 2.0
 *  which accompanies this distribution, and is available at
 *  https://www.eclipse.org/legal/epl-2.0/
 *
 *  SPDX-License-Identifier: EPL-2.0
 *
 *  Contributors:
 *     IBM Corporation - initial API and implementation
 *     James Blackburn (Broadcom Corp.) - ongoing development
 *     Sergey Prigogin (Google) - [462440] IFile#getContents methods should specify the status codes for its exceptions
 *******************************************************************************/
package org.eclipse.core.resources;

import java.io.InputStream;
import java.io.Reader;
import java.net.URI;
import org.eclipse.core.runtime.*;
import org.eclipse.core.runtime.content.IContentDescription;
import org.eclipse.core.runtime.content.IContentTypeManager;

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:
getAdapterManager.getAdapterManager()
@noimplement
This interface is not intended to be implemented by clients.
@noextend
This interface is not intended to be extended by clients./**
 * Files are leaf resources which contain data.
 * The contents of a file resource is stored as a file in the local
 * file system.
 * <p>
 * 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.
 * </p>
 * <p>
 * Files implement the <code>IAdaptable</code> interface;
 * extensions are managed by the platform's adapter manager.
 * </p>
 *
 * @see Platform#getAdapterManager()
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IFile extends IResource, IEncodedStorage, IAdaptable {
	
Character encoding constant (value 0) which identifies
files that have an unknown character encoding scheme.
See Also:
getEncoding.getEncoding()
Deprecated:
see getEncoding for details/**
	 * Character encoding constant (value 0) which identifies
	 * files that have an unknown character encoding scheme.
	 *
	 * @see IFile#getEncoding()
	 * @deprecated see getEncoding for details
	 */
	@Deprecated
	int ENCODING_UNKNOWN = 0;
	
Character encoding constant (value 1) which identifies
files that are encoded with the US-ASCII character encoding scheme.
See Also:
getEncoding.getEncoding()
Deprecated:
see getEncoding for details/**
	 * Character encoding constant (value 1) which identifies
	 * files that are encoded with the US-ASCII character encoding scheme.
	 *
	 * @see IFile#getEncoding()
	 * @deprecated see getEncoding for details
	 */
	@Deprecated
	int ENCODING_US_ASCII = 1;
	
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.getEncoding()
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 IFile#getEncoding()
	 * @deprecated see getEncoding for details
	 */
	@Deprecated
	int ENCODING_ISO_8859_1 = 2;
	
Character encoding constant (value 3) which identifies
files that are encoded with the UTF-8 character encoding scheme.
See Also:
getEncoding.getEncoding()
Deprecated:
see getEncoding for details/**
	 * Character encoding constant (value 3) which identifies
	 * files that are encoded with the UTF-8 character encoding scheme.
	 *
	 * @see IFile#getEncoding()
	 * @deprecated see getEncoding for details
	 */
	@Deprecated
	int ENCODING_UTF_8 = 3;
	
Character encoding constant (value 4) which identifies
files that are encoded with the UTF-16BE character encoding scheme.
See Also:
getEncoding.getEncoding()
Deprecated:
see getEncoding for details/**
	 * Character encoding constant (value 4) which identifies
	 * files that are encoded with the UTF-16BE character encoding scheme.
	 *
	 * @see IFile#getEncoding()
	 * @deprecated see getEncoding for details
	 */
	@Deprecated
	int ENCODING_UTF_16BE = 4;
	
Character encoding constant (value 5) which identifies
files that are encoded with the UTF-16LE character encoding scheme.
See Also:
getEncoding.getEncoding()
Deprecated:
see getEncoding for details/**
	 * Character encoding constant (value 5) which identifies
	 * files that are encoded with the UTF-16LE character encoding scheme.
	 *
	 * @see IFile#getEncoding()
	 * @deprecated see getEncoding for details
	 */
	@Deprecated
	int ENCODING_UTF_16LE = 5;
	
Character encoding constant (value 6) which identifies
files that are encoded with the UTF-16 character encoding scheme.
See Also:
getEncoding.getEncoding()
Deprecated:
see getEncoding for details/**
	 * Character encoding constant (value 6) which identifies
	 * files that are encoded with the UTF-16 character encoding scheme.
	 *
	 * @see IFile#getEncoding()
	 * @deprecated see getEncoding for details
	 */
	@Deprecated
	int ENCODING_UTF_16 = 6;

	
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.

Params:
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(InputStream, int, IProgressMonitor)/**
	 * Appends the entire contents of the given stream to this file.
	 * <p>
	 * This is a convenience method, fully equivalent to:
	 * </p>
	 * <pre>
	 *   appendContents(source, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);
	 * </pre>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancelation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param source an input stream containing the new contents of the file
	 * @param force a flag controlling how to deal with resources that
	 *    are not in sync with the local file system
	 * @param keepHistory a flag indicating whether or not to store
	 *    the current contents in the local history
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> The corresponding location in the local file system
	 *       is occupied by a directory.</li>
	 * <li> The workspace is not in sync with the corresponding location
	 *       in the local file system and <code>force </code> is <code>false</code>.</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
	 * <li> The file modification validator disallowed the change.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @see #appendContents(java.io.InputStream,int,IProgressMonitor)
	 */
	void appendContents(InputStream source, boolean force, boolean keepHistory, 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.

Params:
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.
See Also:
IResourceRuleFactory.modifyRule(IResource)
Since:
2.0/**
	 * Appends the entire contents of the given stream to this file.
	 * The stream, which must not be <code>null</code>, will get closed
	 * whether this method succeeds or fails.
	 * <p>
	 * The <code>FORCE</code> update flag controls how this method deals with
	 * cases where the workspace is not completely in sync with the local file
	 * system. If <code>FORCE</code> 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 <code>FORCE</code> 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).
	 * </p>
	 * <p>
	 * If this file is non-local then this method will always fail. The only exception
	 * is when <code>FORCE</code> 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.
	 * </p>
	 * <p>
	 * The <code>KEEP_HISTORY</code> 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 <code>KEEP_HISTORY</code>
	 * 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.
	 * </p>
	 * <p>
	 * Update flags other than <code>FORCE</code> and <code>KEEP_HISTORY</code>
	 * are ignored.
	 * </p>
	 * <p>
	 * 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 <code>IFileModificationValidator.validateSave</code> on this file.
	 * If the validation fails, then this operation will fail.
	 * </p>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancelation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param source an input stream containing the new contents of the file
	 * @param updateFlags bit-wise or of update flag constants
	 *   (<code>FORCE</code> and <code>KEEP_HISTORY</code>)
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> The corresponding location in the local file system
	 *       is occupied by a directory.</li>
	 * <li> The workspace is not in sync with the corresponding location
	 *       in the local file system and <code>FORCE</code> is not specified.</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
	 * <li> The file modification validator disallowed the change.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @see IResourceRuleFactory#modifyRule(IResource)
	 * @since 2.0
	 */
	void appendContents(InputStream source, int updateFlags, 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.

Params:
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./**
	 * Creates a new file resource as a member of this handle's parent resource.
	 * <p>
	 * This is a convenience method, fully equivalent to:
	 * </p>
	 * <pre>
	 *   create(source, (force ? FORCE : IResource.NONE), monitor);
	 * </pre>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param source an input stream containing the initial contents of the file,
	 *    or <code>null</code> if the file should be marked as not local
	 * @param force a flag controlling how to deal with resources that
	 *    are not in sync with the local file system
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource already exists in the workspace.</li>
	 * <li> The parent of this resource does not exist.</li>
	 * <li> The parent of this resource is a virtual folder.</li>
	 * <li> The project of this resource is not accessible.</li>
	 * <li> The parent contains a resource of a different type
	 *      at the same path as this resource.</li>
	 * <li> The name of this resource is not valid (according to
	 *    <code>IWorkspace.validateName</code>).</li>
	 * <li> The corresponding location in the local file system is occupied
	 *    by a directory.</li>
	 * <li> The corresponding location in the local file system is occupied
	 *    by a file and <code>force </code> is <code>false</code>.</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 */
	void create(InputStream source, boolean force, 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.

Params:
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.
See Also:
IResourceRuleFactory.createRule(IResource)
Since:
2.0/**
	 * 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 <code>null</code> then a file is not created in the local
	 * file system and the created file resource is marked as being non-local.
	 * <p>
	 * The {@link 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 {@link 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 {@link 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.
	 * </p>
	 * <p>
	 * The {@link IResource#DERIVED} update flag indicates that this resource
	 * should immediately be set as a derived resource.  Specifying this flag
	 * is equivalent to atomically calling {@link IResource#setDerived(boolean)}
	 * with a value of <code>true</code> immediately after creating the resource.
	 * </p>
	 * <p>
	 * The {@link 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 {@link IResource#setTeamPrivateMember(boolean)}
	 * with a value of <code>true</code> immediately after creating the resource.
	 * </p>
	 * <p>
	 * The {@link IResource#HIDDEN} update flag indicates that this resource
	 * should immediately be set as a hidden resource.  Specifying this flag
	 * is equivalent to atomically calling {@link IResource#setHidden(boolean)}
	 * with a value of <code>true</code> immediately after creating the resource.
	 * </p>
	 * <p>
	 * Update flags other than those listed above are ignored.
	 * </p>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param source an input stream containing the initial contents of the file,
	 *    or <code>null</code> if the file should be marked as not local
	 * @param updateFlags bit-wise or of update flag constants
	 *   ({@link IResource#FORCE}, {@link IResource#DERIVED}, and {@link IResource#TEAM_PRIVATE})
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource already exists in the workspace.</li>
	 * <li> The parent of this resource does not exist.</li>
	 * <li> The parent of this resource is a virtual folder.</li>
	 * <li> The project of this resource is not accessible.</li>
	 * <li> The parent contains a resource of a different type
	 *      at the same path as this resource.</li>
	 * <li> The name of this resource is not valid (according to
	 *    <code>IWorkspace.validateName</code>).</li>
	 * <li> The corresponding location in the local file system is occupied
	 *    by a directory.</li>
	 * <li> The corresponding location in the local file system is occupied
	 *    by a file and <code>FORCE</code> is not specified.</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @see IResourceRuleFactory#createRule(IResource)
	 * @since 2.0
	 */
	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 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.

Params:
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.
See Also:
IResource.isLinked()
IResource.ALLOW_MISSING_LOCAL
IResource.REPLACE
IResource.HIDDEN
Since:
2.1/**
	 * 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.
	 * <p>
	 * The {@link 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 {@link 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 {@link 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.
	 * </p>
	 * <p>
	 * The {@link 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 {@link IResource#REPLACE}
	 * is specified, then the existing linked resource's location is replaced
	 * by localLocation's value.  This does <b>not</b>
	 * cause the underlying file system contents of that resource to be deleted.
	 * If {@link IResource#REPLACE} is not specified, this method will
	 * fail if an existing resource exists of the same name.
	 * </p>
	 * <p>
	 * The {@link IResource#HIDDEN} update flag indicates that this resource
	 * should immediately be set as a hidden resource.  Specifying this flag
	 * is equivalent to atomically calling {@link IResource#setHidden(boolean)}
	 * with a value of <code>true</code> immediately after creating the resource.
	 * </p>
	 * <p>
	 * Update flags other than those listed above are ignored.
	 * </p>
	 * <p>
	 * This method synchronizes this resource with the local file system at the given
	 * location.
	 * </p>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param localLocation a file system path where the file should be linked
	 * @param updateFlags bit-wise or of update flag constants
	 *   ({@link IResource#ALLOW_MISSING_LOCAL}, {@link IResource#REPLACE} and {@link IResource#HIDDEN})
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource already exists in the workspace.</li>
	 * <li> The workspace contains a resource of a different type
	 *      at the same path as this resource.</li>
	 * <li> The parent of this resource does not exist.</li>
	 * <li> The parent of this resource is not an open project</li>
	 * <li> The name of this resource is not valid (according to
	 *    <code>IWorkspace.validateName</code>).</li>
	 * <li> The corresponding location in the local file system does not exist, or
	 * is relative to an undefined variable, and <code>ALLOW_MISSING_LOCAL</code> is
	 * not specified.</li>
	 * <li> The corresponding location in the local file system is occupied
	 *    by a directory (as opposed to a file).</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification.  See <code>IResourceChangeEvent</code> for more details.</li>
	 * <li>The team provider for the project which contains this folder does not permit
	 *       linked resources.</li>
	 * <li>This folder's project contains a nature which does not permit linked resources.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @see IResource#isLinked()
	 * @see IResource#ALLOW_MISSING_LOCAL
	 * @see IResource#REPLACE
	 * @see IResource#HIDDEN
	 * @since 2.1
	 */
	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
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.

Params:
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.
See Also:
IResource.isLinked()
IResource.ALLOW_MISSING_LOCAL
IResource.REPLACE
IResource.HIDDEN
Since:
3.2/**
	 * 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.
	 * <p>
	 * The <code>ALLOW_MISSING_LOCAL</code> 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 <code>ALLOW_MISSING_LOCAL</code> is specified, the operation will succeed
	 * even if the local file is missing, or the path is relative to an undefined
	 * variable. If <code>ALLOW_MISSING_LOCAL</code> 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.
	 * </p>
	 * <p>
	 * The {@link 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 {@link 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 <b>not</b>
	 * cause the underlying file system contents of that resource to be deleted.
	 * If {@link IResource#REPLACE} is not specified, this method will
	 * fail if an existing resource exists of the same name.
	 * </p>
	 * <p>
	 * The {@link IResource#HIDDEN} update flag indicates that this resource
	 * should immediately be set as a hidden resource.  Specifying this flag
	 * is equivalent to atomically calling {@link IResource#setHidden(boolean)}
	 * with a value of <code>true</code> immediately after creating the resource.
	 * </p>
	 * <p>
	 * Update flags other than those listed above are ignored.
	 * </p>
	 * <p>
	 * This method synchronizes this resource with the file system at the given
	 * location.
	 * </p>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param location a file system URI where the file should be linked
	 * @param updateFlags bit-wise or of update flag constants
	 *   ({@link IResource#ALLOW_MISSING_LOCAL}, {@link IResource#REPLACE} and {@link IResource#HIDDEN})
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource already exists in the workspace.</li>
	 * <li> The workspace contains a resource of a different type
	 *      at the same path as this resource.</li>
	 * <li> The parent of this resource does not exist.</li>
	 * <li> The parent of this resource is not an open project</li>
	 * <li> The name of this resource is not valid (according to
	 *    <code>IWorkspace.validateName</code>).</li>
	 * <li> The corresponding location in the file system does not exist, or
	 * is relative to an undefined variable, and <code>ALLOW_MISSING_LOCAL</code> is
	 * not specified.</li>
	 * <li> The corresponding location in the file system is occupied
	 *    by a directory (as opposed to a file).</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification.  See <code>IResourceChangeEvent</code> for more details.</li>
	 * <li>The team provider for the project which contains this folder does not permit
	 *       linked resources.</li>
	 * <li>This folder's project contains a nature which does not permit linked resources.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @see IResource#isLinked()
	 * @see IResource#ALLOW_MISSING_LOCAL
	 * @see IResource#REPLACE
	 * @see IResource#HIDDEN
	 * @since 3.2
	 */
	void createLink(URI location, int updateFlags, 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.

Params:
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)/**
	 * Deletes this file from the workspace.
	 * <p>
	 * This is a convenience method, fully equivalent to:
	 * </p>
	 * <pre>
	 *   delete((keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);
	 * </pre>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param force a flag controlling whether resources that are not
	 *    in sync with the local file system will be tolerated
	 * @param keepHistory a flag controlling whether files under this folder
	 *    should be stored in the workspace's local history
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource could not be deleted for some reason.</li>
	 * <li> This resource is out of sync with the local file system
	 *      and <code>force</code> is <code>false</code>.</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @see IResource#delete(int,IProgressMonitor)
	 * @see IResourceRuleFactory#deleteRule(IResource)
	 */
	void delete(boolean force, boolean keepHistory, IProgressMonitor monitor) 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.

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.
See Also:
getCharset(boolean)
IEncodedStorage.getCharset()
IContainer.getDefaultCharset()
Returns:
the name of a charset
Since:
3.0/**
	 * Returns the name of a charset to be used when decoding the contents of this
	 * file into characters.
	 * <p>
	 * This refinement of the corresponding {@link IEncodedStorage} method
	 * is a convenience method, fully equivalent to:</p>
	 * <pre>
	 *   getCharset(true);
	 * </pre>
	 * <p>
	 * <b>Note 1</b>:  this method does not check whether the result is a supported
	 * charset name. Callers should be prepared to handle
	 * <code>UnsupportedEncodingException</code> where this charset is used.
	 * </p>
	 * <p>
	 * <b>Note 2</b>: 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.
	 * </p>
	 *
	 * @return the name of a charset
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource could not be read.</li>
	 * <li> This resource is not local.</li>
	 * <li> The corresponding location in the local file system
	 *       is occupied by a directory.</li>
	 * </ul>
	 * @see IFile#getCharset(boolean)
	 * @see IEncodedStorage#getCharset()
	 * @see IContainer#getDefaultCharset()
	 * @since 3.0
	 */
	@Override
	String getCharset() 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:

the charset defined by calling #setCharset, if any, and this file
exists, or
the charset automatically discovered based on this file's contents,
if one can be determined, or
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.

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.
See Also:
IEncodedStorage.getCharset()
IContainer.getDefaultCharset()
Returns:
the name of a charset, or null
Since:
3.0/**
	 * Returns the name of a charset to be used when decoding the contents of this
	 * file into characters.
	 * <p>
	 * If checkImplicit is <code>false</code>, this method will return the
	 * charset defined by calling <code>setCharset</code>, provided this file
	 * exists, or <code>null</code> otherwise.
	 * </p><p>
	 * If checkImplicit is <code>true</code>, this method uses the following
	 * algorithm to determine the charset to be returned:</p>
	 * <ol>
	 * <li>the charset defined by calling #setCharset, if any, and this file
	 * exists, or</li>
	 * <li>the charset automatically discovered based on this file's contents,
	 * if one can be determined, or</li>
	 * <li>the default encoding for this file's parent (as defined by
	 * <code>IContainer#getDefaultCharset</code>).</li>
	 * </ol>
	 * <p>
	 * <b>Note 1</b>:  this method does not check whether the result is a supported
	 * charset name. Callers should be prepared to handle
	 * <code>UnsupportedEncodingException</code> where this charset is used.
	 * </p>
	 * <p>
	 * <b>Note 2</b>: 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.
	 * </p>
	 *
	 * @return the name of a charset, or <code>null</code>
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource could not be read.</li>
	 * <li> This resource is not local.</li>
	 * <li> The corresponding location in the local file system
	 *       is occupied by a directory.</li>
	 * </ul>
	 * @see IEncodedStorage#getCharset()
	 * @see IContainer#getDefaultCharset()
	 * @since 3.0
	 */
	String getCharset(boolean checkImplicit) 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:

if this file exists, the charset returned by IFile#getCharset(false), if one is defined, or
the charset automatically discovered based on the file name and the given contents,
if one can be determined, or
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.

Params:
reader – a character stream containing the contents to be saved into this file
Throws:
CoreException – if this method fails. Reasons include:

The given character stream could not be read.
See Also:
getCharset(boolean)
IContainer.getDefaultCharset()
Returns:
the name of a charset
Since:
3.1/**
	 * 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 <em>not</em> automatically closed.
	 * <p>
	 * This method uses the following algorithm to determine the charset to be returned:</p>
	 * <ol>
	 * <li>if this file exists, the charset returned by IFile#getCharset(false), if one is defined, or</li>
	 * <li>the charset automatically discovered based on the file name and the given contents,
	 * if one can be determined, or</li>
	 * <li>the default encoding for the parent resource (as defined by
	 * <code>IContainer#getDefaultCharset</code>).</li>
	 * </ol>
	 * <p>
	 * <b>Note</b>:  this method does not check whether the result is a supported
	 * charset name. Callers should be prepared to handle
	 * <code>UnsupportedEncodingException</code> where this charset is used.
	 * </p>
	 *
	 * @param reader a character stream containing the contents to be saved into this file
	 * @return the name of a charset
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li>The given character stream could not be read.</li>
	 * </ul>
	 * @see #getCharset(boolean)
	 * @see IContainer#getDefaultCharset()
	 * @since 3.1
	 */
	String getCharsetFor(Reader reader) 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
IFiles, clients should call this method instead of
IContentTypeManager.getDescriptionFor.

Throws:
CoreException – if this method fails. The status code associated with exception
    reflects the cause of the failure. Reasons include:

 IResourceStatus.RESOURCE_NOT_FOUND - This file does not exist. Please notice that a successful IResource.exists() check prior to calling getContentDescription() does not guarantee the file existence since the file may be deleted outside Eclipse at the very last moment.
 IResourceStatus.RESOURCE_NOT_LOCAL - This resource is not local.
 IResourceStatus.OUT_OF_SYNC_LOCAL - The workspace is not in sync with the corresponding location in the local file system (and ResourcesPlugin.PREF_LIGHTWEIGHT_AUTO_REFRESH is disabled).
 IResourceStatus.FAILED_DESCRIBING_CONTENTS - An I/O error occurred while reading the file.
See Also:
IContentDescription
IContentTypeMatcher.getDescriptionFor(InputStream, String, QualifiedName[])
Returns:
a description for this file's current contents, or
null
Since:
3.0/**
	 * Returns a description for this file's current contents. Returns
	 * <code>null</code> if a description cannot be obtained.
	 * <p>
	 * Calling this method produces a similar effect as calling
	 * <code>getDescriptionFor(getContents(), getName(), IContentDescription.ALL)</code>
	 * on <code>IContentTypeManager</code>, but provides better
	 * opportunities for improved performance. Therefore, when manipulating
	 * <code>IFile</code>s, clients should call this method instead of
	 * <code>IContentTypeManager.getDescriptionFor</code>.
	 * </p>
	 *
	 * @return a description for this file's current contents, or
	 * <code>null</code>
	 * @exception CoreException if this method fails. The status code associated with exception
	 *     reflects the cause of the failure. Reasons include:
	 * <ul>
	 * <li> {@link IResourceStatus#RESOURCE_NOT_FOUND} - This file does not exist.
	 *       Please notice that a successful {@link #exists()} check prior to calling
	 *       {@link #getContentDescription()} does not guarantee the file existence since the file
	 *       may be deleted outside Eclipse at the very last moment.</li>
	 * <li> {@link IResourceStatus#RESOURCE_NOT_LOCAL} - This resource is not local.</li>
	 * <li> {@link IResourceStatus#OUT_OF_SYNC_LOCAL} - The workspace is not in sync with
	 * 		 the corresponding location in the local file system (and
	 *       {@link ResourcesPlugin#PREF_LIGHTWEIGHT_AUTO_REFRESH} is disabled).</li>
	 * <li> {@link IResourceStatus#FAILED_DESCRIBING_CONTENTS} - An I/O error occurred while
	 *       reading the file.</li>
	 * </ul>
	 * @see IContentDescription
	 * @see IContentTypeManager#getDescriptionFor(InputStream, String, QualifiedName[])
	 * @since 3.0
	 */
	IContentDescription getContentDescription() 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.
Throws:
CoreException – if this method fails. The status code associated with exception
    reflects the cause of the failure. Reasons include:

 IResourceStatus.RESOURCE_NOT_FOUND - This file does not exist. Please notice that a successful IResource.exists() check prior to calling getContents() does not guarantee the file existence since the file may be deleted outside Eclipse at the very last moment.
 IResourceStatus.RESOURCE_NOT_LOCAL - This resource is not local.
 IResourceStatus.RESOURCE_WRONG_TYPE - The file-system resource is not a file.
 IResourceStatus.OUT_OF_SYNC_LOCAL - The workspace is not in sync with the corresponding location in the local file system (and ResourcesPlugin.PREF_LIGHTWEIGHT_AUTO_REFRESH is disabled).
Returns:
an input stream containing the contents of the file/**
	 * Returns an open input stream on the contents of this file.
	 * <p>
	 * This refinement of the corresponding {@link IStorage} method
	 * is a convenience method returning an open input stream.  It's equivalent to:
	 * </p>
	 * <pre>
	 *   getContents(RefreshManager#PREF_LIGHTWEIGHT_AUTO_REFRESH);
	 * </pre>
	 * <p>
	 * If lightweight auto-refresh is not enabled this method will throw a CoreException
	 * when opening out-of-sync resources.
	 * </p>
	 * The client is responsible for closing the stream when finished.
	 *
	 * @return an input stream containing the contents of the file
	 * @exception CoreException if this method fails. The status code associated with exception
	 *     reflects the cause of the failure. Reasons include:
	 * <ul>
	 * <li> {@link IResourceStatus#RESOURCE_NOT_FOUND} - This file does not exist.
	 *       Please notice that a successful {@link #exists()} check prior to calling
	 *       {@link #getContents()} does not guarantee the file existence since the file may be
	 *       deleted outside Eclipse at the very last moment.</li>
	 * <li> {@link IResourceStatus#RESOURCE_NOT_LOCAL} - This resource is not local.</li>
	 * <li> {@link IResourceStatus#RESOURCE_WRONG_TYPE} - The file-system resource is not
	 *       a file.</li>
	 * <li> {@link IResourceStatus#OUT_OF_SYNC_LOCAL} - The workspace is not in sync with
	 * 		 the corresponding location in the local file system (and
	 *       {@link ResourcesPlugin#PREF_LIGHTWEIGHT_AUTO_REFRESH} is disabled).</li>
	 * </ul>
	 */
	@Override
	InputStream getContents() 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.
Params:
force – a flag controlling how to deal with resources that
   are not in sync with the local file system
Throws:
CoreException – if this method fails. The status code associated with exception
    reflects the cause of the failure. Reasons include:

 IResourceStatus.RESOURCE_NOT_FOUND - This file does not exist. Please notice that a successful IResource.exists() check prior to calling getContents() does not guarantee the file existence since the file may be deleted outside Eclipse at the very last moment.
 IResourceStatus.RESOURCE_NOT_LOCAL - This resource is not local.
 IResourceStatus.RESOURCE_WRONG_TYPE - The file-system resource is not a file.
 IResourceStatus.OUT_OF_SYNC_LOCAL - The workspace is not in sync with the corresponding location in the local file system (and ResourcesPlugin.PREF_LIGHTWEIGHT_AUTO_REFRESH is disabled).
Returns:
an input stream containing the contents of the file/**
	 * This refinement of the corresponding <code>IStorage</code> 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 <code>true</code> 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 <code>false</code> the method fails if not in sync.
	 *
	 * @param force a flag controlling how to deal with resources that
	 *    are not in sync with the local file system
	 * @return an input stream containing the contents of the file
	 * @exception CoreException if this method fails. The status code associated with exception
	 *     reflects the cause of the failure. Reasons include:
	 * <ul>
	 * <li> {@link IResourceStatus#RESOURCE_NOT_FOUND} - This file does not exist.
	 *       Please notice that a successful {@link #exists()} check prior to calling
	 *       {@link #getContents()} does not guarantee the file existence since the file may be
	 *       deleted outside Eclipse at the very last moment.</li>
	 * <li> {@link IResourceStatus#RESOURCE_NOT_LOCAL} - This resource is not local.</li>
	 * <li> {@link IResourceStatus#RESOURCE_WRONG_TYPE} - The file-system resource is not
	 *       a file.</li>
	 * <li> {@link IResourceStatus#OUT_OF_SYNC_LOCAL} - The workspace is not in sync with
	 * 		 the corresponding location in the local file system (and
	 *       {@link ResourcesPlugin#PREF_LIGHTWEIGHT_AUTO_REFRESH} is disabled).</li>
	 * </ul>
	 */
	InputStream getContents(boolean force) throws CoreException;

	
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.
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.
Returns:
The character encoding of this file
Deprecated:
use 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.
	 *
	 * @return The character encoding of this file
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> This resource could not be read.</li>
	 * <li> This resource is not local.</li>
	 * <li> The corresponding location in the local file system
	 *       is occupied by a directory.</li>
	 * </ul>
	 * @deprecated use {@link #getCharset} instead
	 */
	@Deprecated
	int getEncoding() throws CoreException;

	
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
IFiles always have a path and that path is relative to the
containing workspace.
See Also:
getFullPath.getFullPath()
IStorage.getFullPath()/**
	 * Returns the full path of this file.
	 * This refinement of the corresponding <code>IStorage</code> and <code>IResource</code>
	 * methods links the semantics of resource and storage object paths such that
	 * <code>IFile</code>s always have a path and that path is relative to the
	 * containing workspace.
	 *
	 * @see IResource#getFullPath()
	 * @see IStorage#getFullPath()
	 */
	@Override
	IPath getFullPath();

	
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.

Params:
monitor – a progress monitor, or null if progress
   reporting is not desired
Throws:
CoreException – if this method fails.
OperationCanceledException – if the operation is canceled.
Cancelation can occur even if no progress monitor is provided.
Returns:
an array of states of this file/**
	 * Returns a list of past states of this file known to this workspace.
	 * Recently added states first.
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @return an array of states of this file
	 * @exception CoreException if this method fails.
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 */
	IFileState[] getHistory(IProgressMonitor monitor) throws CoreException;

	
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
IFiles always have a name and that name equivalent to the
last segment of its full path.
See Also:
getName.getName()
IStorage.getName()/**
	 * Returns the name of this file.
	 * This refinement of the corresponding <code>IStorage</code> and <code>IResource</code>
	 * methods links the semantics of resource and storage object names such that
	 * <code>IFile</code>s always have a name and that name equivalent to the
	 * last segment of its full path.
	 *
	 * @see IResource#getName()
	 * @see IStorage#getName()
	 */
	@Override
	String getName();

	
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.
See Also:
isReadOnly.isReadOnly()
IStorage.isReadOnly()/**
	 * Returns whether this file is read-only.
	 * This refinement of the corresponding <code>IStorage</code> and <code>IResource</code>
	 * methods links the semantics of read-only resources and read-only storage objects.
	 *
	 * @see IResource#isReadOnly()
	 * @see IStorage#isReadOnly()
	 */
	@SuppressWarnings("deprecation")
	@Override
	boolean isReadOnly();

	
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.

Params:
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)/**
	 * Moves this resource to be at the given location.
	 * <p>
	 * This is a convenience method, fully equivalent to:
	 * </p>
	 * <pre>
	 *   move(destination, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);
	 * </pre>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param destination the destination path
	 * @param force a flag controlling whether resources that are not
	 *    in sync with the local file system will be tolerated
	 * @param keepHistory a flag controlling whether files under this folder
	 *    should be stored in the workspace's local history
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this resource could not be moved. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> This resource is not local.</li>
	 * <li> The resource corresponding to the parent destination path does not exist.</li>
	 * <li> The resource corresponding to the parent destination path is a closed
	 *      project.</li>
	 * <li> A resource at destination path does exist.</li>
	 * <li> A resource of a different type exists at the destination path.</li>
	 * <li> This resource is out of sync with the local file system
	 *      and <code>force</code> is <code>false</code>.</li>
	 * <li> The workspace and the local file system are out of sync
	 *      at the destination resource or one of its descendents.</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 *
	 * @see IResource#move(IPath,int,IProgressMonitor)
	 * @see IResourceRuleFactory#moveRule(IResource, IResource)
	 */
	void move(IPath destination, boolean force, boolean keepHistory, IProgressMonitor monitor) throws CoreException;

	
Sets the charset for this file. Passing a value of null
will remove the charset setting for this resource.
Params:
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.
See Also:
getCharset()
Since:
3.0
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 <code>null</code>
	 * will remove the charset setting for this resource.
	 *
	 * @param newCharset a charset name, or <code>null</code>
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> An error happened while persisting this setting.</li>
	 * </ul>
	 * @see #getCharset()
	 * @since 3.0
	 * @deprecated Replaced by {@link #setCharset(String, IProgressMonitor)} which
	 * 	is a workspace operation and reports changes in resource deltas.
	 */
	@Deprecated
	void setCharset(String newCharset) 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.

Params:
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.
See Also:
getCharset()
IResourceRuleFactory.charsetRule(IResource)
Since:
3.0/**
	 * Sets the charset for this file. Passing a value of <code>null</code>
	 * will remove the charset setting for this resource.
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param newCharset a charset name, or <code>null</code>
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> An error happened while persisting this setting.</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See {@link IResourceChangeEvent} for more details.</li>
	 * </ul>
	 * @see #getCharset()
	 * @see IResourceRuleFactory#charsetRule(IResource)
	 * @since 3.0
	 */
	void setCharset(String newCharset, 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.

Params:
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(InputStream, int, IProgressMonitor)/**
	 * Sets the contents of this file to the bytes in the given input stream.
	 * <p>
	 * This is a convenience method, fully equivalent to:
	 * </p>
	 * <pre>
	 *   setContents(source, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);
	 * </pre>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param source an input stream containing the new contents of the file
	 * @param force a flag controlling how to deal with resources that
	 *    are not in sync with the local file system
	 * @param keepHistory a flag indicating whether or not store
	 *    the current contents in the local history
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> The corresponding location in the local file system
	 *       is occupied by a directory.</li>
	 * <li> The workspace is not in sync with the corresponding location
	 *       in the local file system and <code>force </code> is <code>false</code>.</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
	 * <li> The file modification validator disallowed the change.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @see #setContents(java.io.InputStream,int,IProgressMonitor)
	 */
	void setContents(InputStream 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.

Params:
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)/**
	 * Sets the contents of this file to the bytes in the given file state.
	 * <p>
	 * This is a convenience method, fully equivalent to:
	 * </p>
	 * <pre>
	 *   setContents(source, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);
	 * </pre>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param source a previous state of this resource
	 * @param force a flag controlling how to deal with resources that
	 *    are not in sync with the local file system
	 * @param keepHistory a flag indicating whether or not store
	 *    the current contents in the local history
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> The state does not exist.</li>
	 * <li> The corresponding location in the local file system
	 *       is occupied by a directory.</li>
	 * <li> The workspace is not in sync with the corresponding location
	 *       in the local file system and <code>force </code> is <code>false</code>.</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
	 * <li> The file modification validator disallowed the change.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @see #setContents(IFileState,int,IProgressMonitor)
	 */
	void setContents(IFileState source, boolean force, boolean keepHistory, 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.

Params:
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.
See Also:
IResourceRuleFactory.modifyRule(IResource)
Since:
2.0/**
	 * 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 <code>null</code> then the content is set to be the
	 * empty sequence of bytes.
	 * <p>
	 * The <code>FORCE</code> update flag controls how this method deals with
	 * cases where the workspace is not completely in sync with the local file
	 * system. If <code>FORCE</code> 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 <code>FORCE</code> 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).
	 * </p>
	 * <p>
	 * The <code>KEEP_HISTORY</code> 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 <code>KEEP_HISTORY</code>
	 * 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.
	 * </p>
	 * <p>
	 * Update flags other than <code>FORCE</code> and <code>KEEP_HISTORY</code>
	 * are ignored.
	 * </p>
	 * <p>
	 * 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 <code>IFileModificationValidator.validateSave</code> on this file.
	 * If the validation fails, then this operation will fail.
	 * </p>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param source an input stream containing the new contents of the file
	 * @param updateFlags bit-wise or of update flag constants
	 *   (<code>FORCE</code> and <code>KEEP_HISTORY</code>)
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> The corresponding location in the local file system
	 *       is occupied by a directory.</li>
	 * <li> The workspace is not in sync with the corresponding location
	 *       in the local file system and <code>FORCE</code> is not specified.</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
	 * <li> The file modification validator disallowed the change.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @see IResourceRuleFactory#modifyRule(IResource)
	 * @since 2.0
	 */
	void setContents(InputStream 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.

Params:
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.
See Also:
IResourceRuleFactory.modifyRule(IResource)
Since:
2.0/**
	 * Sets the contents of this file to the bytes in the given file state.
	 * <p>
	 * The <code>FORCE</code> update flag controls how this method deals with
	 * cases where the workspace is not completely in sync with the local file
	 * system. If <code>FORCE</code> 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 <code>FORCE</code> 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).
	 * </p>
	 * <p>
	 * The <code>KEEP_HISTORY</code> 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 <code>KEEP_HISTORY</code>
	 * 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.
	 * </p>
	 * <p>
	 * Update flags other than <code>FORCE</code> and <code>KEEP_HISTORY</code>
	 * are ignored.
	 * </p>
	 * <p>
	 * 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 <code>IFileModificationValidator.validateSave</code> on this file.
	 * If the validation fails, then this operation will fail.
	 * </p>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param source a previous state of this resource
	 * @param updateFlags bit-wise or of update flag constants
	 *   (<code>FORCE</code> and <code>KEEP_HISTORY</code>)
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> The state does not exist.</li>
	 * <li> The corresponding location in the local file system
	 *       is occupied by a directory.</li>
	 * <li> The workspace is not in sync with the corresponding location
	 *       in the local file system and <code>FORCE</code> is not specified.</li>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
	 * <li> The file modification validator disallowed the change.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @see IResourceRuleFactory#modifyRule(IResource)
	 * @since 2.0
	 */
	void setContents(IFileState source, int updateFlags, IProgressMonitor monitor) throws CoreException;
}