STP Core Overview Documentation

STP Core API [Index]

The STP Core API is an EMF-based model with several enhancements. The SCA standard is honored by the model, but there are some abstractions which are not directly dictated by the specification, but are useful in the context of developing a tool for the development of specification-compliant applications. These enhancements include a common base type, the abstraction of concepts such as Composite, WireSource and WireTarget, and cleaner method signatures for the manipulation of substitutable XML types (such as interface or binding).

org.eclipse.stp.core.sca.SCAObject

The base type for the SCA model, SCAObject provides capabilities that all SCA model objects can take advantage of. First, it provides standard facilities for associating org.eclipse.core.IStatus objects with a given model object. Thus, an invalid model element does not have to prevent the complete loading of the document. SCAObject also insulates the STP Core API from the standard EMF base interface (EObject), which is exposed only through SCAObject.getEObject(). This helps to keep the API on each SCA object clean and focused, but allows editors or advanced operations to take advantage of the many useful facilities of EObject when necessary. Finally, a bitmask of flags can be associated with each SCAObject, in order to keep track of characteristics of an object in a standard and extensible way.

In the diagram, SCAObject is shown as the common parent of the key model elements. Some model elements were filtered for clarity. The Composite type, which is not explicit in the SCA specification will be discussed below.

Useful Abstractions

There are several abstractions which were found useful when describing the SCA specification for a tooling-centric model.

Composite:

Provides a common base type for ModuleFragment and Subsystem. A Composite describes a collection of Components EntryPoints, and ExternalServices. It also provides a base where WireSource/WireTargets may be resolved.

AbstractService:

Exposes an Interface and provides a method to determine if it matches (or is compatible with) an AbstractReference.

AbstractReference:

Provides the same information as AbstractService but from the view point of a reference.

WireSource:

In SCA, either an EntryPoint or a Reference of a particular Component may be the source of an embedded wire. To make client code more reusable, each of these types provide a WireSource abstraction; EntryPoint extends WireSource directly, while Component provides an implementation which describes a particular Reference on the Component.

WireTarget:

Provides the opposite functionality of WireSource; ExternalService extends this type directly, while Component provides an implementation which describes a particular Service on the Component.

EMF, XML Substitution Groups, and FeatureMaps, OH MY!

In EMF, XML Substitution Groups are managed by a special EMF data structure named FeatureMap. This type associates a particular EMF feature (e.g. the global document element from the XML Schema) with a particular instance which subclasses the substituable type indicate in the XML Schema declaration. With a few restrictions, the STP Core API was able to automatically manage the FeatureMap, and expose more friendly schemes for clients who wish to add substituted types (e.g. JavaInterface) to their respective fields (e.g. Service.set/getInterface).

Generating the STP Core API from the standard schemas [Top]

The STP Core API cannot be generated from scratch due to the modifications and enhancements. However, it can be regenerated to integrate updates from the specification. This process uses an extensible stylesheet transformation (XSLT) to convert the Standard SCA schemas to a form which will generate certain additive abstractions (like Composite), and also annotates the generated schemas with Ecore annotations to make the generation a little cleaner (by hiding some fields, renaming others, etc).