Use Common Data Access in ODA SDKs (Part 2 of 2)

Obtaining hierarchical information

This article describes how to obtain hierarchical information from a Common Data Access tree. For an overview and requirements of Common Data Access, see the first article in this series.

The createDatabaseHierarchyTree function of the OdRxModelHierarchyTreeBase class is used to build a hierarchical tree structure. There are three modes for building a Common Data Access tree:

• Obtaining only the tree structure of the base (this is the fastest).
• Getting the tree structure of bases and a small set of properties that are used, for example, to group and sort objects in a tree.
• Obtaining a full set: a tree and a cache of all node properties.

…
      // pDb - Pointer to the source database object.
      // create_properties_cache - Flag to create cache of properties. Default value is true.
      // class_dependent_hierarchy - Flag to optimize the creation of a hierarchical tree. It can only be set to true if the properties of database objects with a hierarchical attribute are statically dependent on the object type. Default value is false.
      // class_dependent_property - Flag to optimize cache creation. It can be set to true only if all properties of database objects are statically dependent on the object type. Default value is false.
      // Returns a smart pointer to the root node of the hierarchical tree.

    virtual OdRxModelTreeBaseNodePtr createDatabaseHierarchyTree(const OdRxObject* pDb, const bool create_properties_cache = true, 
      const bool class_dependent_hierarchy = false, const bool class_dependent_property = false);

    // pDb - Pointer to the source database object.
    // collected_properties - A pointer to a set of property names that will be added to the cache. If NULL, all properties will be cached.
    // class_dependent_hierarchy - Flag to optimize the creation of a hierarchical tree. It can only be set to true if the properties of database objects with a hierarchical attribute are statically dependent on the object type. Default value is false.
    // class_dependent_property - Flag to optimize cache creation. It can be set to true only if all properties of database objects are statically dependent on the object type. Default value is false.
    // Returns a smart pointer to the root node of the hierarchical tree.

    virtual OdRxModelTreeBaseNodePtr createDatabaseHierarchyTree(const OdRxObject* pDb, const std::set<OdString>* collected_properties, 
      const bool class_dependent_hierarchy = false, const bool class_dependent_property = false);

Parameters class_dependent_hierarchy and class_dependent_property are used to optimize the performance of obtaining hierarchical data. These flags can optimize the performance of methods only in the following cases:

• class_dependent_hierarchy flag — If properties containing a hierarchical attribute are statically dependent on the object type.
• class_dependent_property flag — If all properties of the object statically depend on the object type.

Otherwise, the result is unpredictable.

The following table shows the applicability of flags for various ODA products.

Drawings Drawings (DGN) IFC BimNv BimRv class_dependent_hierarchy + + + + - class_dependent_property + + - + -

Here is an example of obtaining a hierarchical tree with a full set of properties:

OdRxModelHierarchyTreeBasePtr pHierarchyTreeBase = OdRxModelHierarchyTreeBase::createObject();

OdRxModelTreeBaseNodePtr pTree = pHierarchyTreeBase->createDatabaseHierarchyTree(pDb, true);

Where pTree is a pointer to the root node of the hierarchical tree of the base.

OdRxModelTreeBaseNode object

Each OdRxModelTreeBaseNode object in the Common Data Access tree contains the following information:

• Unique node identifier (UniqueID)
• Unique database identifier (UniqueDatabaseID)

UniqueID and UniqueDatabaseID are used to identify a node in the tree. For example, UniqueID is used in Visualize to bind the GiDrawables node and Common Data Access. The unique identifier for the main database (UniqueDatabaseID) is always zero. The unique identifier for nested databases is the address of the corresponding database object. UniqueDatabaseID is filled when creating a Common Data Access tree, when a node element is in a hierarchy with a hierarchical attribute "Database".

Important: Binding GiDrawables and UniqueDatabaseID is only possible during one database session. Otherwise, the result is not guaranteed.

PropertyInfo object

The PropertyInfo structure contains information about the node property. Each element contains the following information:

• Property name
• Localized property name
• UI placement group
• UI placement weight
• Property value
• Array of subproperties

When creating a Common Data Access tree, the property values are filled using the following rules:

• If the property is a reference to RxObject and has OdRxDisplayAsAttribute, an OdRxDisplayAsAttribute value is assigned as the property value.
• If the property value is included in the list of supported types, the corresponding value of this property is assigned.
• In other cases, the value is set to the value returned by OdRxValue::toString().