cleanup and further comments
diff --git a/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IModelManagerProposed.java b/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IModelManagerProposed.java
index bf69585..5621de2 100644
--- a/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IModelManagerProposed.java
+++ b/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IModelManagerProposed.java
@@ -22,31 +22,31 @@
import org.eclipse.wst.sse.core.exceptions.ResourceInUse;
import org.eclipse.wst.sse.core.text.IStructuredDocument;
-
/**
- * Responsible for managing structured models.
+ * Responsible for managing IStructuredModels.
*
* This allows clients to share models, so they do not have to be re-created
- * or "passed around" from one client to another. There is a heavy burden on
- * clients, though, in that every client who 'gets' a model must correctly
- * 'release' it.
+ * or passed around from one client to another. Clients should internally
+ * enforce that models are gotten and released from locations close to each
+ * other to prevent model leaks.
*
- * There are two ways to get a model, for 'EDIT' or for 'READ'. Contrary to
- * their names, either model can, technically, be modified, and when modified,
- * it modifies the commonily shared version of the model. It is part of the
- * API contract however, that clients who get a model for READ do not modify
- * it. The significance of the 'EDIT' model is that the client is registering
- * their interest in saving changes to the model.
+ * There are three ways to get a model based on usage and responsibility: for
+ * 'WRITE', just for 'SHARED', and 'UNSHARED'. Contrary to their names, a
+ * model can technically be modified, and all modifications directly affect
+ * the commonly shared version of the model. It is part of the API contract,
+ * however, that clients who get a model for SHARED do not modify it. The
+ * significance of the 'WRITE' model is that the client is registering their
+ * interest in saving changes to the model.
*
* Clients can reference this interface, but should not implement.
*
- * @see StructuredModelManger
+ * @see StructuredModelManager
* @since 1.0
*/
public interface IModelManagerProposed {
/**
- * ReadEditType is used internally to create. Not intented to be
+ * ReadEditType is used internally to create. Not intended to be
* referenced by clients.
*/
static class ReadEditType {
@@ -71,64 +71,26 @@
}
/**
- * Constant to provide compile time safe paramenter. <code>EDIT</code>signifies
- * the client is intending to make changes and is responsible for saving
- * changes (or not) if they are the last one holding the model before its
- * released.
- */
- final ReadEditType WRITE = new ReadEditType("WRITE"); //$NON-NLS-1$
- /**
- * Constant to provide compile time safe paramenter. <code>READ</code>signifies
- * the client is not intending to make changes and does not care about the
- * saved state of the model.
- */
- final ReadEditType SHARED = new ReadEditType("SHARED"); //$NON-NLS-1$
- /**
- * Constant to provide compile time safe paramenter.
- * <code>NOTSHARED</code>signifies the client intentially wants a model
- * that is not shared with other clients. Note: NOTSHARED models can not
- * be saved.
+ * Constant to provide compile time safe parameter. <code>NOTSHARED</code>signifies
+ * the client intentially wants a model that is not shared with other
+ * clients. NOTSHARED models can not be saved.
*/
final ReadEditType NOTSHARED = new ReadEditType("NOTSHARED"); //$NON-NLS-1$
/**
- * createNewInstance is similar to clone, except the new instance has no
- * text content. Note: this produces an UNSHARED model, for temporary use,
- * that has the same characteristics as original model. If a true shared
- * model is desired, use "copy".
- *
- * ISSUE: still needed?
+ * Constant to provide compile-time safe parameter. <code>SHARED</code>signifies
+ * the client is not intending to make changes and does not care whether
+ * the model accessed is saved.
*/
- public IStructuredModel createNewInstance(Object requester, IStructuredModel model) throws IOException;
+ final ReadEditType SHARED = new ReadEditType("SHARED"); //$NON-NLS-1$
/**
- * Returns the model, if it already exists and is being shared. Returns
- * null if this is not the case.
- *
- * @param location
- * @param type
- * @return
+ * Constant to provide compile-time safe parameter. <code>WRITE</code>signifies
+ * the client is intending to make changes and is responsible for saving
+ * changes (or not) if they are the last one holding WRITE access to the
+ * model before it's released.
*/
- public IStructuredModel getExistingModel(Object requester, ReadEditType type, IPath location);
-
- /**
- * Returns the model that has the specified document as its core text
- * buffer.
- *
- * @param document
- * @param type
- * @return
- */
- public IStructuredModel getModel(Object requester, ReadEditType type, IProgressMonitor progressMonitor, IDocument document);
-
- /**
- * Returns the model based on the content at the specified location.
- *
- * @param location
- * @param type
- * @return
- */
- public IStructuredModel getModel(Object requester, ReadEditType type, IProgressMonitor progressMonitor, IPath location) throws IOException, CoreException;
+ final ReadEditType WRITE = new ReadEditType("WRITE"); //$NON-NLS-1$
/**
* copyModel is similar to a deep clone. The resulting model is shared,
@@ -137,54 +99,139 @@
* unless the ReadEditType is NOTSHARED, in which case the resulting model
* can not be saved.
*
- * @param oldId
- * @param newId
+ * @param oldLocation
+ * @param newLocation
+ * @param type
* @return
* @throws ResourceInUse
*
- *
* ISSUE: is this important enough to be API, or can clients solve
- * themselves
+ * themselves
*/
IStructuredModel copyModel(IPath oldLocation, IPath newLocation, ReadEditType type) throws ResourceInUse;
/**
+ * createNewInstance is similar to clone, except the new instance has no
+ * text content. Note: this produces an UNSHARED model, for temporary use,
+ * that has the same characteristics as original model. If a true shared
+ * model is desired, use "copy".
+ *
+ * ISSUE: still needed?
+ *
+ * @param requester
+ * @param model
+ * @return
+ * @throws IOException
+ */
+ public IStructuredModel createNewInstance(Object requester, IStructuredModel model) throws IOException;
+
+ /**
* Factory method, since a proper IStructuredDocument must have a proper
- * parser assigned. Note: its assume that IFile does not actually exist as
+ * parser assigned. Note: its assume that IPath does not actually exist as
* a resource yet. If it does, ResourceAlreadyExists exception is thrown.
* If the resource does already exist, then createStructuredDocumentFor is
* the right API to use.
*
* ISSUE: do we want to support this via model manager, or else where?
* ISSUE: do we need two of these? What's legacy use case?
+ *
+ * @param location
+ * @param progressMonitor
+ * @return
+ * @throws ResourceAlreadyExists
+ * @throws IOException
+ * @throws CoreException
*/
IStructuredDocument createNewStructuredDocumentFor(IPath location, IProgressMonitor progressMonitor) 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.
+ * parser assigned. Note: clients should verify that the resource
+ * identified by the IPath exists before using this method. If this IFile
+ * does not exist, then createNewStructuredDocument is the correct API to
+ * use.
*
* ISSUE: do we want to support this via model manager, or else where?
* ISSUE: do we need two of these? What's legacy use case?
+ *
+ * @param location
+ * @param progressMonitor
+ * @return
+ * @throws IOException
+ * @throws CoreException
*/
IStructuredDocument createStructuredDocumentFor(IPath location, IProgressMonitor progressMonitor) throws IOException, CoreException;
/**
- * Note: users of this 'model' must still release it when finished.
- * Returns null if there's not a model corresponding to document.
+ * Note: callers of this method must still release the model when
+ * finished. Returns the model for this document if it already exists and
+ * is being shared. Returns null if this is not the case. The ReadEditType
+ * must be either WRITE or SHARED.
*
* ISSUE: should we accept IDocument on parameter for future evolution,
* and constrain to StructuredDocuments at runtime?
+ *
+ * @param requester
+ * @param type
+ * @param document
+ * @return
*/
IStructuredModel getExistingModel(Object requester, ReadEditType type, IDocument document);
/**
+ * Callers of this method must still release the model when finished.
+ * Returns the model for this location if it already exists and is being
+ * shared. Returns null if this is not the case. The ReadEditType must be
+ * either WRITE or SHARED.
+ *
+ * @param requester
+ * @param type
+ * @param location
+ * @return
+ */
+ public IStructuredModel getExistingModel(Object requester, ReadEditType type, IPath location);
+
+ /**
+ * Returns the model that has the specified document as its structured
+ * document.
+ *
+ * @param requester
+ * @param type
+ * @param progressMonitor
+ * @param document
+ * @return
+ */
+ public IStructuredModel getModel(Object requester, ReadEditType type, IProgressMonitor progressMonitor, IDocument document);
+
+ /**
+ * Returns the model based on the content at the specified location.
+ *
+ * @param requester
+ * @param type
+ * @param progressMonitor
+ * @param location
+ * @return
+ * @throws IOException
+ * @throws CoreException
+ */
+ public IStructuredModel getModel(Object requester, ReadEditType type, IProgressMonitor progressMonitor, IPath location) throws 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 requester
+ * @param location
+ * @param force
+ * @param type
+ * @param progressMonitor
+ * @return
+ * @throws ResourceAlreadyExists
+ * @throws ResourceInUse
+ * @throws IOException
+ * @throws CoreException
*/
IStructuredModel getNewModel(Object requester, IPath location, boolean force, ReadEditType type, IProgressMonitor progressMonitor) throws ResourceAlreadyExists, ResourceInUse, IOException, CoreException;
@@ -192,15 +239,19 @@
* This function returns true if there are other references to the
* underlying model.
*
- * @param id
- * Object The id of the model
+ * @param location
+ * @return
*/
boolean isShared(IPath location);
/**
* This function returns true if there are other references to the
- * underlying model, shared in the specified way.
+ * underlying model, shared in the specified way. The ReadEditType must be
+ * either WRITE or SHARED.
*
+ * @param location
+ * @param type
+ * @return
*/
boolean isShared(IPath location, ReadEditType type);
@@ -209,11 +260,30 @@
* 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.
*
+ * @param model
+ * @return
+ * @throws IOException
*/
IStructuredModel reinitialize(IStructuredModel model) throws IOException;
/**
+ * This is used by clients to signify that they are finished with a model
+ * and will no longer access it or any of its underlying data (such as its
+ * structured document). The ReadEditType must match what ever the client
+ * used in the corresponding 'get' method.
+ *
+ * This method must be called for every 'get'. Clients should use the
+ * try/finally pattern to ensure the release is called even if there is an
+ * unexpected exception.
+ *
+ * @param requester
+ * @param structuredModel
+ * @param type
+ */
+ void releaseModel(Object requester, IStructuredModel structuredModel, ReadEditType type);
+
+ /**
* Writes the underlying document to the IPath.
*
* ISSUE: we want to just "dump" contents to location, but need to spec.
@@ -232,8 +302,8 @@
*
*
* @param structuredModel
- * @param location
- * normalized?
+ * @param location - already normalized?
+ * @param progressMonitor
* @throws UnsupportedEncodingException
* @throws IOException
* @throws CoreException
@@ -249,7 +319,8 @@
* or other client that might desire user intervention to save a resource.
*
* @param structuredModel
- * @param location
+ * @param location - already normalized?
+ * @param progressMonitor
* @throws UnsupportedEncodingException
* @throws IOException
* @throws CoreException
@@ -258,20 +329,4 @@
* created with
*/
void saveModelIfNotShared(IStructuredModel structuredModel, IPath location, IProgressMonitor progressMonitor) throws UnsupportedEncodingException, IOException, CoreException;
-
- /**
- * This is used by clients to signify that they are finished with a model
- * and will no longer access it or any of its underlying data (such as its
- * structured document). The ReadEditType must match what ever the client
- * used in the corresponding 'get' method.
- *
- * This method must be called for every 'get'. Clients should use the
- * try/finally pattern to ensure the release is called even if there is an
- * unexpected exception.
- *
- * @param structuredModel
- * @param type
- */
- void releaseModel(Object requester, IStructuredModel structuredModel, ReadEditType type);
-
}