diff options
Diffstat (limited to 'core/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/internal/provisional/IStructuredModel.java')
| -rw-r--r-- | core/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/internal/provisional/IStructuredModel.java | 419 |
1 files changed, 419 insertions, 0 deletions
diff --git a/core/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/internal/provisional/IStructuredModel.java b/core/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/internal/provisional/IStructuredModel.java new file mode 100644 index 0000000000..86690199d5 --- /dev/null +++ b/core/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/internal/provisional/IStructuredModel.java @@ -0,0 +1,419 @@ +/******************************************************************************* + * Copyright (c) 2001, 2011 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.OutputStream; +import java.io.UnsupportedEncodingException; + +import org.eclipse.core.resources.IFile; +import org.eclipse.core.resources.IResource; +import org.eclipse.core.runtime.CoreException; +import org.eclipse.core.runtime.IAdaptable; +import org.eclipse.wst.sse.core.internal.encoding.EncodingRule; +import org.eclipse.wst.sse.core.internal.ltk.modelhandler.IModelHandler; +import org.eclipse.wst.sse.core.internal.model.FactoryRegistry; +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.undo.IStructuredTextUndoManager; +import org.eclipse.wst.sse.core.internal.util.URIResolver; + + +/** + * IStructuredModels are mainly interesting by their extensions and + * implementers. The main purposed of this abstraction is to provide a common + * means to manage models that have an associated structured document. + * + * <p> + * TODO: this interface needs ton of cleanup! + * </p> + * + * @noimplement This interface is not intended to be implemented by clients. + */ +public interface IStructuredModel extends IAdaptable { + + + /** + * This API allows clients to declare that they are about to make a + * "large" change to the model. This change might be in terms of content + * or it might be in terms of the model id or base location. + * + * Note that in the case of embedded calls, notification to listeners is + * sent only once. + * + * Note that the client who is making these changes has the responsibility + * to restore the model's state once finished with the changes. See + * getMemento and restoreState. + * + * The method isModelStateChanging can be used by a client to determine if + * the model is already in a change sequence. + * + * This method is a matched pair to changedModel, and must be called + * before changedModel. A client should never call changedModel without + * calling aboutToChangeModel first nor call aboutToChangeModel without + * calling changedModel later from the same Thread. + */ + void aboutToChangeModel(); + + void addModelLifecycleListener(IModelLifecycleListener listener); + + void addModelStateListener(IModelStateListener listener); + + /** + * Begin recording undo transactions. + */ + void beginRecording(Object requester); + + /** + * Begin recording undo transactions. + */ + void beginRecording(Object requester, int cursorPosition, int selectionLength); + + /** + * Begin recording undo transactions. + */ + void beginRecording(Object requester, String label); + + /** + * Begin recording undo transactions. + */ + void beginRecording(Object requester, String label, int cursorPosition, int selectionLength); + + /** + * Begin recording undo transactions. + */ + void beginRecording(Object requester, String label, String description); + + /** + * Begin recording undo transactions. + */ + void beginRecording(Object requester, String label, String description, int cursorPosition, int selectionLength); + + /** + * This API allows a client controlled way of notifying all ModelEvent + * listeners that the model has been changed. This method is a matched + * pair to aboutToChangeModel, and must be called after aboutToChangeModel + * ... or some listeners could be left waiting indefinitely for the + * changed event. So, its suggested that changedModel always be in a + * finally clause. Likewise, a client should never call changedModel + * without calling aboutToChangeModel first. + * + * In the case of embedded calls, the notification is just sent once. + * + */ + void changedModel(); + + long computeModificationStamp(IResource resource); + + /** + * @deprecated + * @see IModelManager#copyModelForEdit(String, String) + */ + IStructuredModel copy(String id) throws ResourceInUse, ResourceAlreadyExists; + + /** + * Disable undo management. + * + * @deprecated - the ability to enable and disable Undo management for the + * model cannot be guaranteed as it implicitly requires + * knowledge of the underlying undo/redo implementation + */ + void disableUndoManagement(); + + /** + * Enable undo management. + * + * @deprecated - the ability to enable and disable Undo management for the + * model cannot be guaranteed as it implicitly requires + * knowledge of the underlying undo/redo implementation + */ + void enableUndoManagement(); + + /** + * End recording undo transactions. + */ + void endRecording(Object requester); + + /** + * End recording undo transactions. + */ + void endRecording(Object requester, int cursorPosition, int selectionLength); + + /** + * This is a client-defined value for what that client (and/or loader) + * considers the "base" of the structured model. Frequently the location + * is either a workspace root-relative path of a workspace resource or an + * absolute location in the local file system. + * + * @return the base location of the model or <code>null</code> when one + * has not been set, such as in models resulting from calling + * {@link IModelManager#createNewInstance(IStructuredModel)} + */ + String getBaseLocation(); + + /** + * @return The associated content type identifier (String) for this model. + * This value may be more accurate than the content type against + * which the model handler was registered. + * + * @see IModelHandler#getAssociatedContentTypeId() + */ + String getContentTypeIdentifier(); + + /** + * + * @return The model's FactoryRegistry. A model is not valid without one. + */ + FactoryRegistry getFactoryRegistry(); + + /** + * The id is the id that the model manager uses to identify this model + */ + String getId(); + + /** + * @param offset + * a text offset within the structured document + * @return an IndexedRegion containing this offset or null if one could + * not be found + */ + IndexedRegion getIndexedRegion(int offset); + + /** + * @return the model's handler + */ + IModelHandler getModelHandler(); + + IModelManager getModelManager(); + + /** + * @param id + * Object The id of the model TODO: try to refine the design + * not to use this function + * + * @return the reference count of underlying model + */ + int getReferenceCount(); + + /** + * This function returns the edit-responsible reference count of + * underlying model. + * + * @param id + * Object The id of the model TODO: try to refine the design + * not to use this function + */ + int getReferenceCountForEdit(); + + /** + * This function returns the reader reference count of underlying model. + * + * @param id + * Object The id of the model TODO: try to refine the design + * not to use this function + */ + int getReferenceCountForRead(); + + Object getReinitializeStateData(); + + /** + * Get URI resolution helper + * + * @deprecated - use org.eclipse.wst.common.uriresolver.internal.provisional.URIResolverPlugin.createResolver(*) instead + */ + URIResolver getResolver(); + + IStructuredDocument getStructuredDocument(); + + /** + * modification date of underlying resource, when this model was open, or + * last saved. (Note: for this version, the client must manage the + * accuracy of this data) + */ + long getSynchronizationStamp(); + + /** + * Get undo manager. + */ + IStructuredTextUndoManager getUndoManager(); + + /** + * + */ + boolean isDirty(); + + /** + * This method can be called to determine if the model is within a + * "aboutToChange" and "changed" sequence. + */ + public boolean isModelStateChanging(); + + /** + * + */ + boolean isNew(); + + boolean isReinitializationNeeded(); + + /** + * This is a combination of if the model is dirty and if the model is + * shared for write access. The last writer as the responsibility to be + * sure the user is prompted to save. + */ + public boolean isSaveNeeded(); + + /** + * This function returns true if either isSharedForRead or isSharedForEdit + * is true. + */ + boolean isShared(); + + /** + * This function returns true if there are other references to the + * underlying model. + */ + boolean isSharedForEdit(); + + /** + * This function returns true if there are other references to the + * underlying model. + */ + boolean isSharedForRead(); + + /** + * newInstance is similar to clone, except that the newInstance contains + * no content. Its purpose is so clients can get a temporary, unmanaged, + * model of the same "type" as the original. Note: the client may still + * need to do some initialization of the model returned by newInstance, + * depending on desired use. For example, the only factories in the + * newInstance are those that would be normally be created for a model of + * the given contentType. Others are not copied automatically, and if + * desired, should be added by client. + */ + IStructuredModel newInstance() throws IOException; + + /** + * Performs a reinitialization procedure. For this model. Note for future: + * there may be a day where the model returned from this method is a + * different instance than the instance it was called on. This will occur + * when there is full support for "save as" type functions, where the + * model could theoretically change completely. + */ + IStructuredModel reinit() throws IOException; + + /** + * This function allows the model to free up any resources it might be + * using. In particular, itself, as stored in the IModelManager. + * + */ + void releaseFromEdit(); + + /** + * This function allows the model to free up any resources it might be + * using. In particular, itself, as stored in the IModelManager. + * + */ + void releaseFromRead(); + + /** + * This function replenishes the model with the resource without saving + * any possible changes. It is used when one editor may be closing, and + * specifically says not to save the model, but another "display" of the + * model still needs to hang on to some model, so needs a fresh copy. + * + * Only valid for use with managed models. + */ + IStructuredModel reload(InputStream inputStream) throws IOException; + + void removeModelLifecycleListener(IModelLifecycleListener listener); + + void removeModelStateListener(IModelStateListener listener); + + /** + * A method that modifies the model's synchronization stamp to match the + * resource. Turns out there's several ways of doing it, so this ensures a + * common algorithm. + */ + void resetSynchronizationStamp(IResource resource); + + void resourceDeleted(); + + void resourceMoved(IStructuredModel newModel); + + void save() throws UnsupportedEncodingException, IOException, CoreException; + + /** + * @deprecated - will save according to the encoding priorities specified for the IFile + */ + void save(EncodingRule encodingRule) throws UnsupportedEncodingException, IOException, CoreException; + + void save(IFile iFile) throws UnsupportedEncodingException, IOException, CoreException; + + /** + * @deprecated - will save according to the encoding priorities specified for the IFile + */ + void save(IFile iFile, EncodingRule encodingRule) throws UnsupportedEncodingException, IOException, CoreException; + + void save(OutputStream outputStream) throws UnsupportedEncodingException, IOException, CoreException; + + /** + * Sets the base location of this model to the new value, also updating + * the value in its URI resolution helper if one is present. + * + * @param newBaseLocation + */ + void setBaseLocation(String newBaseLocation); + + public void setDirtyState(boolean dirtyState); + + void setFactoryRegistry(FactoryRegistry registry); + + /** + * The id is the id that the model manager uses to identify this model + */ + void setId(String id) throws ResourceInUse; + + void setModelHandler(IModelHandler modelHandler); + + void setModelManager(IModelManager modelManager); + + public void setNewState(boolean newState); + + /** + * Sets a "flag" that reinitialization is needed. + */ + void setReinitializeNeeded(boolean b); + + /** + * Holds any data that the reinitialization procedure might find useful in + * reinitializing the model. This is handy, since the reinitialization may + * not take place at once, and some "old" data may be needed to properly + * undo previous settings. Note: the parameter was intentionally made to + * be of type 'Object' so different models can use in different ways. + */ + void setReinitializeStateData(Object object); + + /** + * Set the URI resolution helper + */ + void setResolver(URIResolver uriResolver); + + void setStructuredDocument(IStructuredDocument structuredDocument); + + /** + * Set undo manager. + */ + void setUndoManager(IStructuredTextUndoManager undoManager); +} |