Catalog Modeler |
Browsing a CatalogUnderstanding the internal catalog structure |
|
| Use Case | ||
AbstractThis use case enables to understand the catalog document structure in displaying its contents. |
In reading the "What You Will learn With this Use case" section of the use case "Creating a Catalog" [1], you learn that a catalog is in the form of a tree structure made up of chapters, families (end chapters), components, descriptions and keywords. This use case is browsing a catalog to retrieve and display all the catalog is made off.
Before getting to the use case itself, it is important to already be familiar with the basic notions of Catalog. See the referenced article [2] for a detailed overview.
[Top]
CAACciCatalogVisualize is a use case of the CAAComponentsCatalogs.edu framework that illustrates ComponentsCatalogsInterfaces framework capabilities.
[Top]
The CAACciCatalogVisualize use case dumps a catalog. It means that it displays:
The output format (right shift at each sub-chapter) enables to understand the tree structure of the chapters.
Here an illustration with the CAATool.catalog created in the use
case CAACciCatalogToolCreation [1].
The CAACciCatalogVisualize main program begins ....
The E:\users\egd\adele\egdmm10\CAAComponentsCatalogs.edu\InputData\CAATool.catalog is opened
The catalog contains 5 chapter(s)
Tools
Nuts
Nuts4SidesFamily
NutsWithFixedSizeHole
Nuts6SidesHole10Family
...
|
...
---Tools (Chapter)
Keyword(s): 2
ToolType; Default value= Unset
Suppliers(*); Default value= Unset
Description's name= Tools.2
Chapter's keyword value
ToolType= Screws
Suppliers= MySupplierA
---------Screws (External Chapter)
Keyword(s): 1
ToolType; Default value= Screw
Description's name= Screws.2
Chapter's keyword value
ToolType= Screw
---------------ScrewsFamily (Family)
Keyword(s): 1
Material; Default value= Iron
Description's name= ScrewsFamily.2
Chapter's keyword value
Material= Iron
Referenced Object's Type= Document
Referenced Object's Name= CAAScrew.CATPart
Part configuration
Description's name= ScrewsFamily.3
Chapter's keyword value
Material= Iron
Referenced Object's Type= Document
Referenced Object's Name= CAAGroovedScrew.CATPart
Part configuration
Description's name= Tools.3
Chapter's keyword value
ToolType= Nuts
Suppliers= MySupplierA
---------Nuts (Chapter)
Keyword(s): 1
SideNumber; Default value= Unset
Description's name= Nuts.2
Chapter's keyword value
SideNumber= 6
---------------Nuts6SidesFamily (External Family)
Keyword(s): 3
PartNumber; Default value= Unset
PartBody\Pad.1\FirstLimit\Length; Default value= Unset
PartBody\Hole.1\Diameter; Default value= Unset
Description's name= Nut20x20
Chapter's keyword value
PartNumber= Nut20x20
PartBody\Pad.1\FirstLimit\Length= 0.02 Meter
PartBody\Hole.1\Diameter= 0.02 Meter
Referenced Object's Type= Document
Referenced Object's Name= Nut20x20.CATPart
Resolved Part configuration
Description's name= Nut30x10
Chapter's keyword value
PartNumber= Nut30x10
PartBody\Pad.1\FirstLimit\Length= 0.03 Meter
PartBody\Hole.1\Diameter= 0.01 Meter
Referenced Object's Type= Document
Referenced Object's Name= Nut30x10.CATPart
Resolved Part configuration
Description's name= Nut40x10
Chapter's keyword value
PartNumber= Nut40x10
PartBody\Pad.1\FirstLimit\Length= 0.04 Meter
PartBody\Hole.1\Diameter= 0.01 Meter
Referenced Object's Type= Document
Referenced Object's Name= Nut40x10.CATPart
Resolved Part configuration
Description's name= Nuts.3
Chapter's keyword value
SideNumber= 4
---------------Nuts4SidesFamily (Family)
Keyword(s): 3
PartNumber; Default value= Unset
PartBody\Pad.1\FirstLimit\Length; Default value= Unset
PartBody\Hole.1\Diameter; Default value= Unset
Description's name= Nut20x20
Chapter's keyword value
PartNumber= Nut20x20
PartBody\Pad.1\FirstLimit\Length= 0.02 Meter
PartBody\Hole.1\Diameter= 0.02 Meter
Referenced Object's Type= Document
Referenced Object's Name= CAANuts4Sides.CATPart
Part configuration
Description's name= Nut20x10
Chapter's keyword value
PartNumber= Nut20x10
PartBody\Pad.1\FirstLimit\Length= 0.02 Meter
PartBody\Hole.1\Diameter= 0.01 Meter
Referenced Object's Type= Document
Referenced Object's Name= CAANuts4Sides.CATPart
Part configuration
Description's name= Nut20x5
Chapter's keyword value
PartNumber= Nut20x5
PartBody\Pad.1\FirstLimit\Length= 0.02 Meter
PartBody\Hole.1\Diameter= 0.005 Meter
Referenced Object's Type= Document
Referenced Object's Name= CAANuts4Sides.CATPart
Part configuration
Description's name= Tools.4
Chapter's keyword value
ToolType= Nuts
Suppliers= MySupplierA
---------NutsWithFixedSizeHole (Chapter)
Description's name= NutsWithFixedSizeHole.2
Chapter's keyword value
---------------Nuts6SidesHole10Family (Family)
Keyword(s): 1
Name; Default value= Unset
Nb Pesistent Query=1
Description's name= Nut30x10
Chapter's keyword value
Name= Nut30x10
Referenced Object's Type= Description
Referenced Object's Name= Nut30x10
Name of its external chapter:Nuts6SidesFamily
Description's name= Nut40x10
Chapter's keyword value
Name= Nut40x10
Referenced Object's Type= Description
Referenced Object's Name= Nut40x10
Name of its external chapter:Nuts6SidesFamily
The CAACciCatalogVisualize main program is ended.
|
[Top]
To launch CAACciCatalogVisualize , you will need to set up the build time environment, then compile the CAACciCatalogVisualize module along with its prerequisites, set up the run time environment, and then execute the use case [3].
mkrun -c CAACciCatalogVisualize InputPath
Where:
InputPath : The path of the catalog to visualize.You can use catalogs located in CAAComponentsCatalogs.edu/InputData
InstallRootDirectory/CAAComponentsCatalogs.edu/InputData
InstallRootDirectory\CAAComponentsCatalogs.edu\InputData where InstallRootDirectory is the directory where the CAA
CD-ROM is installed.
[Top]
The CAACciCatalogVisualize use case is made of two source files located in the CAACciCatalogVisualize.m module of the CAAComponentsCatalogs.edu framework:
| Name of the source file | Function |
| CAACciCatalogVisualizeMain | Main source file |
| CAACciChapterBrowser | Global function to browse a chapter |
depending on operating system you find them :
| Windows | InstallRootDirectory\CAAComponentsCatalogs.edu\CAACciCatalogVisualize.m\ |
| Unix | InstallRootDirectory/CAAComponentsCatalogs.edu/CAACciCatalogVisualize.m/ |
where InstallRootDirectory is the directory where the CAA CD-ROM
is installed.
[Top]
In the CAACciCatalogVisualizeMain.cpp file you have four mains steps
In the CAACciCatalogChapterBrowser.cpp file, which contains the CAABrowsingChapter
recursive global function to browse a chapter , there is two main steps:
[Top]
...
CATDocument * pDocument = NULL ;
rc = CATDocumentServices::Open(CatalogPath.CastToCharPtr(), pDocument);
...
CATInit *pInitOnDoc = NULL ;
rc = pDocument->QueryInterface(IID_CATInit,(void **) &pInitOnDoc);
...
CATIContainer *pIRootCont = NULL ;
pIRootCont = (CATIContainer*)pInitOnDoc->GetRootContainer("CATIContainer");
...
CATICatalogChapterFactory * pICatalogChapterFactory = NULL ;
rc = pIRootCont->QueryInterface(IID_CATICatalogChapterFactory,
(void **) &pICatalogChapterFactory);
...
|
CatalogPath is a CATUnicodeString initialized with the
first argument of the CAACciCatalogVisualize main, so the complete name of the
catalog to dump.
The root container of a catalog document implements the CATICatalogChapterFactory interface. As usual you retrieve the root container of a document thanks to the CATInit interface.
Before to dump the catalog, it is interesting to list the chapters of the catalog.
... CATListValCATICatalogChapter_var * ListOfChapter = NULL ; rc = pICatalogChapterFactory->ListChapters(ListOfChapter); ... |
pICatalogChapterFactory is the CATICatalogChapterFactory
interface pointer previously retrieved. The ListChapters method
retrieves the list of the chapters of the CURRENT catalog. It means that this
method doesn't retrieve the eventually external chapters pointed by a
description [Fig.1].
...
CATICatalogChapter * pICatalogChapter = NULL ;
rc = pICatalogChapterFactory->GetRootChapter(pICatalogChapter) ;
...
CATUnicodeString TypeChapter = "Chapter" ;
if ( TRUE == pICatalogChapter->KindIsEndChapter() )
{
TypeChapter = "Family" ;
}
...
|
The root chapter is the first chapter created in the catalog. This chapter,
retrieved by the GetRootChapter, can be a end chapter, but it is
not recommended.
... rc = ::CAABrowsingChapter(pICatalogChapter,TypeChapter, 3); ... |
The catalog will be recursively browsed from the root chapter.
pICatalogChapter is the CATICatalogChapter interface pointer on the root
chapter. The last argument indicates the space's number to display the chapters
tree. [Fig. 2]
We are inside the CAABrowsingChapter
global function. pICatalogChapter is the CATICatalogChapter
interface pointer on the chapter to dump, the first argument of this function.
... CATUnicodeString ChapterName ; ChapterName = pICatalogChapter->GetChapterName(); ... |
...
CATListValCATICatalogKeyword_var * pListKeyword = NULL ;
rc = pICatalogChapter->ListKeywords(pListKeyword);
int SizeKWList = 0 ;
if ( SUCCEEDED(rc) && (NULL != pListKeyword) )
{
SizeKWList = pListKeyword->Size();
...
for ( int i=1 ; i<= SizeKWList; i++)
{
CATICatalogKeyword_var CurrentKeyword ((*pListKeyword)[i]);
if ( NULL_var != CurrentKeyword )
{
CATUnicodeString KWName = CurrentKeyword->GetKeywordName();
if ( TRUE == CurrentKeyword->GetHidden() )
{
KWName += "(*)";
}
CATUnicodeString DefaultValue ;
CATBoolean IsDefaultValue = pICatalogChapter->GetDefaultValue(KWName,DefaultValue);
if ( FALSE == IsDefaultValue ) DefaultValue = "Unset" ;
...
}
}
}
...
|
The list of keyword of the chapter is retrieved thanks to the ListKeywords
method applied to pICatalogChapter the CATICatalogChapter
interface pointer on the chapter.
The name of the keyword is given by the GetKeywordName method
applied to the CATICatalogKeyword
interface pointer on the keyword.
The default value of a keyword is given by the chapter thanks to the GetDefaultValue
method applied to pICatalogChapter the CATICatalogChapter
interface pointer on the chapter. If this method returns false, there is no
default value, otherwise the value is returned by the second argument of
the method.
...
CATListValCATICatalogPersistentQuery_var * pListPersistentQuery = NULL ;
rc = pICatalogChapter->ListPersistentQuery(pListPersistentQuery);
if ( SUCCEEDED(rc) && (NULL !=pListPersistentQuery) )
{
int NbPQ = pListPersistentQuery->Size();
}
...
|
Each chapter can contain persistent queries even if it is strongly recommended to set a persistent query to a end chapter and only one for each end chapter. Refer to the "Creating a Persistent Query" article [4] for more details about persistent queries.
...
CATListValCATICatalogDescription_var * pListDescription = NULL ;
rc = pICatalogChapter->ListDescriptions(pListDescription);
if ( SUCCEEDED(rc) && (NULL != pListDescription) )
{
int SizeDescList = pListDescription->Size();
...
CATICatalogDescription_var CurrentDescription ((*pListDescription)[i]);
...
|
Each chapter contains a list of descriptions. For each element of the list,
pListDescription, an analyze of its contents is done in the
following sections.
...
rc = CurrentDescription->GetName(DescriptionName) ;
...
|
...
for ( int j= 1 ; j <= SizeKWList ; j++ )
{
CATICatalogKeyword_var CurrentKeyword ((*pListKeyword)[j]);
CATUnicodeString value ;
CATUnicodeString KWName = CurrentKeyword->GetKeywordName();
rc = CurrentDescription->GetValue(KWName,value);
...
if ( SUCCEEDED(rc) )
{
cout << "= " << value.CastToCharPtr() << endl;
}else cout << "= Unset" << endl;
}
...
|
The keywords of a description are the keywords defined on its chapter.
pListKeyword is the list of keywords of the current chapter retrieving
at the "The Keywords of the Chapters"
step.
On each description you retrieve the value of a keyword thanks to the GetValue
method. The first argument of the method, KWName, is the name of
the keyword. Notice that when there is no value on the keyword (Unset), the GetValue
method returns E_FAIL.
...
CATBaseUnknown * pReferencedObject = NULL ;
rc = CurrentDescription->GetObject(pReferencedObject);
...
|
...
if ( CurrentDescription->IsObjectASubchapter() )
{
...
|
The IsObjectASubchapter method is the easiest way to
determine is the referenced object is a chapter or not.
We are in case where the IsObjectASubchapter method returns TRUE.
To retrieve the pointed chapter the easiest way is to use the GetSubChapter
method on the description.
... CATICatalogChapter * pChapter = NULL ; pChapter = CurrentDescription->GetSubChapter(); ... |
The
GetObject method doesn't retrieve the pointed chapter but a
temporary object, a QueryResult object. See the technical article
"Catalog Overview" [2]
for details about this object.
Before to call a recursive method on the new chapter, pChapter,
we make some verifications.
The first verification consists in to define if it is a end chapter or not.
The KindIsEndChapter method retrieves this information.
...
CATUnicodeString sTypeOfChapter ;
sTypeOfChapter = "Chapter" ;
CATBoolean EndChapter ;
EndChapter = pChapter ->KindIsEndChapter() ;
if ( TRUE == EndChapter )
{
sTypeOfChapter = "Family" ;
}
...
|
The second verification consists in to define if it is an
external chapter for its parent chapter. To resolve this question, you
must retrieve the CATILinkableObject interface pointer on the
current description and itself. Thanks to this interface
and its method GetDocument you can compare the associated
document.
...
CATILinkableObject * pLinkObjectOnChapter = NULL ;
rc = pChapter->QueryInterface(IID_CATILinkableObject,
(void **) & pLinkObjectOnChapter);
if ( SUCCEEDED(rc) )
{
CATILinkableObject * pLinkObjectOnDescription = NULL ;
rc = CurrentDescription->QueryInterface(IID_CATILinkableObject,
(void **) & pLinkObjectOnDescription);
if ( SUCCEEDED(rc) )
{
CATDocument *pDocOnDescription = pLinkObjectOnDescription->GetDocument();
CATDocument *pDocOnPointedChapter = pLinkObjectOnChapter->GetDocument();
if ( pDocOnDescription != pDocOnPointedChapter )
{
sTypeOfChapter = "External " + sTypeOfChapter ;
...
|
pLinkObjectOnDescription is the CATILinkableObject
interface pointer on the current description and pLinkObjectOnChapter
is the same interface pointer on the pointed chapter. The GetDocument
method returns the document (a CATDocument pointer) which contains
the object which implements the CATILinkableObject interface. It is
possible to test the CATDocument pointer because during a session
this pointer is always the same.
At last we can browse the pointed chapter. The global function CAABrowsingChapter browses the pChapter
whose the type is sTypeOfChapter and with a shift for the cout.
...
::CAABrowsingChapter(pChapter,sTypeOfChapter,MoveTxt+6) ;
...
|
We are in case where the IsObjectASubchapter method
returns FALSE.
The type of the description is retrieved thanks the GetDescriptionType
method on the CATICatalogDescription interface pointer.
![]()
GetDescriptionType
is valid only for descriptions with reference a component and not a chapter.
...
CATUnicodeString sTypeOfTheDescription ;
CATICatalogDescription::CATCatalogDescriptionType TypeOfTheDescription ;
CurrentDescription->GetDescriptionType(TypeOfTheDescription);
if (TypeOfTheDescription == CATICatalogDescription::CATCatalogFeature)
sTypeOfTheDescription = "Feature";
else if (TypeOfTheDescription == CATICatalogDescription::CATCatalogDescription)
sTypeOfTheDescription = "Description";
else if (TypeOfTheDescription == CATICatalogDescription::CATCatalogDocument)
sTypeOfTheDescription = "Document";
...
...
|
The name of the referenced object can be obtained with the CATIAlias interface.
...
CATIAlias * pIAlias = NULL ;
rc = pReferencedObject->QueryInterface(IID_CATIAlias,(void **) & pIAlias);
if ( SUCCEEDED(rc) )
{
CATUnicodeString Identifier;
Identifier = pIAlias->GetAlias() ;
...
}
...
|
In case of a description containing a link towards a description, the referenced object implements the CATICatalogDescription interface. Such descriptions are obtained when a persistent query is associated (and resolved) with a chapter. The referenced object is the description from an another catalog. Refer to the "Creating a Persistent Query" article [4] for more details about persistent query.
...
if ( TypeOfTheDescription == CATICatalogDescription::CATCatalogDescription )
{
CATICatalogDescription * pIPointedDesc = NULL ;
rc = pReferencedObject->QueryInterface(IID_CATICatalogDescription,
(void**) &pIPointedDesc);
if ( SUCCEEDED(rc) )
{
CATICatalogChapter * pExternalChapter = NULL ;
rc = pIPointedDesc->GetChapter(pExternalChapter);
if ( SUCCEEDED(rc) )
{
...
pExternalChapter->Release();
pExternalChapter = NULL ;
}
pIPointedDesc->Release();
pIPointedDesc = NULL ;
}
}
...
|
In case of a description containing a link towards a document, the referenced object implements at least the CATInit interface because it is a document.
...
if (TypeOfTheDescription == CATICatalogDescription::CATCatalogDocument)
{
CATInit * pIInitOnPointedDesc = NULL ;
rc = pReferencedObject->QueryInterface(IID_CATInit,
(void**) &pIInitOnPointedDesc);
if ( SUCCEEDED(rc) )
{
pIInitOnPointedDesc->Release();
pIInitOnPointedDesc = NULL ;
int value ;
CurrentDescription->IsResolvedObjectComputed(value) ;
...
if ( value == 1 )
{
cout <<"Resolved Part configuration" << endl;
}else
{
cout <<"Part configuration" << endl;
}
}
}
...
|
The IsResolvedObjectComputed enables to know if the description
references a resolved document or not. To be resolved two cases:
[Top]
This use case enables to understand the catalog structure in analyzing the description's content and in detailing the data (keyword) linked to the chapter.
[Top]
| Version: 1 [Jul 2002] | Document created |
| [Top] | |
Copyright © 2002, Dassault Systèmes. All rights reserved.