3D PLM PPR Hub Open Gateway

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.

This use case is intended to be useful in two different cases:

1. You are the owner of a catalog containing a StartUp that you would like to make "public", i.e., allow its derivation by others. In order to protect your catalog from unwanted access, you must provide a factory that creates a new derived StartUp in your client's catalog. Actually, for every "public" StartUp, you will need to provide a corresponding factory.
2. You are a client needing to derive a StartUp existing in a catalog that you do not own. You must use a factory that the owner of the deriving StartUp catalog must have provided allowing you to derive your StartUp in your own catalog.

This use case illustrates the programming steps you must go through for both of the two cases described above: as an owner, how to create the StartUp factory; as a client, how to use the StartUp factory to derive a new StartUp.

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

[Top]

The CAAOsmDerivedSUFactory Use Case

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

[Top]

What Does CAAOsmDerivedSUFactory Do

The goal of CAAOsmDerivedSUFactory is to illustrate creating and working with StartUp factories. It uses the StartUp with type "CAAOsmNovel" found in the catalog created in the CAAOsmCatalogSU use case [2]. Here is an image of the "CAAOsmNovel" StartUp in this catalog:

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

The owner of this catalog creates a factory called CAAOsmCreateNovelSU. The client needing to derive a new StartUp from "CAAOsmNovel" in his own catalog, uses this factory. Here is an image of the "CAAOsmNewNovel" StartUp created through this factory in a client catalog:

Fig.1 CAAOsmFactory.CATfct Catalog - "CAAOsmNewNovel" StartUp

[Top]

How to Launch CAAOsmDerivedSUFactory

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

mkrun -c "CAAOsmMainFactory NewCatalogStoragePathName NewDocumentStoragePathName"

• NewCatalogStoragePathName - the entire storage pathname, name and extension (.CATfct) of the new catalog created.
• NewDocumentStoragePathName - the entire storage pathname, name and extension (.CATPart) of the new document created.

[Top]

Where to Find the CAAOsmDerivedSUFactory Code

The main CAAOsmDerivedSUFactory code is located in the CAAOsmMainFactory.m module of the CAAObjectSpecsModeler.edu framework. It contains a unique source file named CAAOsmMainFactory.cpp. This main calls one global function, CAAOsmCreateDerivedSU, contained in the CAAOsmCreateDerivedSU.cpp source file of the CAAOsmCreateSUByFactory.m module which in turn calls the CAAOsmCreateNovelSU global function (the factory) contained in the CAAOsmCreateFactory.cpp source file of the CAAOsmCreateFactoryServices.m module:

CAAOsmMainFactory.m (CAAOsmMainFactory.cpp) -----> CAAOsmCreateSUByFactory.m (CAAOsmCreateDerivedSU.cpp) ----->

------> CAAOsmCreateFactoryServices.m (CAAOsmCreateFactory.cpp).

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

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

[Top]

Step-by-Step

There are eight logical steps in CAAOsmDerivedSUFactory:

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

We will now comment each of those sections by looking at the code.

[Top]

Create the StartUp Factory

This section comments the code found in the CAAOsmCreateNovelSU global function.

CATUnicodeString stgName("CAAOsmCatalogSU.CATfct");
CATUnicodeString clientId("CAAOsmClientId");

rc = piClientCatalog -> OpenPrereqCatalog (&stgName,
                                           &clientId);

//Process return code error.
if (FAILED(rc))
{
   cout << "ERROR on OpenPrereqCatalog" << endl << flush;
   return rc;
}          

Using the CATICatalog pointer to the client catalog passed as an argument to the factory, the owner catalog is opened using the OpenPrereqCatalog method of CATICatalog. This method takes as input the name of the catalog to be opened and its client identifier. The catalog must be found under the current workspace + "OS" + resources + graphic directory. Remember, this is the catalog created by the CAAOsmCatalogSU use case. If you initially gave it a name other than "CAAOsmCatalogSU.CATfct", copy it, rename it, and make sure it is available in the directory above under the proper name: the CAAOsmCreateNovelSU factory must hard-code this information given that it is not available to the caller.

CATBaseUnknown *pNewSU = NULL;
CATUnicodeString superTypeName("CAAOsmNovel");
rc = piClientCatalog -> CreateSUInCatalog (&pNewSU,
                                           typeName,
	                                  typeName,
				      "CATISpecObject",
				      &superTypeName);
//Process return code error.
...
   
// Return a CATISpecObject pointer to the caller
*piStartUp = (CATISpecObject *) pNewSU;

A new StartUp in the client catalog is created using the CreateSUInCatalog method on the CATICatalog pointer to the client catalog. The method takes the following parameters:

• pNewSU - returned CATBaseUnknown pointer to the new StartUp created.
• typeName - type of the new StartUp created: argument passed to the factory by the client.
• typeName - name of the new StartUp created: by default, the new StartUp has the same name as its type.
• "CATISpecObject" - the interface the StartUp pointer can be cast to.
• superTypeName - the type of the StartUp to derive from: this information is hard-coded in the factory as it is known only to the owner.

The CATBaseUnknown pointer is then cast to a CATISpecObject pointer and returned to the caller who must remember to release it at the end of its use.

[Top]

Create a New Part Document

The code commented in all of the following sections is found in the CAAOsmCreateDerivedSU global function.

CATDocument *pDoc = NULL;
rc = CATDocumentServices::New("Part",
                              pDoc);

//Process return code error.
...	

A new Part document is created using the New method of CATDocumentServices. This is the document that will contain an instance of the new derived StartUp "CAAOsmNewNovel" created with the CAAOsmCreateNovelSU 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:

• catalogStorage - the CATUnicodeString storage pathname, name and .CATfct extension where the catalog will be stored. In this case, the value of catalogStorage comes from pCatStorageName which is passed in as an argument to the function.
• piCatalog - the return CATICatalog pointer to the new catalog created.

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 StartUp Factory to Create the New Derived StartUp

CATUnicodeString newSUType("CAAOsmNewNovel");
CATISpecObject *piNewNovelSU = NULL;

rc = ::CAAOsmCreateNovelSU (&newSUType,
                            piCatalog,
	                   &piNewNovelSU);

//Process return code error. 
...

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

• newSUType - the type of the new StartUp.
• piCatalog - the CATICatalog pointer to the client catalog that will contain the new StartUp.
• piNewNovelSU - the returned CATISpecObject pointer to the new StartUp created.

[Top]

Add a New Attribute to the StartUp

CATUnicodeString copyright("Copyright");
CATISpecAttribute *piCopyright = piNewNovelSU -> AddAttribute(copyright,
	                                                     tk_integer);

//Process return code error. 
...

piCopyright -> Release();

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. 
...	

Client feature objects should always be created in applicative containers. An applicative container is created using the CATCreateApplicativeContainer global function. This function takes as arguments:

• pApplicativeContainer - the pointer that references the new applicative container that is to be created. Its type can be a CATIContainer or a CATIClientContainer, depending on the value of the fourth parameter.
• pDoc - the CATDocument pointer to the current document in which the applicative container will be created.
• idAppliCont - if the value of this argument is not "CATFeatCont", the fifth parameter, the supertype, must be "CATFeatCont". This argument is the type of the container that will be created.
• IID_CATIContainer - the interface IID that this new applicative container will implement.
• iContSU - this is the supertype of the applicative container. If left blank, the idAppliCont argument must be "CATFeatCont". Otherwise, this argument must itself be "CATFeatCont".
• appliContIdentifier - the name of this new applicative container.

See the CAAOsmAppliCont [4] 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 *piNewNovelInst1 = piNewNovelSU -> Instanciate(CATUnicodeString("CAAOsmNewNovel1"),
		                                            pApplicativeContainer);
piNewNovelSU -> Release();
piNewNovelSU = NULL;

pApplicativeContainer -> Release();
pApplicativeContainer = NULL;

//Process return code error. 
...

piNewNovelInst1 -> Release();
piNewNovelInst1 = 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:

• "CAAOsmNewNovel1" - the new name of the feature object. The StartUp type will remain the same for all the features instantiated from it.
• pApplicativeContainer - the pointer to the applicative container in which the new feature object will be created.

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:

• piCatalog - the CATICatalog pointer to the catalog to be saved.

• catalogStorage - the CATUnicodeString pathname, name and .CATfct extension of the catalog to be saved.

[Top]

Epilog

See the referenced article [5] 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 "public" if its owner decides to allow others to derive new StartUps from it. In this case, the StartUp owner must provide a factory to create a new derived StartUp in the client's catalog. The StartUp factory uses the OpenPrereqCatalog method of CATICatalog on the client's catalog in order to open the owner's catalog for derivation purposes. Then, it uses the CreateSUInCatalog method of CATICatalog to actually create the new derived StartUp in the client's catalog. Once the factory has been executed, 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

History

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