Copyright (c) 2000, 2009 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
/*******************************************************************************
 * Copyright (c) 2000, 2009 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
 *******************************************************************************/
package org.eclipse.core.filebuffers;


import org.eclipse.core.filesystem.IFileStore;
import org.eclipse.core.internal.filebuffers.FileBuffersPlugin;

import org.eclipse.core.runtime.IPath;

import org.eclipse.jface.text.IDocument;
import org.eclipse.jface.text.source.IAnnotationModel;


A text file buffer manager manages text file buffers for files whose contents
is considered text.

Clients are not supposed to implement that interface.

Since:
3.0
@noimplement
This interface is not intended to be implemented by clients.
@noextend
This interface is not intended to be extended by clients./**
 * A text file buffer manager manages text file buffers for files whose contents
 * is considered text.
 * <p>
 * Clients are not supposed to implement that interface.
 * </p>
 *
 * @since 3.0
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface ITextFileBufferManager extends IFileBufferManager {

	
The default text file buffer manager.
Since:
3.3/**
	 * The default text file buffer manager.
	 * @since 3.3
	 */
	ITextFileBufferManager DEFAULT= FileBuffersPlugin.getDefault().getFileBufferManager();

	
Returns the text file buffer managed for the file at the given location
or null if either there is no such text file buffer.

The provided location is either a full path of a workspace resource or
an absolute path in the local file system. The file buffer manager does
not resolve the location of workspace resources in the case of linked
resources.

Params:
location – the location
Returns:
the text file buffer managed for that location or null
Deprecated:
As of 3.3, replaced by getTextFileBuffer(IPath, LocationKind)/**
	 * Returns the text file buffer managed for the file at the given location
	 * or <code>null</code> if either there is no such text file buffer.
	 * <p>
	 * The provided location is either a full path of a workspace resource or
	 * an absolute path in the local file system. The file buffer manager does
	 * not resolve the location of workspace resources in the case of linked
	 * resources.
	 * </p>
	 *
	 * @param location the location
	 * @return the text file buffer managed for that location or <code>null</code>
	 * @deprecated As of 3.3, replaced by {@link #getTextFileBuffer(IPath, LocationKind)}
	 */
	@Deprecated
	ITextFileBuffer getTextFileBuffer(IPath location);

	
Returns the text file buffer managed for the file at the given location
or null if there is no such text file buffer.

The type of the provided location is specified by the given
locationKind.

Params:
location – the location
locationKind – the kind of the given location
See Also:
LocationKind
Returns:
the text file buffer managed for that location or null
Since:
3.3/**
	 * Returns the text file buffer managed for the file at the given location
	 * or <code>null</code> if there is no such text file buffer.
	 * <p>
	 * The type of the provided location is specified by the given
	 * <code>locationKind</code>.
	 * </p>
	 *
	 * @param location the location
	 * @param locationKind the kind of the given location
	 * @return the text file buffer managed for that location or <code>null</code>
	 * @see LocationKind
	 * @since 3.3
	 */
	ITextFileBuffer getTextFileBuffer(IPath location, LocationKind locationKind);

	
Returns the text file buffer managed for the given file store
or null if there is no such text file buffer.

Note: This API must not be used if the given file
store maps to a resource contained in the workspace. A file buffer
that has been connected using a path will not be found. The encoding
of the file in the workspace will not be considered.


We had to use a different name than getTextFileBuffer for this method
due to https://bugs.eclipse.org/bugs/show_bug.cgi?id=148844

Params:
fileStore – the file store
Returns:
the text file buffer managed for that file store or null
Since:
3.3/**
	 * Returns the text file buffer managed for the given file store
	 * or <code>null</code> if there is no such text file buffer.
	 * <p>
	 * <strong>Note:</strong> This API must not be used if the given file
	 * store maps to a resource contained in the workspace. A file buffer
	 * that has been connected using a path will not be found. The encoding
	 * of the file in the workspace will not be considered.
	 * </p>
	 * <p>
	 * We had to use a different name than <code>getTextFileBuffer</code> for this method
	 * due to https://bugs.eclipse.org/bugs/show_bug.cgi?id=148844
	 * </p>
	 *
	 * @param fileStore the file store
	 * @return the text file buffer managed for that file store or <code>null</code>
	 * @since 3.3
	 */
	ITextFileBuffer getFileStoreTextFileBuffer(IFileStore fileStore);

	
Returns the text file buffer managed for the given document
or null if there is no such text file buffer.

Note: This method goes through the list
of registered buffers and tests whether its document matches
the given one. Therefore this method should not be used in
performance critical code.

Params:
document – the document for which to find the text file buffer
Returns:
the text file buffer managed for that document or null
Since:
3.3/**
	 * Returns the text file buffer managed for the given document
	 * or <code>null</code> if there is no such text file buffer.
	 * <p>
	 * <strong>Note:</strong> This method goes through the list
	 * of registered buffers and tests whether its document matches
	 * the given one. Therefore this method should not be used in
	 * performance critical code.
	 * </p>
	 *
	 * @param document the document for which to find the text file buffer
	 * @return the text file buffer managed for that document or <code>null</code>
	 * @since 3.3
	 */
	ITextFileBuffer getTextFileBuffer(IDocument document);

	
Returns the default encoding that is used to read the contents of text files
if no other encoding is specified.
Returns:
the default text file encoding/**
	 * Returns the default encoding that is used to read the contents of text files
	 * if no other encoding is specified.
	 *
	 * @return the default text file encoding
	 */
	String getDefaultEncoding();

	
Creates a new empty document. The document is set up in the same way as it would be used in a
text file buffer for a file at the given location.

The provided location is either a full path of a workspace resource or an absolute path in
the local file system. The file buffer manager does not resolve the location of workspace
resources in the case of linked resources.

Params:
location – the location used to set up the newly created document or null
           if unknown
Returns:
a new empty document
Deprecated:
As of 3.3, replaced by createEmptyDocument(IPath, LocationKind)/**
	 * Creates a new empty document. The document is set up in the same way as it would be used in a
	 * text file buffer for a file at the given location.
	 * <p>
	 * The provided location is either a full path of a workspace resource or an absolute path in
	 * the local file system. The file buffer manager does not resolve the location of workspace
	 * resources in the case of linked resources.
	 * </p>
	 *
	 * @param location the location used to set up the newly created document or <code>null</code>
	 *            if unknown
	 * @return a new empty document
	 * @deprecated As of 3.3, replaced by {@link #createEmptyDocument(IPath, LocationKind)}
	 */
	@Deprecated
	IDocument createEmptyDocument(IPath location);

	
Creates a new empty document. The document is set up in the same way as it would be used in a
text file buffer for a file at the given location.

The type of the provided location is specified by the given locationKind.

Params:
location – the location used to set up the newly created document or null
           if unknown
locationKind – the kind of the given location
Returns:
a new empty document
Since:
3.3/**
	 * Creates a new empty document. The document is set up in the same way as it would be used in a
	 * text file buffer for a file at the given location.
	 * <p>
	 * The type of the provided location is specified by the given <code>locationKind</code>.
	 * </p>
	 *
	 * @param location the location used to set up the newly created document or <code>null</code>
	 *            if unknown
	 * @param locationKind the kind of the given location
	 * @return a new empty document
	 * @since 3.3
	 */
	IDocument createEmptyDocument(IPath location, LocationKind locationKind);

	
Creates a new annotation for the given location.

The provided location is either a full path of a workspace resource or an
absolute path in the local file system. The file buffer manager does not
resolve the location of workspace resources in the case of linked
resources.

Params:
location – the location used to create the new annotation model
Returns:
the newly created annotation model
Deprecated:
As of 3.3, replaced by createAnnotationModel(IPath, LocationKind)/**
	 * Creates a new annotation for the given location.
	 * <p>
	 * The provided location is either a full path of a workspace resource or an
	 * absolute path in the local file system. The file buffer manager does not
	 * resolve the location of workspace resources in the case of linked
	 * resources.
	 * </p>
	 *
	 * @param location the location used to create the new annotation model
	 * @return the newly created annotation model
	 * @deprecated As of 3.3, replaced by {@link #createAnnotationModel(IPath, LocationKind)}
	 */
	@Deprecated
	IAnnotationModel createAnnotationModel(IPath location);

	
Creates a new annotation for the given location.

The type of the provided location is specified by the given
locationKind.

Params:
location – the location used to create the new annotation model
locationKind – the kind of the given location
Returns:
the newly created annotation model
Since:
3.3/**
	 * Creates a new annotation for the given location.
	 * <p>
	 * The type of the provided location is specified by the given
	 * <code>locationKind</code>.
	 * </p>
	 *
	 * @param location the location used to create the new annotation model
	 * @param locationKind the kind of the given location
	 * @return the newly created annotation model
	 * @since 3.3
	 */
	IAnnotationModel createAnnotationModel(IPath location, LocationKind locationKind);

	
Returns whether a file at the given location is or can be considered a
text file. If the file exists, the concrete content type of the file is
checked. If the concrete content type for the existing file can not be
determined, this method returns true. If the file does
not exist, it is checked whether a text content type is associated with
the given location. If no content type is associated with the location,
this method returns true.

The provided location is either a full path of a workspace resource or an
absolute path in the local file system. The file buffer manager does not
resolve the location of workspace resources in the case of linked
resources.

Params:
location – the location to check
Returns:
true if the location is a text file location
Since:
3.1
Deprecated:
As of 3.2, replaced by isTextFileLocation(IPath, boolean)/**
	 * Returns whether a file at the given location is or can be considered a
	 * text file. If the file exists, the concrete content type of the file is
	 * checked. If the concrete content type for the existing file can not be
	 * determined, this method returns <code>true</code>. If the file does
	 * not exist, it is checked whether a text content type is associated with
	 * the given location. If no content type is associated with the location,
	 * this method returns <code>true</code>.
	 * <p>
	 * The provided location is either a full path of a workspace resource or an
	 * absolute path in the local file system. The file buffer manager does not
	 * resolve the location of workspace resources in the case of linked
	 * resources.
	 * </p>
	 *
	 * @param location the location to check
	 * @return <code>true</code> if the location is a text file location
	 * @since 3.1
	 * @deprecated As of 3.2, replaced by {@link #isTextFileLocation(IPath, boolean)}
	 */
	@Deprecated
	boolean isTextFileLocation(IPath location);
	
Returns whether a file at the given location is or can be considered a
text file. If the file exists, the concrete content type of the file is
checked. If the concrete content type for the existing file can not be
determined, this method returns !strict. If the file does
not exist, it is checked whether a text content type is associated with
the given location. If no content type is associated with the location,
this method returns !strict.

The provided location is either a full path of a workspace resource or an
absolute path in the local file system. The file buffer manager does not
resolve the location of workspace resources in the case of linked
resources.

Params:
location – 	the location to check
strict – 	true if a file with unknown content type
					is not treated as text file, false otherwise
Returns:
true if the location is a text file location
Since:
3.2/**
	 * Returns whether a file at the given location is or can be considered a
	 * text file. If the file exists, the concrete content type of the file is
	 * checked. If the concrete content type for the existing file can not be
	 * determined, this method returns <code>!strict</code>. If the file does
	 * not exist, it is checked whether a text content type is associated with
	 * the given location. If no content type is associated with the location,
	 * this method returns <code>!strict</code>.
	 * <p>
	 * The provided location is either a full path of a workspace resource or an
	 * absolute path in the local file system. The file buffer manager does not
	 * resolve the location of workspace resources in the case of linked
	 * resources.
	 * </p>
	 *
	 * @param location	the location to check
	 * @param strict	<code>true</code> if a file with unknown content type
	 * 					is not treated as text file, <code>false</code> otherwise
	 * @return <code>true</code> if the location is a text file location
	 * @since 3.2
	 */
	boolean isTextFileLocation(IPath location, boolean strict);
}