This document tries to capture the issues that are related to integrating logical models into the Eclipse Platform. This is a reiteration of what was captured here but tries to present the set of model characteristics of interest along with related scenarios. The focus is not on defining a general API for logical models. Instead, the focus is on identifying those points in the Platform that degrade the user experience when working with logical models and identifying possible solutions to these issues. The focus is also on those issues that involve maintaining model consistency both locally and remotely in a repository.
First we will describe some of the different model characteristics that we have seen in various modeling tools built on top of Eclipse. Then we will describe several scenarios and how they relate to these model characteristics. The scenarios contain descriptions of what the ideal workflows could be without considering the viability of making these a reality.
This section describes several different model characteristics that are common in model tooling. This list is general and it is most likely that real models will have a combination of these characteristics.
The most straightforward relationship between model elements and file system resources is a one-to-one mapping. That is, a model element maps directly to a file system resources. An example of this is a Java class (or compilation unit) which maps directly to the file that contains the class.
It is often the case that a single file will contain multiple model elements. A simple example of this is a Java file that contains multiple compilation units or classes. Usually, a file contains a single class but multiple classes in the same file is supported. In this case, classes that appear in Java views will still correspond to a single file but performing operations that are resource based, such as repository operations, on the class will include all classes contained in the file in the operation.
In some models, a model element may consist of a fixed set of files. We will use an example from the Eclipse plug-in structure. When developing plug-ins,
These two files are tied together in the sense that they are really one entity that is stored in two files (in reality, there are other files that are thus linked to the plugin.xml file but we'll only use two files to keep it simple).
Another example of a fixed relationship is a Java package which consists of all the direct file children of the package folder. That is, sub-folders of the package folder (which model sub-packages) and the files that are contained in those sub-folders are not part of the Java package.
In some tools, several files are related to a single model object through a map file or interfile references. For a simple case, consider
An additional restriction may be that the names of some or all of the files have a common string in the file name (e.g. A).
In some cases, it is possible to have a model that doesn't necessarily contain certain files but cannot be reasonably rendered without them. An example of this is a diagram that described the relationship between a set a Java classes. The diagram will contain layout information and perhaps even some class relationship information but will not likely duplicate information found in the classes themselves, such as method signatures. If one or more of the classes in the diagram were not available, it may not be possible to render portions of the diagram.
In some cases, a model may be persisted in several file system resources where each file is meaningless on its own. An example would be a large diagram that is divided into files but cannot be rendered if one of the files is missing. This is similar to the fixed or variable relationship cases but has the added characteristic that operations should never be performed on the file-system resources individually.
It is often the case that there are many model layers involved in a product. Consider this layering:
Each of these models is built on top of the lower layer (i.e. layer 2 is built on top of layer 1, etc.). It is also true that the higher layers may be built on top of several lower level model layers. We commonly refer to the mapping of model elements to files as logical-to-physical mapping. We will refer to mapping from one logical model to another as logical-to-logical mapping.
It is worth mentioning the case where a model is not persisted in local files but is instead persisted in some other location (e.g. a database). Some of the scenarios that will be mentioned below are still relevant to this case (e.g. problem reporting).
This section covers various scenarios, work flows or use cases that can potentially have an effect on the consistency of a model. There are basically two methods of maintaining model consistency:
Ensuring that all the operations performed on a model will maintain model consistency is fairly straight forward when operations are launched from the tooling associated with the model in question. However, it is often the case that operations are performed on the elements of lower level models directly. For instance, a user who edits the plugin.properties file directly may remove an entry that is still referenced by the plugin.xml file. Or, in the layered model case, a user may delete a Java file that is contained in a model element of a higher level model. These types of changes lead to a greater chance of models becoming inconsistent.
The work flows in the section are related back to the model characteristics described previously with descriptions of what currently occurs as well as what would be the desirable behavior. The statement of the desirable behavior is by no means a statement of the viability of such a solution. It is only something to shoot for.
Currently in Eclipse, dealing with model inconsistencies is mainly done using problem reporting. However, the mechanisms provided by Eclipse (build, markers, Problems view) are highly file system centric. This makes the reporting of problems difficult as they are always associated with file system resources. This has several shortcomings:
Ideally, the Problems view should display problems that are associated with any model element, whether it be a file-system resource or an element of a higher level model. Furthermore, the ability to group related problems together using a tree view or some other type of grouping mechanism would be helpful when the user is presented with a lot of problems that are really all symptoms of one larger problem.
The following sub-sections present specific problem reporting scenarios.
Consider the case where a model element is persisted in at least one file which is XML. If that file cannot be parsed, the XML parser will create a problem marker that contains a description of the parse error. Here are some scenarios related to this type of problem:
Another case to consider is when model elements contain references to other model elements (M.4, M.5). Changes to a model element may cause references to become stale. That is, a referenced element could be removed or modified in such a way as to make any references to the element no longer valid. With the current Problems view, a problem could be associated with the location in the file where the reference appears. If the stale reference appears multiple times, then multiple markers could be created. However, providing a link to the position in the file where the link appears may not be enough to help the user to decide how to fix the problem. Also, the user would need to fix the problem in each location it appeared.
Ideally, a single problem item should identify the existence of the stale reference. This would allow the user to see the single cause of the multiple stale references. It may still be desirable to associate problems with each of the elements that contain stale references and also with each particular occurrence of a stale reference but the user should only need to see the specific locations if they decided to deal with each occurrence individually.
Models that are not persisted in files (M.8) may still have model consistencies problem that should appear in the problems view. Currently, problems cannot be associated with logical model elements that do not have a corresponding resource unless the model tooling has it's own problems view. Having multiple views that serve the same purpose is confusing for users.
The Problems view currently has the ability to filter by selection. This only works when the items in the selection have a one-to-one mapping to file system resources. Ideally, the following would be supported:
With this support, the user could select any element in the UI and see what problems existed for that element.
Many of the scenarios presented previously involve layered models. However, it is worthwhile to mention specific instances of how model layering affects problem reporting. The user will often work at a particular model level and will therefore like to see problems stated in such a way that is consistent with that layer. Thus is would be desirable to be able to:
In this section we look at various operations and their effect on model consistency.
First, lets look at what happens when a file that is part of a model element is renamed. The following conditions will result in model inconsistencies that need to be corrected.
The currently supported solution for all these cases is for a builder to recognize the inconsistency and place a problem marker on an appropriate file. The model tooling could associate a QuickFix with the problem that would allow the user to correct the problem in a single operation (as opposed to renaming all the necessary files one-by-one) but that is the best they could do.
Ideally, the model tooling would want some or all of these abilities:
File deletion is similar to the rename case with some additional considerations:
The effects on model consistency are harder to determine on folder (or project) deletion, simply because there are potentially many files being renamed or deleted. It is possible that many file references may become stale upon folder deletion but it is just as likely that all the files contained in or referenced by the model were all contained in the same folder so deleting that folder may introduce no inconsistencies.
There are two cases of interest when looking at file content modification.
For operation participation, the following list of issues arise when model layering is considered:
Some things to consider here are:
It is also interesting to note that Java refactorings support certain types of participation (create, delete, move and rename).
Although not technically a model consistency issue, opening an editor is similar to performing other operations. Here are a few cases involving logical models that impact the opening of editors.
When working with logical models, the user would like to be able to select logical model elements that appear in Eclipse and perform repository operations on them. However, repository tooling tends to be file based so a conversion from the model space to the file system resource space is required. We have introduced API in 3.1 M5 that supports the mapping of logical elements to their underlying file system resources. As of 3.1 M5, the following is support:
The following sections highlight issues that still exist.
There are some cases where a model may want to participate in repository operations for the purpose of augmenting the list of model elements or file system resources that are being operated on. Examples of when this may be necessary are:
The repository tooling may also need to obtain additional input from the user. Although the operation is being performed on file system resources, the relationship between the resources and the originating model should be made obvious to the user.
One of the more complicated scenarios involving repository operations is that of merging remote changes with local changes. Eclipse has API which supports model based merging for the one-to-one case (M.1). This API could also be used to handle the many-to-one case (M.2). However, there is currently no mechanism for performing an atomic merge on a model element that contains multiple files. What would be required in this case is API between the model tooling and repository provider in order to reconcile the logical model to the physical model when performing repository operations such as merging.
One potential complication is that a merge operation may involve model elements form different model layers or from different model tooling. Either there would need to be a single merge mechanisms that was capable of performing merges on multiple models simultaneously or the merges would need to be sequences. The former case is more desirable than the later from a usability standpoint.
Decorating elements that appear in the UI with their state relative to the repository provides valuable feedback to the user in some cases. One such case is a dirty decorator that, when present, indicates that the element has changed locally since the time it was loaded from the repository.
A related issue is that of bootstrapping. In other words, how does a user load model elements that were created by other users. To do this, a root access point is required. In Eclipse, the project acts as this root. Therefore, the user must first load a project and can then access the model elements it contains. In the cases where models span projects, Team projects sets can be used to bootstrap a workspace.
There are a couple of issues involving the use of project sets in this way:
One simple means of addressing this may be to support the grouping projects together in a way that ensured that if one got loaded from a repository, they all got loaded.
The required support for the scenarios presented in this document can be broken down into three separate features:
Although there is some overlap between these features, they can each be addressed as separate issues.