Modeling StartUps

Technical Article

Abstract

Applications create feature objects by instantiating feature startups stored in catalogs. This article covers the OSM language that is used to define catalogs and their contents including feature startups.

The OSM Language

You should be familiar with the fundamentals of the Feature Modeler as outlined in the Feature Modeler Concepts [1] before reading this article.

The purpose of the OSM language is to describe the contents of catalogs since it is where feature startups get stored and accessed. An OSM statement has the following syntax:

statement identifier [super_identifier] [facets..] {
        body
        /* a comment */
        // another comment
} 

where

To give you a feeling of the OSM language, here is a complete example. It is fully commented in the A Catalog Example section.

document `MyCatalog.CATfct` {
        container CATFeatCont #root {
                /* Point2D startup */
                feature Point2D #startup {
                        double x
                        double y
                }
                /* Point3D startup deriving from Point2d */
                feature Point3D Point2D #startup {
                        double z
                        double #list coordinates
                }
                /* Line3D startup */
                feature Line3D #startup {
                        specobject start #in  // start point
                        specobject end #in    // end point
                        double length #out    // length
                }
        }
} 

The document Statement

Because an OSM file describes the contents of a catalog, it always consists of one document statement that names the resulting catalog. The CATfct file extension of the catalog name must be included. Since the identifier rule does not allow a dot (.), catalog names must be enclosed in backquotes (`).

There is no facet applicable to a document.

document `MyCatalog.CATFct' {
        ...
} 

The name given to the catalog must abide by the CAA Naming Rules [5], because all the catalogs will share the same directory in the run-time view [4] which is resources/graphic.

The body of a document is simply a container which is described in the next section.

The container Statement

The container statement describes the contents of a container in a catalog. There can only be one root container in each catalog. The only facet that applicable to the container statement is always specified: #root.

container CATFeatCont #root {
        ...
}

 The body of the container statement contains one or more feature statments and optionally one or more external_link_meta_data statements.

The feature Statement

A feature object is described by the feature statement. Feature startups and feature extensions are also defined by the same statement but with their specific facets. The format of the feature statement is:

feature identifier [super_identifier] [facets..] {
        attribute_definitions
        [attribute_initializations]
}

If the name given to the feature identifier, must be chosen carefully:

super_identifer designates the feature from which this one must be derived or instantiated, like "Point2D" in the following example

feature Point3D Point2D #startup {
        ...

If the super_identifer resides in another catalog, it must be specified with the @`other_catalog.CATfct` or @`other_catalog.feat` (DS feature) notation:

feature Point3D Point2D @`2DCatalog.CATfct` #startup {
        ...

Note that catalogs are always specified with only their names, without any directory. This is because they are supposed to be present in a specific directory of the run-time view [4].

There are many facets for the feature statement:

Facet Meaning
#startup defines a Feature StartUp from which features can be instantiated
#extension defines a Feature Extension, to be used in conjunction with #startup
#inheritability(caa) indicates a derivable feature, i.e. used as supertype by other feature definitions
#isa(late_type) specifies that the late type is late_type instead of the feature identifier. Its usage is not recommended

The body of a feature statement contains the definition of the feature's attributes and optionally their initial values. We will not cover the attribute definition and initlization.

 

Attribute Definition

There is no specific statement to define the attributes. Each attribute definition is of the form:

attribute_type attribute_name [facets]

The following table lists the possible values for an attribute_type (OSM type column ), the corresponding data type in C++ (C++ type column) and the corresponding enum value that is used in the Feature Modeler APIs (CATAttrKind colum):

OSM type C++ type CATAttrKind
Enum
Description
string char * tk_string character string
double double tk_double double precision floating point
boolean CATBoolean tk_boolean boolean
octet unsigned char tk_octet unsigned 8 bit value
int int tk_integer signed 32 bit integer
specobject N/A tk_specobject "referenced" link
component tk_component "aggregated" link
external tk_external "external" link

An attribute definition can have facets:

Facet Meaning
#list the attribute holds not single value but a list (the corresponding CATAttrKind value is tk_list)
#in the attribute is a Spec  
#out the attribute is a Result
#neutral the attribute is neither a Spec or a Result
#external_link_meta_data(name) define link metadata for this external attribute: name refers to an external_link_meta_data block where the link metadata is defined

The order of the attribute definition is not kept and should be not relied on.

Attribute Initialization

The attribute can be initialized with a value with a statement of the form:

attribute_name=value

value is specified as constants, with list written using square brackets and commas: [1,2,...]:

OSM type Example of Value
string "a string", ["a", "list", "of", "strings"]
double 314.16e-2, 2.007
boolean true, false
octet 255
int 1, 2, 3
specobject feature_identifier
component
external

The attributes that have feature objects as value (specobject, component and external) are initialized using feature object identifiers. The following example shows a "Line3D" feature object being initialized with two "Point3D" feature objects, point0 and point1:

...
feature point0 Point3D {
        x=0
        y=0
        z=0
}
feature point1 Point3D {
        x=1
        y=1
        z=1
}
feature line Line3D {
        start=point0
        end=point0
}
...

In the above example, all feature objects belong to the same catalog. The @`other_catalog.CATfct` notation can be used if a feature object resides in another catalog.

The order of the attribute initializations is not important with respect to the attribute definitions.

The meta_data_definition Statement

The meta_data_defintion statement appears at the same level as the container statement. It defines a block consisting of only external_link_meta_data statements where link metadata are defined and referred to by #external_link_meta_data facets in attribute defnitions.

meta_data_definition {
        external_link_meta_data name1 {
                ...
        }
        ...
}

The external_link_meta_data Statement

This statement which can only appear inside a meta_data_definition block, defines the metadata of an external link.

meta_data_definition and external_link_meta_data are statement used for next version.

A Commented Catalog Example

Here is an example of a complete catalog definition:

document `MyCatalog.CATfct` {
        container CATFeatCont #root {
                /* Point2D startup */
                feature Point2D #startup {
                        double x
                        double y
                }
                /* Point3D startup deriving from Point2d */
                feature Point3D Point2D #startup {
                        double z
                        double #list coordinates
                }
                /* Line3D startup */
                feature Line3D #startup {
                        specobject start #in // start point
                        specobject end #in   // end point
                        double length #out   // length
                }
                /* Create a point at the origin */
                feature point0 Point3D {
                        x=0.
                        y=0.
                        z=0.
                }
                /* Create point1 at (1,1,1) */
                feature point1 Point3D {
                        x=1.
                        y=1.
                        z=1.
                        coordinates=[1.,1.,1.]
                }
                feature line Line3D {
                        start=point0
                        end=point0
                }
        }
} 

In Short

In this article, we have detailed the OSM language that is used to describe catalogs and their contents: feature startups and feature objects.

References

[1] Feature Modeler Concepts
[3] Getting Started with Your Own Features
[4] Understanding Feature StartUp Catalogs
[5] CAA Naming Rules
[6] CAA C++ Naming Rules

History

Version: 1 [Aug 2007] Document created