diff options
Diffstat (limited to 'bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/internal/provisional/IModelManager.java')
| -rw-r--r-- | bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/internal/provisional/IModelManager.java | 554 |
1 files changed, 0 insertions, 554 deletions
diff --git a/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/internal/provisional/IModelManager.java b/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/internal/provisional/IModelManager.java deleted file mode 100644 index b23d0fa9a1..0000000000 --- a/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/internal/provisional/IModelManager.java +++ /dev/null @@ -1,554 +0,0 @@ -/******************************************************************************* - * Copyright (c) 2001, 2010 IBM Corporation and others. - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * which accompanies this distribution, and is available at - * http://www.eclipse.org/legal/epl-v10.html - * - * Contributors: - * IBM Corporation - initial API and implementation - * Jens Lukowski/Innoopract - initial renaming/restructuring - * - *******************************************************************************/ -package org.eclipse.wst.sse.core.internal.provisional; - -import java.io.IOException; -import java.io.InputStream; -import java.io.UnsupportedEncodingException; -import java.util.Enumeration; - -import org.eclipse.core.resources.IFile; -import org.eclipse.core.runtime.CoreException; -import org.eclipse.jface.text.IDocument; -import org.eclipse.wst.sse.core.StructuredModelManager; -import org.eclipse.wst.sse.core.internal.encoding.EncodingRule; -import org.eclipse.wst.sse.core.internal.provisional.exceptions.ResourceAlreadyExists; -import org.eclipse.wst.sse.core.internal.provisional.exceptions.ResourceInUse; -import org.eclipse.wst.sse.core.internal.provisional.text.IStructuredDocument; -import org.eclipse.wst.sse.core.internal.util.URIResolver; - -/** - * <p> - * Provides APIs for managing (get, release, save, and save as) SSE Structured - * Models. - * </p> - * <p> - * Structured Models created from an implementor of this interface can be - * either managed or unmanaged. Managed models are shared using reference - * counts, so until that count has been decremented to zero, the model will - * continue to exist in memory. When managed, models can be looked up using - * their IDs or their IStructuredDocuments, which can be advantageous when - * building on APIs that aren't specifically designed for SSE (such as those - * revolving around IDocuments). Unmanaged models offer no such features, and - * are largely used for tasks where their contents are ephemeral, such as for - * populating a source viewer with syntax-colored content. - * </p> - * <p> - * There are two types of access used when retrieving a model from the model - * manager: READ and EDIT. The contents of a model can be modified regardless - * of which access type is used, but any client who gets a model for EDIT is - * explicitly declaring that they are interested in saving those changed - * contents. The EDIT and READ reference counts are visible to everyone, as - * are convenience methods for determining whether a managed model is shared - * among multiple clients accessing it for READ or EDIT. - * </p> - * <p> - * Managed models whose contents are "dirty" with READ and EDIT counts above - * zero will be reverted to the on-disk content if the EDIT count drops to - * zero while the READ count remains above zero. - * </p> - * <p> - * Shared models for which the read and edit counts have both dropped to zero - * are no longer valid for use, regardless of whether they have been garbage - * collected or not. It is possible, but not guaranteed, that the underlying - * structured document is still valid and may even be used in constructing a - * new shared model. - * </p> - * <p> - * - * @noimplement This interface is not intended to be implemented by clients. - * Clients should obtain an instance of the IModelManager interface through - * {@link StructuredModelManager#getModelManager()}.</p> - * </p> - * <p> - * @see {@link StructuredModelManager}</p> - */ -public interface IModelManager { - - /** - * A fixed ID used for models which were created as duplicates of existing - * models - */ - public final static String DUPLICATED_MODEL = "org.eclipse.wst.sse.core.IModelManager.DUPLICATED_MODEL"; //$NON-NLS-1$ - - /** - * A fixed ID used for unmanaged models - */ - public final static String UNMANAGED_MODEL = "org.eclipse.wst.sse.core.IModelManager.UNMANAGED_MODEL"; //$NON-NLS-1$ - - /** - * Calculate id provides a common way to determine the id from the input - * ... needed to get and save the model. It is a simple class utility, but - * is an instance method so can be accessed via interface. - */ - public String calculateId(IFile file); - - /** - * Copies a model with the old id - * @param oldId - the old model's ID - * @param newId - the new model's ID - * @return the new model - * @throws ResourceInUse if the given new ID is already in use by a managed model - */ - IStructuredModel copyModelForEdit(String oldId, String newId) throws ResourceInUse; - - /** - * Creates a new, but empty, unmanaged model of the same kind as the one - * given. For a managed model with the same contents, use "copy". - * - * @param model - * @return the model, or null of one could not be created - * @throws IOException if the file's contents can not be read or its detected encoding does not support its contents - */ - public IStructuredModel createNewInstance(IStructuredModel model) throws IOException; - - /** - * Factory method, since a proper IStructuredDocument must have a proper - * parser assigned. If the resource does already exist, then - * createStructuredDocumentFor is the right API to use. - * - * @param iFile - * @return the document, or null if one could not be created - * @throws ResourceAlreadyExists - * if the IFile already exists - * @throws CoreException if the file's contents or description can not be read - * @throws IOException if the file's contents can not be read or its detected encoding does not support its contents - * @throws ResourceAlreadyExists if the give file already exists - */ - IStructuredDocument createNewStructuredDocumentFor(IFile iFile) throws ResourceAlreadyExists, IOException, CoreException; - - /** - * Factory method, since a proper IStructuredDocument must have a proper - * parser assigned. Note: clients should verify IFile exists before using - * this method. If this IFile does not exist, then - * {@link #createNewStructuredDocumentFor(IFile)} is the correct API to use. - * - * @param iFile - the file - * @return the document, or null if one could not be created - * - * @throws CoreException if the file's contents or description can not be read - * @throws IOException if the file's contents can not be read or its detected encoding does not support its contents - */ - IStructuredDocument createStructuredDocumentFor(IFile iFile) throws IOException, CoreException; - - /** - * Convenience method, since a proper IStructuredDocument must have a - * proper parser assigned. It should only be used when an empty - * structuredDocument is needed. Otherwise, use IFile form. - * - * @param contentTypeId - * @return a structured document with the correct parsing setup for the - * given content type ID, or null if one could not be created or - * the given content type ID is unknown or unsupported - */ - IStructuredDocument createStructuredDocumentFor(String contentTypeId); - - /** - * @deprecated - use IFile form instead as the correct encoding and content rules may not be applied otherwise - * - * Creates and returns a properly configured structured document for the given contents with the given name - * - * @param filename - the filename, which may be used to guess the content type - * @param contents - the contents to load - * @param resolver - the URIResolver to use for locating any needed resources - * @return the IStructuredDocument or null of one could not be created - * @throws IOException if the file's contents can not be read or its content type can not be determined - */ - IStructuredDocument createStructuredDocumentFor(String filename, InputStream contents, URIResolver resolver) throws IOException; - - /** - * Creates and returns a properly configured structured document for the given contents with the given name - * - * @param filename - the filename, which may be used to guess the content type - * @param inputStream - the contents to load - * @param resolver - the URIResolver to use for locating any needed resources - * @param ianaEncodingName - the IANA specified encoding to use when reading the contents - * @return the IStructuredDocument or null if one could not be created - * @throws IOException if the file's contents can not be read or its content type can not be determined - * @deprecated - clients should convert the InputStream into text themselves - * and then use the version of this method taking a String for its - * content - */ - IStructuredDocument createStructuredDocumentFor(String filename, InputStream inputStream, URIResolver resolver, String ianaEncodingName) throws IOException; - - /** - * Creates and returns a properly configured structured document for the given contents with the given name - * - * @param filename - the filename, which may be used to guess the content type - * @param content - the contents to load - * @param resolver - the URIResolver to use for locating any referenced resources - * @return a structured document with the correct parsing setup for the - * given filename, or null if one could not be created - * @throws IOException if the file's contents can not be read or its detected encoding does not support its contents - */ - IStructuredDocument createStructuredDocumentFor(String filename, String content, URIResolver resolver) throws IOException; - - /** - * Creates and returns an unmanaged model populated with the given IFile's - * contents - * - * @param iFile - * @return a structured model, or null if one could not be created - * @throws CoreException if the file's contents or description can not be read - * @throws IOException if the file's contents can not be read or its detected encoding does not support its contents - */ - IStructuredModel createUnManagedStructuredModelFor(IFile iFile) throws IOException, CoreException; - - /** - * Convenience method. It depends on the loader's newModel method to return - * an appropriate StrucuturedModel appropriately initialized. - * - * @param contentTypeId - * @return a structured model for the given content type, or null if one could not be created or the content type is unsupported - */ - IStructuredModel createUnManagedStructuredModelFor(String contentTypeId); - - /** - * @deprecated - */ - IStructuredModel createUnManagedStructuredModelFor(String contentTypeId, URIResolver resolver); - - /** - * Note: callers of this method must still release the model when finished. - * - * @param document - * @return the structured model containing the give document, incrementing - * its edit count, or null if there is not a model corresponding - * to this document. - */ - IStructuredModel getExistingModelForEdit(IDocument document); - - /** - * @param file - * @return the structured model for the given file, incrementing its edit - * count, or null if one does not already exist for this file. - */ - IStructuredModel getExistingModelForEdit(IFile file); - - /** - * @param id - * @return the structured model with the given ID, incrementing its edit - * count, or null if one does not already exist for this ID - */ - public IStructuredModel getExistingModelForEdit(Object id); - - /** - * Note: callers of this method must still release the model when finished. - * - * @param document - * @return the structured model containing the give document, incrementing - * its read count, or null if there is not a model corresponding - * to this document. - */ - IStructuredModel getExistingModelForRead(IDocument document); - - /** - * @param file - * @return the structured model for the given file, incrementing its read - * count, or null if one does not already exist for this file. - */ - public IStructuredModel getExistingModelForRead(IFile iFile); - - /** - * @param id - * @return the structured model with the given ID, incrementing its edit - * count, or null if one does not already exist for this ID - */ - public IStructuredModel getExistingModelForRead(Object id); - - /** - * @deprecated - internal information - */ - public Enumeration getExistingModelIds(); - - /** - * Returns a structured model for the given file. If one does not already - * exists, one will be created with an edit count of 1. If one already - * exists, its edit count will be incremented before it is returned. - * - * @param iFile - * @return a structured model for the given file, or null if one could not - * be found or created - * @throws CoreException if the file's contents or description can not be read - * @throws IOException if the file's contents can not be read or its detected encoding does not support its contents - */ - public IStructuredModel getModelForEdit(IFile iFile) throws IOException, CoreException; - - /** - * Returns a structured model for the given file. If one does not already - * exists, one will be created with an edit count of 1. If one already - * exists, its edit count will be incremented before it is returned. - * - * @param iFile - * @param encodingRule the rule for handling encoding - * @return a structured model for the given file, or null if one could not - * be found or created - * @throws CoreException if the file's contents or description can not be read - * @throws IOException if the file's contents can not be read or its detected encoding does not support its contents - * @deprecated - encoding is handled automatically based on the file's - * contents or user preferences - */ - public IStructuredModel getModelForEdit(IFile iFile, EncodingRule encodingRule) throws UnsupportedEncodingException, IOException, CoreException; - - /** - * @deprecated - Encoding and the line delimiter used are handled - * automatically based on the file's contents or user - * preferences. - */ - public IStructuredModel getModelForEdit(IFile iFile, String encoding, String lineDelimiter) throws UnsupportedEncodingException, IOException, CoreException; - - /** - * Returns a structured model for the given document. If one does not - * already exists, one will be created with an edit count of 1. If one - * already exists, its edit count will be incremented before it is - * returned. This method is intended only to interact with documents - * contained within File Buffers. - * - * @param textFileBufferDocument - * @return a structured model for the given document, or null if there is - * insufficient information known about the document instance to - * do so - */ - public IStructuredModel getModelForEdit(IStructuredDocument textFileBufferDocument); - - /** - * Returns a structured model for the given contents using the given ID. - * If one does not already exist, one will be created with an edit count - * of 1. If one already exists, its edit count will be incremented before - * it is returned. - * - * @param id - * - the id for the model - * @param inStream - * - the initial contents of the model - * @param resolver - * - the URIResolver to use for locating any needed resources - * @return a structured model for the given content, or null if one could - * not be found or created - * @throws UnsupportedEncodingException - * @throws IOException - * if the contents can not be read or its detected encoding - * does not support its contents - * @deprecated - a URI resolver should be automatically created when - * needed - */ - public IStructuredModel getModelForEdit(String id, InputStream inStream, URIResolver resolver) throws UnsupportedEncodingException, IOException; - - /** - * Returns a structured model for the given file. If one does not already - * exists, one will be created with a read count of 1. If one already - * exists, its read count will be incremented before it is returned. - * - * @param iFile - * @return a structured model for the given file, or null if one could not - * be found or created - * @throws CoreException if the file's contents or description can not be read - * @throws IOException if the file's contents can not be read or its detected encoding does not support its contents - */ - public IStructuredModel getModelForRead(IFile iFile) throws IOException, CoreException; - - /** - * @deprecated - encoding is handled automatically based on the file's - * contents or user preferences - */ - public IStructuredModel getModelForRead(IFile iFile, EncodingRule encodingRule) throws UnsupportedEncodingException, IOException, CoreException; - - /** - * @deprecated - Encoding and the line delimiter used are handled - * automatically based on the file's contents or user - * preferences. - */ - public IStructuredModel getModelForRead(IFile iFile, String encoding, String lineDelimiter) throws UnsupportedEncodingException, IOException, CoreException; - - /** - * Returns a structured model for the given document. If one does not - * already exists, one will be created with a read count of 1. If one - * already exists, its read count will be incremented before it is - * returned. This method is intended only to interact with documents - * contained within File Buffers. - * - * @param textFileBufferDocument - * @return a structured model for the given document, or null if there is - * insufficient information known about the document instance to - * do so - */ - public IStructuredModel getModelForRead(IStructuredDocument textFileBufferDocument); - - /** - * Returns a structured model for the given contents using the given ID. - * If one does not already exist, one will be created with an read count - * of 1. If one already exists, its read count will be incremented before - * it is returned. - * - * @param id - * - the id for the model - * @param inStream - * - the initial contents of the model - * @param resolver - * - the URIResolver to use for locating any needed resources - * @return a structured model for the given content, or null if one could - * not be found or created - * @throws UnsupportedEncodingException - * @throws IOException - * if the contents can not be read or its detected encoding - * does not support its contents - * @deprecated - a URI resolver should be automatically created when - * needed - */ - public IStructuredModel getModelForRead(String filename, InputStream inStream, URIResolver resolver) throws UnsupportedEncodingException, IOException; - - /** - * This method will not create a new model if it already exists ... if - * force is false. The idea is that a client should call this method once - * with force set to false. If the exception is thrown, then prompt client - * if they want to overwrite. - * - * @param iFile - * @param force - * @return the new structured model, or - * @throws ResourceInUse if the given new ID is already in use by a managed model - * @throws CoreException if the file's contents or description can not be read - * @throws IOException if the file's contents can not be read or its detected encoding does not support its contents - * @throws ResourceAlreadyExists if the give file already exists - */ - IStructuredModel getNewModelForEdit(IFile iFile, boolean force) throws ResourceAlreadyExists, ResourceInUse, IOException, CoreException; - - /** - * This method will not create a new model if it already exists ... if - * force is false. The idea is that a client should call this method once - * with force set to false. If the exception is thrown, then prompt client - * if they want to overwrite. - * - * @param iFile - * @param force - * @return the new structured model, or - * @throws ResourceInUse if the given new ID is already in use by a managed model - * @throws CoreException if the file's contents or description can not be read - * @throws IOException if the file's contents can not be read or its detected encoding does not support its contents - * @throws ResourceAlreadyExists if the give file already exists - */ - IStructuredModel getNewModelForRead(IFile iFile, boolean force) throws ResourceAlreadyExists, ResourceInUse, IOException, CoreException; - - /** - * This function returns the combined "read" and "edit" reference counts - * of underlying model. - * - * @param id - * Object The id of the model - * @deprecated - internal information that can be obtained from the model - * itself - */ - int getReferenceCount(Object id); - - /** - * This function returns the "edit" reference count of underlying model. - * - * @param id - * Object The id of the model - * @deprecated - internal information that can be obtained from the model itself - */ - int getReferenceCountForEdit(Object id); - - /** - * This function returns the "read" reference count of underlying model. - * - * @param id - * Object The id of the model TODO: try to refine the design - * not to use this function - * @deprecated - internal information that can be obtained from the model itself - */ - int getReferenceCountForRead(Object id); - - /** - * This function returns true if there are other references to the - * underlying model. - * - * @param id - * Object The id of the model - */ - boolean isShared(Object id); - - /** - * This function returns true if there are other "edit" references to the - * underlying model. - * - * @param id - * Object The id of the model - */ - boolean isSharedForEdit(Object id); - - /** - * This function returns true if there are other "read" references to the - * underlying model. - * - * @param id - * Object The id of the model - */ - boolean isSharedForRead(Object id); - - /** - * @deprecated - not granular enough - * - * This method can be called to determine if the model manager is within a - * "aboutToChange" and "changed" sequence. - */ - public boolean isStateChanging(); - - /** - * This method changes the id of the model. - * - * TODO: try to refine the design - * not to use this function - * - * @deprecated - */ - void moveModel(Object oldId, Object newId); - - /** - * This method can be called when the content type of a model changes. It's - * assumed the contentType has already been changed, and this method uses - * the text of the old one, to repopulate the text of the new one. In - * theory, the actual instance could change, (e.g. using 'saveAs' to go - * from xml to dtd), but in practice, the intent of this API is to return - * the same instance, just using different handlers, adapter factories, - * etc. - */ - IStructuredModel reinitialize(IStructuredModel model) throws IOException; - - /** - * This is similar to the getModel method, except this method does not use - * the cached version, but forces the cached version to be replaced with a - * fresh, unchanged version. Note: this method does not change any - * reference counts. Also, if there is not already a cached version of the - * model, then this call is essentially ignored (that is, it does not put - * a model in the cache) and returns null. - * - * @deprecated - */ - IStructuredModel reloadModel(Object id, InputStream inStream) throws UnsupportedEncodingException; - - /** - * Saves the contents of the given structured document to the given file. If - * the document belongs to a managed model, that model will be saved and - * marked as non-dirty. - * - * @param structuredDocument - * - the structured document - * @param iFile - * - the file to save to - * @throws UnsupportedEncodingException - * @throws CoreException if the file's contents or description can not be read - * @throws IOException if the file's contents can not be read or its detected encoding does not support its contents - */ - void saveStructuredDocument(IStructuredDocument structuredDocument, IFile iFile) throws UnsupportedEncodingException, IOException, CoreException; -} |