Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
The SCA builder is associated to the SCA nature and enables automatic validation of SCA artifacts.
The SCA nature by itself is a property which is associated to projects in the workspace. It is added automatically when you create an SCA Java project using the SCA Tools wizard.
You can also add it manually on any project, by right-clicking on this project and selecting SCA > Add SCA nature.
The SCA builder is activated on any project having the SCA nature.
If you have already used the Eclipse Java Development Tools, you must already be familiar with builders. In a Java project, each time you modify and save java resources, a build is performed and markers appear when the generated classes contain errors. The SCA builder works the same way. Every time an SCA project changes, that a possible SCA resource is modified, the SCA builder performs a build of the project and validates the SCA resources.
The following sections give more details about the SCA builder.
SCA Builder Core
The SCA builder is made up of two big parts: the core, and extensions.
The core deals with the SCA common parts, those that do not deal with specific tools or technologies. As an example, validating java resources inside an SCA application depends on external tools, like the JDT, and therefore, is not part of the SCA builder core. The core relies in a major part on the SCA Composite meta-model. It is then completed by additional parts, but there are few of them.
What does the core validate ?
The SCA builder core validates the following points:
- That composites are valid XML files (covered indirectly by the meta-model).
- Composite structural constraints, like those you could see described in XSD files. The right elements, at the right place. The right attributes, of the right type. This part is covered by the meta-model.
- Additional constraints, as described on the SCA meta-model, e.g. unicity of names, valid URIs for wires and so on. This part is also covered by the meta-model.
- Some constraints can't be handled by the meta-model itself. The builder checks them before loading models with the meta-model. It checks:
- The composite name attribute value is the name of the composite file (deployment constraint defined in the OSOA specifications).
- That the couple of values (composite name, composite target namespace) is unique in the scope of the project. This constraint is required so that composite inclusions can work.
What happens when errors are found ?
When errors are found, the builder creates markers and associate them with the resources which are wrong.
The markers contain a severity (error, warning, information), a message (to help the user to fix it), the source (in which file ?) and some additional information that are not needed here. These markers are visible in the file explorer,
in the "Problems view",
and in most of the editors.
SCA Builder Extensions
Currently, there is only one extension.
It's the Java extension, which aims at validating Java resources from an SCA application.
This extension depends on the JDT. We could easily imagine other tools being used by the builder to validate resources from other kinds.
The Java extension of the SCA builder validates the following points:
- Java interfaces and implementations are in the class path (sources, system libraries, referenced libraries, referenced projects).
- Java resources defined as interfaces in a composite (for services and references) are Java interfaces.
- Java resources defined as implementations in a composite (for components) are Java classes.
- For components having a Java implementation and services with Java interfaces, the implementation must implement all the Java interfaces.
- Promotions and wires linking two elements with Java interfaces must have compatible interfaces (i.e. the interfaces are equals or one extends the other).
How to extend the SCA Builder ?
There are two ways of extending the SCA builder.
- The first one consists in extending the SCA meta-model. It relies on Eclipse EMF, which provides a powerful API to define constraints on meta-models. This is what you should use if you want to validate model parts you contributed (e.g. a binding).
- The second one consists in extensions, like the Java one. These parts are hard-coded and a part of the plug-ins itself. An extension-point should be created after the Galileo release. This is what you should use if you want to add validation relying on other Eclipse tools.
How does it work ?
Let's talk about what happens when one or several SCA resources are modified in an SCA project.
First, let's consider the case of a full build. That's what happen at startup or when you select Project > Clean....
- Remove all the SCA markers.
- Then, the first thing is to build a graph of dependencies between SCA resources. You can have composites included in others, or used as component implementations, and so on. For the moment, this graph is only based on composite files. It should be completed later with implementations, component types and constraining types. The graph is built by going through the project and getting the required identifiers.
- Once the graph is built, a first check is made on all the nodes / vertices.
For each node, it makes sure the composite name and the file name match, and that the (name, tns) is unique in the graph. This step results in a first addition of markers.
- Then, the builder looks for cycles in the depdency graph. Resources in a cycle won't be validated further. A second addition of markers is made.
- After this first selection, the builder has resource candidates to be validated with the EMF meta-model. It also knows which resource should be validated and which ones should not. As an example, included composites should not be validated by the meta-model, because they may not have any meaning before they are included (currently, the meta-model does not handle inclusions). For an example of inclusions, you can look at the OSOA specifications. It contains samples.
- For each node / vertex to validate, the builder tries:
- To load the model. Failure may indicate an invalid XML file.
- Validate the composite element. That's here the EMF validation and the model constraints are called.
- Validate the composite elements with the builder extensions (which mlay have to access to internal resources, e.g. interfaces or implementations).
Each of these sub-steps result in the addition of error markers.
Now, let's consider the case of an incremental build.
That's what happens when you modify a file.
- The modified resources are identified.
- Their SCA markers are deleted.
- There graph nodes are removed and then loaded again.
- Once all the modified resources have been updated in the graph, the graph is completely validated.
When it's not a composite file which is modified, but a Java resource (*.class, .classpath), then a full build is performed.
One thing to signal here, and which is develop on another page, is the notion of SCA signature.
The builder introduced this object to abstract markers from any resource (i.e. file) and technology (e.g. EMF, XML, GMF) representations.
SCA Builder: expected improvements
There are lots of things to improve in the SCA builder.
But an important part of the work is in the SCA meta-model.
- Define an EMF loader API. This part would encapsulate the model laoding part and build the dependency graph. It could be used inside Eclipse and in stand-alone mode. It would find composites, component types, constraining types, implementations data to use, and then build a dependency graph and/or SCA model instances.
- Line numbers should be resolved in SCA XML artifacts. One solution could be to update the EMF XML parser and make it store line numbers. By default, the line number is 0.
- Improve performances: instead of revalidating all the graph, only the modifed nodes and the nodes which depdend on them should be revalidated.
- Provide an extension-point to register builder extensions which depend on other Eclipse tools. The Java extension would be the first concrete client of this extension.