Model Roadmap for Logical Model Integration
Here is a list of what model providers can do to take advantage
of the Team logical model support:
- Adapt model elements in model views to ResourceMapping in order to allow resource
based operations to appear on your model elements.
- Register a
ModelProvider to
ensure that your model is consulted when operations are performed on
the resources related to your model.
- Use the
ResourceChangeValidator
when performing operations on resources in order to ensure that any
potential side effects on the model elements related to those resources
are made known to the user.
- Implement an
IResourceMappingMerger
in order to participate in headless merges that involve the resources
related to your model.
- Register a
teamContentProvider in
order to participate in Team viewers such as merge previews.
- Provide an
IHistoryPageSource to show
logical model history in the Team history view.
- Use the
Eclipse File System API
to access the remote state of model projects.
- Use the
SynchronizationStateTester
API to ensure proper decoration of model elements that do not have a
one-to-one mapping to resources.
- Use the
Saveable
API to manage the save life cycle of model elements.)
- Use the
ElementLocalHistoryPageSource
API to show local history for sub-file model elements (e.g. Java methods)
- Use the
ChangeTracker
API to group related changes together.
The following sections describe each of these points in more
detail. The org.eclipse.team.examples.filesystem
plug-in contain an example that illustrate several of these points.
You can check the project out from the CVS repository and use it as
a reference while you are reading this tutorial. Disclaimer: The source
code in the example plug-ins may change over time. To get a copy that matches
what is used in this example, you can check out the project using the 3.3 version
tag (most likely R3_3) or a date tag of June 30, 2007.
Resource Mappings
The Basic Resource Mapping API
The resource mapping API is purposely simple with logical model
manipulations omitted. A client can't use this interface to display
logical models or gain any interesting additional knowledge about it.
It's purpose is simply to map one or more model elements to workspace
resources.
The API consists of the following classes:
-
ResouceMapping:
ResourceMapping
is the Class to which logical model elements adapt to indicate that the
model corresponds to a set of resources in the workspace. The methods
of interest are:
-
Object getModelObject(): The model object from
which the mapping was derived (or adapted).
-
ResourceTraversal[]
getTraversals(ResourceMappingContext, IProgressMonitor): The resource
traversal that cover the resources that constitute the model object.
-
ResourceTraversal: A
ResourceTraversal
contains a set of resources and a depth flag that indicates the depth
to which the resources in the traversal are associated with the
originating model object. Resource traversals are provided to a client
by a resource mapping in order to describe the contents of a model in
such a way that the client (e.g. a repository provider) can perform its
operations in as efficient a means as possible. Methods of interest
are:
-
getResources()
-
getDepth()
-
ResourceMappingContext: A context that is
provided to the resource mapping by the client when obtaining
traversals. This context allows the logical model to determine what the
remote state of the model is so that the proper resources can be
covered by the resource traversals returned by the resource mapping.
The use of the
ResourceMappingContext
and RemoteResourceMappingContext
is a bit more complicated and is described in the Resource Mapping Context section.
There are two types of plugins that should be interested in
resource mappings. Those who provide a model that consists of, or is
persisted in, resources in the workspace and those that want to perform
operations on resources. The former is covered in the next section while
the later is covered in the
RepositoryRoadmap for Logical Model Integration.
Adapting a Model to a ResourceMapping
Plug-ins that adapted their model objects to IResource
in order to get resource specific actions shown in the context menu can
now adapt to ResourceMapping if a richer description of how
the object adapts to resources is beneficial. However, they are not
required to do so if there is no benefit. For instance a Java
compilation unit (i.e. *.java file shown in a JDT view) that now
currently adapts to IFile need not adapt to ResourceMapping
since nothing is gained. However, a Java package should adapt to ResourceMapping
in order to indicate that the package consists of only the files in the
corresponding folder and not the subfolders.
The preferred way to adapt model elements to a resource mapping
is to use an adapter factory. The following is the XML markup for
contributing an adapter factory in a plug-in manifest.
<extension
point="org.eclipse.core.runtime.adapters">
<factory
class="org.eclipse.example.library.logical.AdapterFactory"
adaptableType="org.eclipse.example.library.Book">
<adapter type="org.eclipse.core.resources.mapping.ResourceMapping"/>
</factory>
<factory
class="org.eclipse.example.library.logical.AdapterFactory"
adaptableType="org.eclipse.example.library.Library">
<adapter type="org.eclipse.core.resources.mapping.ResourceMapping"/>
</factory>
...
</extension>
The adapter factory implementation would look something like
this:
public class AdapterFactory implements IAdapterFactory {
public Object getAdapter(Object adaptableObject, Class adapterType) {
if((adaptableObject instanceof EObject) && adapterType == ResourceMapping.class) {
return new EObjectResourceMapping((EObject)adaptableObject);
}
return null;
}
public Class[] getAdapterList() {
return new Class[] {ResourceMapping.class};
}
}
Model objects can implement the IAdaptable
interface. When they do so, they must ensure that the Platform adapter
manager is consulted. This can be done by either subclassing PlatformObject
or by using the following line of code:
Platform.getAdapterManager().getAdapter(Object,
Class)
The above is the preferable approach. However, the model object
can implement the IAdaptable interface and provide a getAdapter(Class)
implementation that creates returns an instance of ResourceMapping
explicitly when asked for one. This is a more straightforward approach
but the least desirable as the model must have explicit knowledge of the
adaptation to resources.
In some cases, the provider of a logical model may not want their
model to adapt to IResource in every context or may want
the object to adapt differently for object contributions than for other
contexts. The workbench UI provides a special intermediate adapter API,
IContributorResourceAdapter, for this purpose. When objects
are being adapted to IResource in the context of object
contributions, the workbench first tries to adapt the resource to IContributorResourceAdapter
before trying to adapt to IResource directly. A new
sub-interface of this interface, IContributorResourceAdapter2,
has been added which provides the same capability for ResourceMapping.
The only difference is that the model provider should register a factory
for IContributorResourceAdapter since the Workbench does an
instanceof check to see if the contributed adapter is also an
instance of IContributorResourceAdapter2.
The implementation of the ResourceMapping subclass
for a Java package would look something like this.
public class JavaPackageResourceMapping extends ResourceMapping {
IPackageFragment package;
...
public getModelObject() {
return package;
}
public ResourceTraversals[] getTraversals(
ResourceMappingContext context,
IProgressMonitor monitor) {
return new ResourceTraversal[] {
new ResourceTraversal(
new IResource[] { package.getCorrespondingResource() },
IResource.DEPTH_ONE, IResource.NONE)
}
}
}
This is a fairly straightforward mapping so the implementation is
not complex. The complexity of the resource mapping implementation will,
of course, vary from model to model.
Resource Mapping Context
One of the advantages of a Resource Mapping API is that it allows
plug-ins to implement any operations they desire in terms of resource
mappings (e.g. CVS update, CVS commit, CVS tag, dirty decoration, etc.).
However, the API that has been introduced so far deals only with the
local state of the model. When working with a model that may be shared
between developers, you end up in a situation where the remote state of
the model (i.e. the state of the model that another user has checked-in
to the repository) may differ from the state in the workspace. If you
performed a CVS update, you would want the local state of the model to
match the remote state even if it meant that additional files needed to
be included or some files needed to be removed.
This is not an issue for some logical models. For instance, a
java package is a container visited to a depth of one, regardless of the
remote state of the model. Given this, a repository provider can easily
determine that outgoing deletions should be included when committing or
that incoming additions should be included when updating. However, the
resources that constitute some logical models may change over time. For
instance, the resources that constitute a model element may depend of
the contents of a manifest file (or some other similar mechanism). In
order for the resource mapping to return the proper traversal, it must
access the remote contents of the manifest file (if it differs from the
local contents) in order to see if there are additional resources that
need to be included. These additional resources may not exist in the
workspace but the repository provider would know how to make sure they
did when the selected action was performed.
In order to support these more complex models, a RemoteResourceMappingContext
can be passed to the ResourceMapping#getTraversals method.
When a context is provided, the mapping can use it to ensure that all
the necessary resources are included in the traversal. If a context is
not provided, the mapping can assume that only the local state is of
interest.
When does a ResourceMapping need to worry about the
RemoteResourceMappingContext?
A ResourceMapping need only worry about a context
supplied to the getTraversals method in cases were the
resources that make up a model change over time and the relationship
between the model and resources cannot be described by a simple
traversal that is guaranteed to encompass those resources (and only
those resources) that constitute the model. For example, although the
resources of a Java package may change over time, the package can be
described as a folder of depth of one so a resource mapping for java
packages would not need to make use of the resource mapping context.
As a more complicated example, consider an HTML file that
contains several images. Let's make the assumption that any images
references from an HTML file are part of the model of that file. When
updating the local contents of the HTML file from a repository, the user
would expect that any new images would be included. The getTraversals
method for a ResourceMapping for the HTML file model would
look something like this:
public class HTMLResourceMapping extends ResourceMapping {
private HTMLFile htmlFile;
public ResourceTraversal[] getTraversals(ResourceMappingContext context,
IProgressMonitor monitor)
IResource[] resources = htmlFile.getResources();
if (context instanceof RemoteResourceMappingContext) {
// Look for any additional resources on the server
RemoteResourceMappingContext remoteContext = (RemoteResourceMappingContext)context;
IFile file = htmlFile.getFile();
if (remoteContext.hasRemoteChange(file, monitor)) {
IStorage storage = remoteContext.fetchRemoteContents(file, monitor);
IResource[] additionalResources = getReferences(storage.getContents());
resources = combine(resources, additionalResources);
}
if (remoteContext.isThreeWay() && remoteContext.hasLocalChange(file, monitor)) {
IStorage storage = remoteContext.fetchBaseContents(file, monitor);
IResource[] additionalResources = getReferences(storage.getContents());
resources = combine(resources, additionalResources);
}
}
return new ResourceTraversal[] {
new ResourceTraversal(resources, IResource.DEPTH_ZERO, IResource.NONE)};
}
}
Notice that there are two sets of resources included in the
model: those derived from the local contents of the HTML file in the
workspace and those obtained from the contents of the remote file and
base file. In either of these two sets, there may be resources that do
not exist in the workspace. For instance, the local HTML file may
contain a relative link to an image that does not exist in the
workspace. This resource should be included so that it will be fetched
if it exists remotely. As for the remote file, it may contain a new copy
that references additional images that should be fetched when the new
remote contents are downloaded.
Model Providers
Model providers are a means to group related resource mappings
together. Here is a link to the ModelProvider
class. This class serves three main purposes:
- From a model provider, clients can then obtain additional API
pieces for performing operations on a set of resource mappings using
the adaptable mechanism. For example, the
IResourceMappingMerger
for the model is obtained by adapting the model provider.
- Given a set of file-system resources, clients can query
whether a model provider has model elements persisted in those
resources and, if it does, obtain the set of resource mappings that
describe the relationship.
- For operations on a set of resources, the resource change
validator will query the model providers in order to determine if there
are any potential side effects of an operation that users should be
made aware of. This is covered in a separate section on change validation.
The following is an example of a modelProvider extension
definition.
<extension
id="modelProvider"
name="Library Example"
point="org.eclipse.core.resources.modelProviders">
<modelProvider
class="org.eclipse.team.examples.library.adapt.LibraryModelProvider"
name="Library Example"/>
<extends-model id="org.eclipse.core.resources.modelProvider"/>
<enablement>
<test property="org.eclipse.core.resources.projectNature"
value="org.eclipse.team.examples.library.view.nature" />
</enablement>
</extension>
The LibraryModelProvider is a subclass of ModelProvider.
The enablement rule is used to match resources that the Library model
persists its model in. In the above example, the model provider will
match any resource in a project that has the library nature.
Once the model provider is defined, the ResourceMapping#getModelProviderId()
method should be overridden to return the id of the model provider.
public String getModelProviderId() {
return "org.eclipse.team.examples.library.adapt.modelProvider";
}
To get the proper inverse mapping of resources to resource
mapping for those resources that match your provider's enablement rule,
you should also override one or both of the getMapping
methods. The method that you need to override depends on whether your
model has elements that contain multiple resources or not. If your model
elements map to a single resource, you can override the method that
accepts a singleIResource argument. Otherwise, you will
need to override the method that accepts an array of resources. Here's
an example using the single resource case.
The following example method wraps a library model file in an
appropriate resource mapping. It also wraps folders that contain files
that are of interest to the model provider.
public class LibraryModelProvider extends ModelProvider {
public ResourceMapping[] getMappings(IResource resource,
ResourceMappingContext context, IProgressMonitor monitor) {
if (isModelFile(resource)) {
// Return a resource mapping on the file
return new LibraryResourceMapping(resource);
} if (containsModelFiles(resource)) {
// Create a deep resource mapping on the container
return new LibraryContainerResourceMapping(resource);
}
// The resource is not of interest to this model provider
return null;
}
}
Clients can then access the model provider to determine whether
the model providers cares about the resources that are about to be
operated on. The next section describes API that will be provided to
team operations that use the model provider API to determine the
complete set of resource mappings to be operated on when a team
operation is performed on a set of selected resources or model elements.
Resource Change Validation
Operations performed on resources should be validated first to
ensure that the user is aware of any potential side effects. Here are the
steps required to validate a resource change.
- Build up a description of the change using the
IResourceChangeDescriptionFactory
.
The factory produces an IResourceDelta that mirrors what
the resulting resource delta will look like once the operation is
performed.
- Validate the change using the
ResourceChangeValidator
.
The validator consults all the model providers that have registered an
interest in the affected resources. The result is one or more status
that contain the id of the originating model and a description of the
potential side effect of the operation on the model.
- Make the user aware of any potential side effects from models
that are unknown to the originator of the operation. For instance, if a
Java refactoring has received a side effect from the Java model, it can
be ignored since the refactoring understands the semantics of the Java
model. However, if a side effect from the Library model is returned, it
should be made known to the user since Java has no knowledge of the
Library model.
Model-based Merging
When a Team provider is attempting a headless merge, it will do
the following:
- Obtain the resource mappings from the selected elements
- Determine the model providers involved using the
ResourceMapping#getModelProvider() method.
- Expand the scope of the operation to include all necessary
resource mappings.
- Build up a description of the synchronization state between
the local and remote. This description is provided to the models
through the IMergeContext
API.
- Adapt the model providers to IResourceMappingMerger.
- Invoke the validateMerge method on each merger, passing in the
synchronization description, to ensure there is not some condition that
should prevent an attempted merge.
- Delegate the merge to the model mergers to perform the merge.
- Model providers can delegate the merge of individual files
back to the Team provider if they only want to control the order of the
merge or may perform the merge themselves and signal to the team
provider when they are done.
Model Content in Team Operation Views
The display of model elements in the context of a Team operation
is made possible by the Common Navigator framework.
The above steps will allow models to appear in dialogs used by
team operations. There are additional steps required to integrate into a
merge preview.
- Adapt the model provider to ISynchronizationCompareAdapter.
This is done to allow the model to open model specific compare editors
on model elements.
- Implement an acti on provider for the navigatorContent
extension as a subclass of SynchronizationActionProvider.
This will allow the model to register merge handlers that will be
invoked when users perform merge operations on the model
provider's elements in the merge preview.
History View
The following improvements have been made in the area of file
history and model element history:
- The History view has been generalized to display the history of
any object that adapts to an IHistoryPageSource.
Thus, model providers can render the history for their logical model
elements.
- An IFileHistoryProvider
API has been added for obtaining and querying the remote history of
workspace files. Logical models can obtain and interpret this history.
- An IHistoryCompareAdapter
is used to hook up the selection in an IHistoryPage to compare editors
so that history pages can be reused in the context of compare
operations.
Remote Browsing
The following has been provided to support remote browsing:
- An Eclipse File System API has been introduced in the
org.eclipse.core.filesystem plug-in.
- API has been added to the ProjectSetCapability to obtain
the URI from project set entries. These URIs can be used to obtain a
FileSystem for the purposes of browsing remote contents.
- Models that require an IResource base project can use the file
system to create a team-private project.
- Methods have been added to the ProjectSetCapability for
loading a URI as a project.
Decorating Model Elements with Team State
Team providers can decorate model elements by converting their
lightweight decorators to work for resource mappings in the same way
object contributions are converted to work for resource mappings.
However, there is one aspect of logical model element decoration that is
problematic. If a model element does not have a one-to-one mapping to a
resource, the model element may not receive a label update when the
underlying resources change.
To address this issue, the
ITeamStateProvider
was introduced in order to give model
providers access to state changes that may affect team decorations. In addition,
model views can use a
SynchronizationStateTester
to determine when the
labels of logical model elements need to be updated. This API relies on
the ITeamStateProvider interface to determine when the team state
of resource has changed and can be passed to a team decorator as part of an
IDecorationContext
.
Using the Saveable API
Logical model providers may use the
Saveable
API to manage the Save lifecycle of their model elements. If they do so,
they should adapt their Saveable instances to a ResourceMapping to ensure that
repository providers (and other tools) can determine which resources would be affected
if the saveable was saved. For instance, this is important in the case where a repository
provider wants to ensure that there are no open dirty editors on a set of resources before a repository
operation is performed.
Showing the history of sub-file elements
The
ElementLocalHistoryPageSource
class can be used by models to show the local history for a sub-file element such as a Java method.
History can be shown in the History view by calling the
TeamUI#showHistory method with the model element
and history page source as arguments. Models that call this also need to provide a subclass of
StructureCreator
as described in the
Advanced compare techniques section.
The history can also be shown in a dialog using the
HistoryPageCompareEditorInput
class. Subclasses can control whether the dialog is to be used for comparison purposes or as a dialog that supports
replacing the current element with an element from the history.
Grouping related changes
Model providers that wish to ensure that changes to sets of resources are committed or checked-in to a repository together
can subclass the
ChangeTracker
class. This class
is used to track local changes and issue requests to the repository provider to group related changes together.
