/*******************************************************************************
* Copyright (c) 2001, 2006 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
*
*******************************************************************************/
package org.eclipse.wst.sse.core.internal.provisional.model;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.jface.text.IDocument;
import org.eclipse.wst.sse.core.internal.provisional.IStructuredModel;
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;
/**
* 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. Clients should internally
* enforce that models are gotten and released from locations close to each
* other to prevent model leaks.
*
* There are three ways to get a model based on usage and responsibility: for
* 'MODIFY', 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 'MODIFY' 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 org.eclipse.wst.sse.core.StructuredModelManager
* @plannedfor 1.0
*/
public interface IModelManagerProposed {
/**
* AccessType is used internally as a JRE 1.4 compatible enumerated type.
* Not intended to be referenced by clients.
*/
static class AccessType {
private String fType;
/**
* default access contructor we use to create our specific constants.
*
* @param type
*/
AccessType(String type) {
super();
fType = type;
}
/**
* For debug purposes only.
*/
public String toString() {
return "Model Access Type: " + fType; //$NON-NLS-1$
}
}
/**
* 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 AccessType NOTSHARED = new AccessType("NOTSHARED"); //$NON-NLS-1$
/**
* 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.
*/
final AccessType SHARED = new AccessType("SHARED"); //$NON-NLS-1$
/**
* Constant to provide compile-time safe parameter. <code>MODIFY</code>signifies
* the client is intending to make changes and is responsible for saving
* changes (or not) if they are the last one holding MODIFY access to the
* model before it's released.
*/
final AccessType MODIFY = new AccessType("MODIFY"); //$NON-NLS-1$
/**
* copyModel is similar to a deep clone. The resulting model is shared,
* according to the value of ReadEditType. If a model already is being
* managed for 'newLocation' then a ResourceInUse exception is thrown,
* unless the ReadEditType is NOTSHARED, in which case the resulting model
* can not be saved.
*
* @param oldLocation
* @param newLocation
* @param type
* @return
* @throws ResourceInUse
*
* ISSUE: is this important enough to be API, or can clients solve
* themselves
*/
IStructuredModel copyModel(IPath oldLocation, IPath newLocation, AccessType 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 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 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: 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 MODIFY 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, AccessType 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 MODIFY or SHARED.
*
* @param requester
* @param type
* @param location
* @return
*/
public IStructuredModel getExistingModel(Object requester, AccessType 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, AccessType type, IProgressMonitor progressMonitor, IDocument document);
/**
* Returns the model based on the content at the specified location.
*
* Note: if the ModelManager does not know how to create a model for
* such a file for content, null is return.
* ISSUE: should we throw some special, meaningful, checked
* exception instead?
*
* @param requester
* @param type
* @param progressMonitor
* @param location
* @return
* @throws IOException
* @throws CoreException
*/
public IStructuredModel getModel(Object requester, AccessType 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, AccessType type, IProgressMonitor progressMonitor) throws ResourceAlreadyExists, ResourceInUse, IOException, CoreException;
/**
* This function returns true if there are other references to the
* underlying 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. The ReadEditType must be
* either MODIFY or SHARED.
*
* @param location
* @param type
* @return
*/
boolean isShared(IPath location, AccessType type);
/**
* This method can be called when the content type of a model changes. Its
* 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, AccessType type);
/**
* Writes the underlying document to the IPath.
*
* ISSUE: we want to just "dump" contents to location, but need to spec.
* all the different cases of shared, etc.
*
* ?If to same location as 'get', then same instance of model, If to
* different location (esp. if shared) then need to leave old instance of
* model, create new model, and save to new location. ?
*
* Cases: IPath is null, write to IPath created with IPath specificed and
* equals IPath created with, write to IPath IPath specified and not
* equals IPath created with, dumps to new IPath, no change in current
* model state.
*
* ISSUE: think through 'normalization' cases
*
*
* @param structuredModel
* @param location - already normalized?
* @param progressMonitor
* @throws UnsupportedEncodingException
* @throws IOException
* @throws CoreException
*
* ISSUE: resource aleady exists? veto override
*/
void saveModel(IStructuredModel structuredModel, IPath location, IProgressMonitor progressMonitor) throws UnsupportedEncodingException, IOException, CoreException;
/**
* Writes the underlying document to the IPath if the model is only shared
* for EDIT by one client. This is the recommended way for 'background
* jobs' to save models, in case the model is being shared by an editor,
* or other client that might desire user intervention to save a resource.
*
* @param structuredModel
* @param location - already normalized?
* @param progressMonitor
* @throws UnsupportedEncodingException
* @throws IOException
* @throws CoreException
*
* ISSUE: is locaiton needed in this case, or just use the one it was
* created with
*/
void saveModelIfNotShared(IStructuredModel structuredModel, IPath location, IProgressMonitor progressMonitor) throws UnsupportedEncodingException, IOException, CoreException;
}