Carbide.c++

com.nokia.carbide.cpp.epoc.engine.model
Interface IModelProvider<Model extends IOwnedModel,SharedModel extends IModel>


public interface IModelProvider<Model extends IOwnedModel,SharedModel extends IModel>

Interface managing shared access to models.

The provider gives access to the factory, for creation of private Model instances, and provides shared instances through #findOrCreateModel(). The model provider is responsible for the real contents of the files provided to it through the #createModel(IPath) call, thus clients must use the provider for safe access to the file. Further, the provider exposes only the base interface IModel to limit inadvertent changes to shared models.

The domain of files managed is not specified by this interface –- a model provider may work entirely on memory buffers. But if an implementations of the model provider manage resources in the workspace, it is responsible for synchronizing the models with the workspace; e.g. persisting changes to IDocuments to the workspace and listening for changes to such resources outside its own APIs.


Method Summary
 Model createModel(IPath workspacePath)
          Create a new model with an empty document, which is slated to live at the given workspace path.
 SharedModel findSharedModel(IPath workspacePath)
          Find a registered Model instance for the given path.
 SharedModel getSharedModel(IPath workspacePath)
          Load a model for shared use.
 void load(Model model)
          Load the document of a model from persistent storage.
 void registerModel(Model model)
          Make a model visible to clients of the provider and manage its contents.
 void releaseSharedModel(SharedModel model)
          Indicate that the client is no longer using the model, which allows it to be eventually cleaned up.
 void save(Model model)
          Deprecated. since 1.4 (Carbide 2.0), this variant is unsafe, since the model is no longer locked during a save, so the document map from a model might be changing.
 void save(Model model, java.util.Map<IPath,IDocument> documentMap)
          Save the contents of a model's document(s) to persistent storage.
 void unregisterModel(Model model)
          Make a model invisible to clients of the provider and stop managing its contents.
 void updateModelDocumentMappings(Model model)
          Update tracked files using the map of IPath -> IDocument mappings for the model.
 

Method Detail

createModel

Model createModel(IPath workspacePath)
Create a new model with an empty document, which is slated to live at the given workspace path. (See getSharedModel(IPath) for the normal case of loading a model from an existing file.)

The returned model is not registered and its document is not tracked until #registerModel(IOwnedModel)) is called.

Parameters:
workspacePath - workspace-relative path.
Returns:
model (never null)

load

void load(Model model)
          throws CoreException
Load the document of a model from persistent storage. Only allowed on owned models. This either updates the existing document or replaces a null document with a new one.

Parameters:
model -
Throws:
CoreException

save

void save(Model model)
          throws CoreException
Deprecated. since 1.4 (Carbide 2.0), this variant is unsafe, since the model is no longer locked during a save, so the document map from a model might be changing.

Save the contents of a model's document(s) to persistent storage. Only allowed on owned models.

Parameters:
model -
Throws:
CoreException

save

void save(Model model,
          java.util.Map<IPath,IDocument> documentMap)
          throws CoreException
Save the contents of a model's document(s) to persistent storage. Only allowed on owned models.

This variant is called directly from a model when views commit themselves. The model is no longer locked, but the provided document map is consistent and may be persisted as a group. This change was made to avoid deadlocks when a model save triggers a resource change event which also wants to reread the model.

Parameters:
model -
documentMap - a copy of the documents generated by the last view commit
Throws:
CoreException
Since:
1.4 (Carbide 2.0)

registerModel

void registerModel(Model model)
                   throws CoreException
Make a model visible to clients of the provider and manage its contents.

Once registered, the model's owned model is counted as a shared model reference. The caller should release this model eventually.

If the model has a null IDocument, then it will be loaded from storage. Otherwise, it will be persisted immediately from the document contents. Then, the model will be parsed.

The registered model always has a document, though it may be empty if the load failed.

Once registered, changes to the model's document are persisted to underlying storage, and changes to the persisted storage cause reloads of the model.

Parameters:
model - a newly created model
Throws:
java.lang.IllegalArgumentException - if already registered
CoreException - if problems registering model, loading (when existing), or saving contents

unregisterModel

void unregisterModel(Model model)
Make a model invisible to clients of the provider and stop managing its contents. Any pending changes in the view, if committed, will not be automatically persisted, and changes to the persisted storage are no longer tracked.

Parameters:
model - a registered model
Throws:
java.lang.IllegalArgumentException - if not registered

findSharedModel

SharedModel findSharedModel(IPath workspacePath)
Find a registered Model instance for the given path.

The path is used to identify the model and is a key to its real contents (usually the given workspace resource, as implied by the name). The client has limited access to the model. The real work happens through IView.

The model must be released after use.

Parameters:
workspacePath -
Returns:
existing model or null

getSharedModel

SharedModel getSharedModel(IPath workspacePath)
                                          throws CoreException
Load a model for shared use. This is the normal client use of the provider.

This finds a registered model instance. If none registered, it loads a new model instance and registers it, then loads and parse its contents.

If the persisted resource does not exist, a null model is returned.

The client is responsible for releasing the model when done.

The client has limited (read-only) direct access to the model but may create views and make changes through them.

Parameters:
workspacePath -
Returns:
model or null if no such path registered
Throws:
org.eclipse.core.runtime.CoreException - if model cannot be created, e.g. due to a problem loading it when it otherwise appears to exist
CoreException

releaseSharedModel

void releaseSharedModel(SharedModel model)
                        throws java.lang.IllegalStateException
Indicate that the client is no longer using the model, which allows it to be eventually cleaned up.

View created on the model must be disposed first.

Parameters:
model -
Throws:
java.lang.IllegalStateException - if all clients have released the model, but views are still undisposed (this condition is delayed until all clients have released the model, so the last client to release will be blamed :( )

updateModelDocumentMappings

void updateModelDocumentMappings(Model model)
Update tracked files using the map of IPath -> IDocument mappings for the model. These can change as different #includes are detected as a result of different IViewFilters. The provider tracks these documents so that changes to #included files can be saved to disk.


Carbide.c++