3D PLM PPR Hub Open Gateway

Feature Modeler

Creating Feature Extensions

Creating new feature extensions in catalogs

Use Case

Abstract

This article discusses the CAAOsmCreateExtensions use case. This use case explains how to create feature extensions in catalogs.

What You Will Learn With This Use Case
The CAAOsmCreateExtensions Use Case
Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to help you understand how to create feature extensions in catalogs.

Before getting to the use case itself, you should have on one hand a good understanding of the feature modeler [1] , and the extension feature concepts [2] on the other hand.

Once you have created the feature extension, you can read the article entitled "Working with Feature Extensions" [3] which explains how to add ,query and remove extensions on a base feature.

[Top]

The CAAOsmCreateExtensions Use Case

CAAOsmCreateExtensions is a use case of the CAAObjectSpecsModeler.edu framework that illustrates ObjectSpecsModeler framework capabilities.

[Top]

What Does CAAOsmCreateExtensions Do

The goal of CAAOsmCreateExtensions is to illustrate creating feature extensions. This use case calls a global function called CAAOsmCreateExtInCatalog which creates two new catalogs. Each catalog contains a different set of feature extensions. Here is an image of the contents of the first extensions catalog:

Fig.1 CAAOsmExt1.CATfct Catalog

And here is an image of the contents of the second extensions catalog:

Fig.2 CAAOsmExt2.CATfct Catalog

[Top]

How to Launch CAAOsmCreateExtensions

To launch CAAOsmCreateExtensions, you will need to set up the build time environment, then compile CAAOsmCreateExtensions along with its prerequisites, set up the run time environment, and then execute the use case. This is fully described in the referenced article [4]. To launch the use case, execute the following command:

mkrun -c "CAAOsmMainCreateExt ExtCatalog1 ExtCatalog2"

ExtCatalog1 - the entire storage path, name and .CATfct suffix of the first new extensions catalog that will be created.
ExtCatalog2 - the entire storage path, name and .CATfct suffix of the second new extensions catalog that will be created.

Note: It is not necessary to locate the newly catalogs in the CNext/resources/graphic directory of the CAAObjectSpecsModeler.edu framework, since there have been already provided.

[Top]

Where to Find the CAAOsmCreateExtensions Code

The main CAAOsmCreateExtensions code is located in the CAAOsmMainCreateExt.m module of the CAAObjectSpecsModeler.edu framework. It contains a unique source file named CAAOsmMainExtensions.cpp. This main calls one global function: CAAOsmCreateExtInCatalog, contained in the CAAOsmCreateExtInCatalog.cpp source file found in the CAAOsmCreateExtensions.m module. Here is the installation path, depending on the operating system:

Windows	`InstallRootDirectory\CAAObjectSpecsModeler.edu\CAAOsmMainCreateExt.m and CAAOsmCreateExtensions.m`
Unix	`InstallRootDirectory/CAAObjectSpecsModeler.edu/CAAOsmMainCreateExt.m and CAAOsmCreateExtensions.m`

where InstallRootDirectory is the root directory of your CAA V5 installation.

[Top]

Step-by-Step

Two extensions catalogs are created in this use case. Since they are created in the same way, only the creation of the first is shown below. There are seven logical steps in CAAOsmCreateExtensions:

Creating the Extensions Catalog
Assigning a Client Id to the Catalog
Creating Extensions in the Catalog
Adding Attributes to the Extension
Valuating the Attributes of an Extension
Saving the Extensions Catalog
Creating CATRsc files

We will now comment each of these sections by looking at the code. The code itself is found in the CAAOsmCreateExtInCatalog function called by the main program.

[Top]

Creating the Extensions Catalog

...
CATICatalog *piCatalog = NULL;
CATUnicodeString extensionsCatalog = pExtensionsCatalog1Name;
	
rc = ::CreateCatalog(&extensionsCatalog, 
	            &piCatalog);

...

The extensions catalog is a regular .CATfct feature catalog. It is created using the CreateCatalog global function. The first argument to this function, the catalog storage name, is passed to the function by the first argument. The second argument is the CATICatalog pointer on the new catalog created.

[Top]

Assigning a Client Id to the Catalog

...
CATUnicodeString clientId("CAAOsmClientId1");
rc = piCatalog -> SetClientId(&clientId);
...

The catalog is uniquely identified using the SetClientId method of CATICatalog. This identification is necessary in order to open the catalog later on. This identifier should remain unique to this particular catalog.

[Top]

Creating Extensions in the Catalog

...
CATIOsmExtensionFactory *piFactoryOnCatalog = NULL;
rc = piCatalog -> QueryInterface(IID_CATIOsmExtensionFactory,
	                        (void**) &piFactoryOnCatalog);

const char *pHistExt = "CAAOsmHistoricalNovel";
CATIOsmExtension*piHistExt = NULL;
rc = piFactoryOnCatalog -> CreateExtension (pHistExt,
                                            NULL,
                                            piHistExt);

...

A new extension is created using the CreateExtension method of CATIOsmExtensionFactory. First, obviously, it is necessary to get a pointer to CATIOsmExtensionFactory from the CATICatalog pointer to the new catalog using QueryInterface. The CreateExtension method takes the following arguments:

pHistExt - the name of the new extension
NULL - the deriving extension name: an extension can only derive from another extension. In this case, the extension does not derive.
piHistExt - the returned CATIOsmExtension pointer to the new extension created.

[Top]

Adding Attributes to the Extension

CATISpecObject *piSpecOnHistExt = NULL;
rc = piHistExt -> QueryInterface(IID_CATISpecObject,
	                        (void**) &piSpecOnHistExt);
... 

CATUnicodeString epoch("Epoch");
CATISpecAttribute *piHistEpoch = piSpecOnHistExt -> AddAttribute(epoch,
                                                                 tk_string);
...

Attributes are added to extensions exactly the same as to StartUps or regular features using the AddAttribute method of CATISpecObject. A pointer to CATISpecObject is obtained from the CATIOsmExension pointer (piHistExt) returned by CreateExtension.

[Top]

Valuating the Attributes of an Extension

CATISpecAttrAccess *piSpecAttrAccessOnHistExt = NULL;
rc = piSpecOnHistExt -> QueryInterface(IID_CATISpecAttrAccess,
	                              (void**) &piSpecAttrAccessOnHistExt);
... 

CATISpecAttrKey *piKeyEpoch = piSpecAttrAccessOnHistExt -> GetAttrKey("Epoch");

... 
	
piSpecAttrAccessOnHistExt -> SetString(piKeyEpoch,
                                       "Middle Ages");
...

In order to valuate an attribute, it is first necessary to access its attribute key using the GetAttrKey of CATISpecAttrAccess. Then, using the Set... methods, in this case SetString, the attribute can be assigned a value.

The second extension, "CAAOsmBiographicalNovel", is created exactly the same as the first, except that it derives from the first. This is done by specifying the name of the first extension in the second argument of CreateExtension.

[Top]

Saving the Extensions Catalog

rc = ::SaveCatalog(&piCatalog,
                   &extensionsCatalog);
...

To save a catalog document, use the SaveCatalog global function which takes as arguments the CATICatalog pointer of the new catalog and the entire storage path and name of the new catalog.

Creating CATRsc files

The last step consists in to create a CATRsc file for each extension StartUp. The resource files are located in the CNext/resources/msgcatalog directory of the CAAObjectSpecsModeler.edu framework. The name of the CATRsc file is the name of the extension (the first argument of the CreateExtensionmethod). This file consists in to declare the extention usage.

The CAAOsmHistoricalNovel.CATRsc file

ExtensionFeature.IsLocal="TRUE";
ExtensionFeature.Extends="CAAOsmNovel";
ExtensionFeature.Container="CAAOsmApplication1";

The CAAOsmBiographicalNovel .CATRsc file

ExtensionFeature.IsLocal="TRUE";
ExtensionFeature.Extends="CAAOsmNovel";
ExtensionFeature.Container="CAAOsmApplication1";

The CAAOsmChildrensNovel .CATRsc file

ExtensionFeature.IsLocal="TRUE";
ExtensionFeature.Extends="CAAOsmNovel";
ExtensionFeature.Container="CAAOsmApplication2";

The CATRsc file for an extension contains the followink keys:

Key Type	Value Key	Explanation
ExtensionFeature.IsLocal	TRUE	It means that the extension it is not re-instanciated when the base feature is re-instanciated.
ExtensionFeature.IsLocal	FALSE	It means that the extension is re-instanciated when base feature is re-instanciated.
ExtensionFeature.Extends	Base feature type	A feature extension can only extend one and only one base feature
ExtensionFeature.Container	Applicative container name	A feature extension can be added to a base feature only in one and only one applicative container.

[Top]

In Short

An extension is created in a regular feature catalog (.CATfct) using the CreateExtension method of the CATIOsmExtensionFactory interface. As for normal StartUps, the AddAttribute method of CATISpecObject is used on extensions to further define their data structure. Likewise, the GetAttrKey and Set... methods of CATISpecAttrAccess are used to valuate attributes. The general SaveCatalog global function is used to save the extensions catalog.

Do not forget to provide a CATRsc file to declare the usage of the feature extension:

Its base feature type to extend,
if it is a local or not feature extension,
The target applicative container name.

[Top]

References

[1]	Feature Modeler Conceptual Overview
[2]	How to Add Data to a Feature
[3]	Working with Feature Extensions
[4]	Building and Launching a CAA V5 Use Case
[Top]

History

Version: 1 [Feb 2000]	Document created
Version: 2 [Feb 2005]	Document updated for new interface
[Top]