IModelProvider (Carbide.c++ SDK API Reference)
Keywords: com.nokia.carbide.cpp.epoc.engine.model.IModelProvider interface

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Carbide.c++
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Carbide.c++
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD