Modeling StartUps |
| Technical Article |
AbstractApplications 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. |
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
statement is one of:identifier names the corresponding object (a
catalog, a container or a feature).#number.
These suffixes appear when the OSM is generated from a catalog and should
not be altered.[super_identifier] is also an identifier,
designating the feature from which this feature is derived or instantiated.
It is optional and is not present on every statement.[facets...] are optional qualifiers that change the
statement defaults. They are prefixed with the sharpsign character (#)body represents in turn one or more OSM statementscomments follow the C++ convention: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
}
}
}
|
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 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.
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:
#isa facet (see below), but this is not recommended as this
introduces confusion.MyCatalog.CATfct would be MyCatalogNLS.CATNls
and resides in the resources/msgcatalog directory. The contents
of this file are simply lines of the form:identifier="localized name of identifer";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.
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.
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_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 {
...
}
...
}
|
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.
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
}
}
}
|
Point2D with two attributes: x and y
(double)Point3D inheriting from Point2D, with two
attribuets: z (double) and coordinates (a
list of double)Line3D with 3 attributes: start, end
(features) and length (double). start and
end are specs while length is a resultpoint0 and point1, instantiated from
Point3D and initialized to (0.,0.,0). and (1.,1.,1.) respectivelyline instantaited from Line3D and initialized
with point0 and point1In this article, we have detailed the OSM language that is used to describe catalogs and their contents: feature startups and feature objects.
| [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 |
| Version: 1 [Aug 2007] | Document created |