3D PLM PPR Hub Open Gateway

Adding data to a feature

This article is an advanced article about adding data to a feature. You must know what is a feature and the basic principles of the feature modeler and the object modeler. So to really take advantage of this article you should see the referenced article [1].

The different types of data that you might want to add to a feature:

1. Non Persistent data, those data are not added using "Feature Modeler" APIs, and therefore are not integrated in basic "Feature Modeler" mechanisms such as Data persistence, Undo/Redo, Copy/Paste. They usually are temporary data used to enhance performances.
2. Persistent data, those data are added using "Feature Modeler" APIs. They are integrated in "Feature Modeler" basic mechanisms. They usually are part of the data model and have their own semantic.
3. Behaviors, in object programming adding data is not enough you migh want to add behavior implementing interfaces.
   
4. Extension features, this mechanism allows to add both data and behaviour to a feature (then referenced as the "base feature") through an extension feature.  This way of adding data is more memory consumming but has other advantages.
   

[Top]

Non Persistent Data

Non persistent data can easily be added by creating a "System Data Extension", you can see the Creating Components article [6] to learn more about Data Extension. In this case data and the feature become one entity, they share the same life cycle. We can also imagine to use an external C++ data structure that would only point to features and manage associated data.

As all data model modifications must be supported during the whole lifecycle of the data, it is interesting to add data without impacting the persistency. It's a very easy and safe way to add data. But, it is not integrated with "Feature Modeler" Undo/Redo or Copy/Paste.

[Top]

Persistent data

Once you  have performed some thinking about your data model, you migh want to make it persistent. Beware of this kind of modifications as you should be able to support them during the whole data lifecycle.
Persistent data available are of three kinds:

• Properties, they can be added to a feature with the CATIProperty interface.
• Attributes, they are declared in the feature's StartUp and are manipulated with CATISpecAttrAccess.
• Aggregation is a way of adding data using tk_component attribute declared in the feature's StartUp.
  

Properties

Properties are the easiest way to add basic data on any feature.

Only basic types are supported:

• C++ short type

• C++ unsigned short type

• C++ long type

• C++ unsigned long type

• C++ double type

• C++ unsigned char type (no support of unicode)

Properties support is integrated in Data persistence, Undo/Redo, Copy/Paste. This means that your data will be saved, modifications are kept during run time to allow Undo/Redo operations and finally those data are copied with the feature in case of "Paste as specified".

The Instance Reference mechanism is not supported with Properties. This means that if you instanciate a feature that has properties defined, the properties are not defined on the instance.

See reference article [1] for a detailed description of the Instance Reference concept

Attributes

Attributes are part of a feature description. Attributes are like "slots" attached to feature objects in which data are stored.

The most efficient way to use attribute is to declare them on the feature's StartUp. Attributes not valuated on the instance have no memory cost.

Attributes can also be added dynamically on any instance using the CATISpecObject interface, with this usage memory consumption and performances are not optimal.

Attributes support is integrated in all Feature Modeler mechanisms (Data persistence, Undo/Redo, Copy/Paste,Instance-Reference, ...).

Aggregation

Aggregation is an advanced way of the attribute way of adding data. Some features declare a tk_component attribute which is dedicated to external applications that want to add data on a feature. Aggregating your feature to another make them share the same life cycle.

Behaviors

Behaviors are added by implementing an interface on a feature. If you implement an interface on a StartUp all features of the same type will benefit of this new behavior.

As you cannot overload interfaces already implemented, you must use the provider mechanism. This mechanism is available on a limited number of interfaces, such as: CATINavigateObject , CATI3DGeoVisu , CATIIcon , CATIUIActivate , etc. See the "Using the Provider Mechanism" use case in the PPR/Product section of the CAA documentation encyclopedia. Some behaviors can be reimplemented to overload the behavior.

Extension Features

A feature can be enriched by adding one or several extension features on it. Extension feature allows to add data and behaviors to a feature.

Extensions are objects that are defined in catalogs like StartUps, and also have one additional resource file to describe them. An extension features is added in an applicative container, the applicative container is declared in the ressource file. You can only add one extension of each kind.
They share the same life cycle as the base feature. Which means that the deletion of a base feature leads to the deletion of all the extensions, but the deletion of an extension feature doesn't lead to the base feature deletion. Deleting an extension is done by removing it from the base feature, an extension feature cannot exist without a base feature.
The base feature is copied with its extensions.
As features, extension features are integrated in Undo/Redo mechanism.

Adding and removing extension is performed using the CATIOsmExtendable interface, which is implemented by default on all features. This interface also provides services to retrieve extension features from the base feature. Extension features can retrieve their base feature using the interface CATIOsmExtension.
 

Properties of the extension feature are declared in a ressource file: TheNameOfMyExtensionFeature.CATRsc

You have to declare the container where the extension features will rely once they are added on a base feature.

You have to declare the base features that you want to extend with the extension feature. A ressource file is effective for the concerned extension feature and the extension features that inheritate from it. The extension feature can the extends all declared base features and the features that inheritate from them.

Extension features are defined as "local" by default, this means that if you instanciate a base feature that has been extended, only the extensions that are not "local" are re-instanciated on the base feature instance.

Attributes can be added to the extension feature as other features. Attributes added on extension feature can have quality (sp_IN, sp_OUT, sp_NEUTRAL), these Build/Update characteristics are supported.

Using extension feature is more powerful because it allows you to overload modelization but also heavier than using properties or dynamic attributes. Try to consider those alternative possibilities before using extension feature.

See the CAAOsmCreateExtensions use case [2] to see how to create extension features and the CAAOsmManageExtensions use case [3] for examples showing how feature objects can be extended.

Data

Extension features are features so it is possible to add attributes on them like any other features. It is possible to add several extensions to one base feature.

You cannot add extension features to an extension feature.

See the referenced article [1] for a detailed description of the attributes concept.

Behaviors

Extensions can implement interfaces that can be retrieved  from the base feature through CATIOsmExtendable interface. This interface is implemented by default on all features and has a QueryExtension method that allows to retrieve a pointer on an interface implemented on the extension.

Instance Reference

By default an extension is "local". This mean that the extension it is not re-instanciated when the base feature is re-instanciated.

See the referenced article [1] for a detailed description of the instance reference concept.

Applicative Container

Just above, we have seen that feature extension instances are created inside an applicative container whose the name is defined by the Container keyword in the CATRsc catalog .

ExtensionFeature.Container="CAAOsmApplication2";
...

Who creates this applicative container ? There are two possibilities :

• You want always create yourself the applicative container: in this case AddExtension method of CATIOsmExtendable will fail if the applicative container does not exist in the CATDocument containing the base feature.
• You want benefit feature modeler capabilities: add these 3 lines in the CATRsc file

ExtensionFeature.Container="CAAOsmApplication2"; ExtensionFeature.ContType="CATFeatCont"; ExtensionFeature.ContSuperType="CATFeatCont"; ExtensionFeature.Catalog="CAAOsmExt2Catalog.CATfct"; ...

• ContType is the container type : CATFeatCont or a specific type if you want implement interfaces on this container.
• ContSuperType is the super type of the container : CATFeatCont or a the type of container which directly or not derives from CATFeatCont.
• Catalog is the CATfct name where is defined the feature extension.

In this case, AddExtension method of CATIOsmExtendable will create the applicative container in the same CATDocument as those containing the base feature, if it does not exit.

Consequently, you have noted that by construction, feature extension can only be instantiated inside an applicative container located in the same  CATDocument as those containing the base feature.

Summary of Essential Tasks

[Top]

In Short

Extending a feature is a basic need to customize application but as it's model manipulation it is important to overview the different ways of doing it.

Before adding data you should ask yourself if you want to add persistent data or not and if the data you want to add is going to be added on every instance of the feature. Depending on your issues you must choose the lighter way to add data.

When you add model element such as properties, attributes or extension beware of their naming. The only way to retrieve those elements created on the fly is by using their name. To avoid indeterminism it is mandatory that all those names are unique. One option is to use specific prefixes to name those entity.  See the referenced article [4] for a review of the naming concept.

[Top]

References

History

Copyright © 2005, Dassault Systèmes. All rights reserved.