| /******************************************************************************* |
| * Copyright (c) 2001, 2009 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.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 the right syntax colors. |
| * </p> |
| * <p> |
| * There are two types of access used when retrieving a model from the model |
| * manager: read or edit. The contents of the 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> |
| * |
| * @noimplement This interface is not intended to be implemented by clients. |
| * </p> |
| * <p> |
| * @see StructuredModelManger</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 |
| * @throws IOException |
| */ |
| 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 |
| * @throws ResourceAlreadyExists |
| * if the IFile already exists |
| * @throws IOException |
| * @throws CoreException |
| */ |
| 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 |
| * createNewStructuredDocument is the correct API to use. |
| */ |
| 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, or null if one could not be created |
| */ |
| IStructuredDocument createStructuredDocumentFor(String contentTypeId); |
| |
| /** |
| * @deprecated -- I marked as deprecated to discouage use of this method. |
| * It does not really work for JSP fragments, since JSP |
| * Fragments need an IFile to correctly look up the content |
| * settings. Use IFile form instead. Note: some confustion |
| * with it and the form for HTPP encoding, so once a null arg |
| * is allowed in that API ... we can remove this one. (after |
| * verifying again with Tom/Linksbuild) |
| */ |
| IStructuredDocument createStructuredDocumentFor(String filename, InputStream inputStream, URIResolver resolver) throws IOException; |
| |
| /** |
| * @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; |
| |
| /** |
| * @param filename |
| * @param content |
| * @param resolver |
| * @return a structured document with the correct parsing setup for the |
| * given filename, or null if one could not be created |
| * @throws IOException |
| */ |
| 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 IOException |
| * @throws CoreException |
| */ |
| 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 |
| */ |
| 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 |
| */ |
| public IStructuredModel getModelForEdit(IFile iFile) throws IOException, CoreException; |
| |
| /** |
| * @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); |
| |
| /* |
| * @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 |
| */ |
| 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); |
| |
| /** |
| * @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. |
| */ |
| 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. |
| */ |
| IStructuredModel getNewModelForRead(IFile iFile, boolean force) throws ResourceAlreadyExists, ResourceInUse, IOException, CoreException; |
| |
| /** |
| * This function returns the 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 getReferenceCount(Object id); |
| |
| /** |
| * This function returns the 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 getReferenceCountForEdit(Object id); |
| |
| /** |
| * This function returns the 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 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 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; |
| |
| void saveStructuredDocument(IStructuredDocument structuredDocument, IFile iFile) throws UnsupportedEncodingException, IOException, CoreException; |
| |
| } |