3D PLM PPR Hub Open Gateway

Feature Modeler

Deriving New StartUps Using a Generic Factory

Working with public StartUps

Use Case

Abstract

This article discusses the CAAOsmGenericDerivedSUFactory use case. This use case explains how to create a new StartUp in your own catalog deriving from a publicly-declared StartUp found in another catalog.


What You Will Learn With This Use Case

As you may remember, StartUps are always created in catalogs. Catalogs are identified by unique client id's in order to protect them from unwanted access. Only the owner of a catalog has the ability to open the catalog and access the StartUps contained in it. Therefore, if you want to derive a new StartUp from a StartUp existing in a catalog that you do not own, you must either use a factory provided by the catalog owner which is useful when you do not know the name of the catalog or of the deriving StartUp, or you can use the generic factory provided by the feature modeler. This use case illustrates the usage of the generic factory. See the "Deriving New StartUps Using Provided Factories" use case [1] for a detailed explanation of creating and using a specific factory provided by the catalog owner.

 In order to use the feature modeler's generic factory, however, it is assumed that the StartUp you are trying to derive from has been declared "public" and "derivable" in the .CATSpecs file corresponding to the catalog containing it. This declaration must have been made by the catalog owner. See the "Managing Public Features and Attributes" use case [2] for a detailed explanation of how to create and update the .CATSpecs file. You will find  documentation on all Dassault Systemes public and derivable StartUps under the Quick Reference section for each modeler.

Before getting to the use case itself, you should have a good understanding of the feature modeler. [3].

[Top]

The CAAOsmGenericDerivedSUFactory Use Case

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

[Top]

What Does CAAOsmGenericDerivedSUFactory Do

The goal of CAAOsmGenericDerivedSUFactory is to illustrate using the generic StartUp factory called CATOsmSUFactory provided by the feature modeler. It uses the StartUp with type "CAAOsmAdd" found in the catalog created in the CAAOsmCatalogSU use case [4]. Here is an image of the "CAAOsmAdd" StartUp's data structure in this catalog:

Fig.1 CAAOsmCatalogSU.CATfct Catalog - "CAAOsmAdd" StartUp

In the CAAOsmCatalogSU use case, the "CAAOsmAdd" StartUp was declared in the CAAOsmCatalogSU.CATSpecs declarative file as being "public" and "derivable". Its derivation is, therefore, authorized. In this use case, a new StartUp called "CAAOsmNewAdd" derived from "CAAOsmAdd" is created in a new catalog by using the CATOsmSUFactory global function. Here is an image of the new StartUp in the new catalog:

Fig.2 CAAOsmGenericFactory.CATfct Catalog - "CAAOsmNewAdd" StartUp

Note that the new StartUp has inherited all of the attributes of its parent and that it has added one of its own attributes ("Third"). The new StartUp was also specified as being "public" and "derivable". A corresponding .CATSpecs file containing an entry for this new StartUp was, therefore, automatically created as well. Here is an image of this declarative file:

Fig.3 CAAOsmGenericFactory.CATSpecs - "CAAOsmNewAdd" StartUp

<?xml version='1.0' encoding='ISO-8859-1' ?>

<!--Important: use only CAA API to modify this file!-->

<CATSpecs>

<StartUp Type = "CAAOsmNewAdd" Derivable = "TRUE"/>

</CATSpecs>

 

[Top]

How to Launch CAAOsmGenericDerivedSUFactory

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

mkrun -c "CAAOsmMainGenericFactory NewCatalogStoragePathName NewDocumentStoragePathName"

[Top]

Where to Find the CAAOsmGenericDerivedSUFactory Code

The main CAAOsmGenericDerivedSUFactory code is located in the CAAOsmMainGenericFactory.m module of the CAAObjectSpecsModeler.edu framework. It contains a unique source file named CAAOsmMainGenericFactory.cpp. This main calls one global function, CAAOsmCreateGenericDerivedSU, contained in the CAAOsmCreateGenericDerivedSU.cpp source file of the CAAOsmCreateSUByGenericFactory.m module: 

CAAOsmMainGenericFactory.m (CAAOsmMainGenericFactory.cpp) -----> CAAOsmCreateSUByGenericFactory.m (CAAOsmCreateGenericDerivedSU.cpp) 

Here is the installation path, depending on the operating system:

Windows InstallRootDirectory\CAAObjectSpecsModeler.edu\CAAOsmMainGenericFactory.m and CAAOsmCreateSUByGenericFactory.m
Unix InstallRootDirectory/CAAObjectSpecsModeler.edu/CAAOsmMainGenericFactory.m and CAAOsmCreateSUByGenericFactory.m

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

[Top]

Step-by-Step

There are seven logical steps in CAAOsmGenericDerivedSUFactory:

  1. Create a New Product Document
  2. Create the Catalog for the New Derived StartUp
  3. Use the Generic StartUp Factory to Create the New Derived StartUp
  4. Add a New Attribute to the StartUp
  5. Instantiate the StartUp in the Part Document
  6. Save the New Catalog
  7. Epilog

We will now comment each of those sections by looking at the code. The code commented in all of the following sections is found in the CAAOsmCreateGenericDerivedSU global function.

[Top]

Create a New Product Document

CATDocument *pDoc = NULL;
rc = CATDocumentServices::New("Product",
                              pDoc);
//Process return code error.
...	

A new Product document is created using the New method of CATDocumentServices. This is the document that will contain an instance of the new derived StartUp "CAAOsmNewAdd" created with the CATOsmSUFactory generic factory.

[Top]

Create a Catalog for the New Derived StartUp

1. Create the catalog.

CATICatalog *piCatalog = NULL;
CATUnicodeString catalogStorage = pCatStorageName;
rc = ::CreateCatalog(&catalogStorage, 
                     &piCatalog);
//Process return code error. 
...   

A new catalog is created using the CreateCatalog global function. This function takes two arguments:

2. Assign a client identifier to the catalog.

CATUnicodeString clientId("CAAOsmNewClientId");
rc = piCatalog -> SetClientId(&clientId);
//Process return code error. 
...

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

[Top]

Use the Generic StartUp Factory to Create the New Derived StartUp

CATUnicodeString newSUType("CAAOsmNewAdd");
CATISpecObject *piNewAddSU = NULL;
CATUnicodeString superType("CAAOsmAdd");
CATUnicodeString catalog("CAAOsmCatalogSU");
CATBoolean publicSU = TRUE;
CATBoolean derivableSU = TRUE;
	
rc = ::CATOsmSUFactory (&piNewAddSU,
                        &newSUType,
		        piCatalog,
                        &superType,
			&catalog,
			publicSU,
			derivableSU);

//Process return code error. 
...

The new derived StartUp is created using the CATOsmSUFactory generic factory. This factory takes the following arguments:

[Top]

Add a New Attribute to the StartUp

CATUnicodeString third("Third");
CATISpecAttribute *piThird = piNewAddSU -> AddAttribute(third,
		                                        tk_integer);
//Process return code error. 
...   

Now that the StartUp has been created, it can be enriched with new attributes over and above those inherited from its parent StartUp. This is done using the AddAttribute method on the CATISpecObject pointer returned by the factory.

[Top]

Instantiate the StartUp in the Part Document

1. Create a new applicative container for the new feature object.

CATIdent idAppliCont = "CATFeatCont";
CATIdent iContSU = NULL;

CATUnicodeString appliContIdentifier("CAAOsmSUCont");
CATBaseUnknown *pApplicativeContainer = NULL;
rc = ::CATCreateApplicativeContainer(&pApplicativeContainer,   // appli cont created
                                     pDoc,                     // document  
                                     idAppliCont,              // type of appli cont
				     IID_CATIContainer,        // interface type of appli cont
				     iContSU,                  // supertype of appli cont 
				     appliContIdentifier);     // name of appli cont
//Process return code error. 
...	

In this use case, we want to create a new feature in an applicative container. Therefore, the applicative container must first be created using the CATCreateApplicativeContainer global function. This function takes as arguments:

See the CAAOsmAppliCont [6] use case for a more detailed description of this service (CATCreateApplicativeContainer) in interactive context.

2. Instantiate the StartUp as a new feature object in the applicative container.

CATISpecObject *piNewAddInst1 = piNewAddSU -> Instanciate(CATUnicodeString("CAAOsmNewAdd1"),
		                                          pApplicativeContainer);
piNewAddSU -> Release();
piNewAddSU = NULL;

pApplicativeContainer -> Release();
pApplicativeContainer = NULL;

//Process return code error. 
...   

piNewAddInst1 -> Release();
piNewAddInst1 = NULL;

To create a new feature object in the applicative container by instantiating the StartUp created above, use the Instanciate method of CATISpecObject on the StartUp pointer returned by the factory. This method takes the following arguments:

Don't forget to release all pointers that will no longer be used.

[Top]

Save the New Catalog

rc = ::SaveCatalog(&piCatalog,
		   &catalogStorage);
piCatalog -> Release();
piCatalog = NULL;
//Process return code error. 
...    

A catalog is saved using the SaveCatalog global function. This function takes the following arguments:

Note that whenever the "publicSU" argument of the CATOsmSUFactory generic factory is set to TRUE, the new StartUp created is "public" and an entry in the corresponding .CATSpecs declarative file is automatically made. This declarative file is automatically saved at the same time as the catalog and in the same file directory.

[Top]

Epilog

See the referenced article [7] for a detailed description of the steps to go through when saving the document.

Note that the opened catalog documents do not need to be removed from the session.

[Top]


In Short

A StartUp is declared as "public" and "derivable" if its owner has authorized others to derive new StartUps from it. In this case, a generic factory called CATOsmSUFactory provided by the feature modeler can be used to create the new, derived StartUp. Once the factory has been executed and the new StartUp created in the client's catalog, the client can work with the StartUp in order to enrich it by adding new attributes using the AddAttribute method of CATISpecObject, or by instantiating it in an applicative container of his working document using the Instanciate method of CATISpecObject.

[Top]


References

[1] Deriving New StartUps Using Provided Factories
[2] Managing Public Features and Attributes
[3] Feature Modeler Conceptual Overview
[4] Creating StartUps in Catalogs
[5] Building and Launching a CAA V5 Use Case
[6] Creating Features in an Applicative Container
[7] Creating a New Document
[Top]

History

Version: 1 [Feb 2002] Document created
Version: 2 [Sep 2003] Update to add a link to the "Creating Features in an App. Cont." article 
[Top]

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