3D PLM PPR Hub Open Gateway |
Feature Modeler |
Deriving New StartUps Using a Generic FactoryWorking with public StartUps |
Use Case |
AbstractThis 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. |
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]
CAAOsmGenericDerivedSUFactory is a use case of the CAAObjectSpecsModeler.edu framework that illustrates ObjectSpecsModeler framework capabilities.
[Top]
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:
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]
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]
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]
There are seven logical steps in CAAOsmGenericDerivedSUFactory:
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]
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]
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]
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:
The derived StartUp can be a StartUp created just before the current one
- See the cpp file for an example: Just after the CAAOsmNewAdd
StartUp creation, the CAAOsmNewAdd_deriv
StartUp deriving from
CAAOsmNewAdd has been created.
[Top]
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]
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]
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:
piCatalog - the CATICatalog pointer to the catalog to be saved.
catalogStorage - the CATUnicodeString pathname, name and .CATfct extension of the catalog to be saved.
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]
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]
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]
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.