Model Management

From DocR21

The ENTITY class provides basic model management functionality common to all persistent objects in an ACIS model. In this context model management refers to the functionality necessary to create and maintain a valid ACIS model. This includes capabilities to undo and redo modeling operations, recover from exceptions, identify objects, create and delete models, save and restore models, copy models, debug models, and track changes in models.

Contents 1 The History Mechanism 2 Construction and Destruction 3 Identifying 4 Saving and Restoring 5 Copying 6 Debugging 7 Scanning 8 Tracking Model Changes 9 Persistent Identifiers 10 See Also

The History Mechanism

The ACIS history mechanism maintains a record of the "history" of every ENTITY in an ACIS model. That is, it records every creation, deletion, and change of every ENTITY. This enables ACIS to capture the state of the model after every modeling operation. This mechanism also allows the model to be quickly rolled back to a previous state, and it allows a model that has been rolled back to a earlier state to be rolled forward to a later state. This functionality is exposed to applications, allowing them to implement undo and redo capabilities.

The history mechanism serves a more fundamental purpose in ACIS than just allowing applications to implement undo and redo capabilities: it allows ACIS to recover from exceptions. In the event of an error (or a user interrupt) the ACIS model can be rolled back to a known valid state. This capability is vital to maintaining a valid data structure. Facilities exist to allow an application to attempt a procedure and, if that procedure fails, to roll back changes to the model and attempt an alternate procedure. It is also possible to create failsafe operations. That is, an operation can encounter an error while processing one data element and still continue operate on other data elements. The ACIS history mechanism allows an application to control the granularity of operations and sub-operations captured by the history mechanism, which enables an application to roll back parts of an operation, entire operations, or a series of operations. The history mechanism also allows different portions of the model to be in different history streams, which allows these different portions of the model to be rolled independently.

The history mechanism provides yet another important piece of functionality: it allows an application to traverse or search the changes made to a model during an operation. This enables an application to determine what ENTITYs were created, deleted, or changed during any operation.

In addition, the data structure underlying the history mechanism can be saved to and restored from a file. This allows the history of a model to persist from one session to another.

For more information on the History Mechanism, refer to History and Roll.

Construction and Destruction

ENTITYs are always constructed on the heap. If ACIS free lists are enabled, ENTITYs are constructed on a free list. ENTITYs are generally constructed by higher level modeling operations; however, if they are constructed through the Direct Interface they should be constructed using the ACIS_NEW macro. (Refer to Managing Application Memory for more information on the use of the ACIS_NEW macro.) When an ENTITY is constructed history information will be constructed and maintained by the history mechanism. This behavior is inherited by all classes derived from the ENTITY class.

Because ENTITYs are maintained by the history mechanism, ENTITYs are typically not directly destructed by an application (for instance, by the ACIS_DELETE macro). Instead, ENTITYs are lost by calling ENTITY::lose(). The lose method records in the history stream that the ENTITY is no longer valid, rather than destructing the ENTITY. Some types of ENTITYs (for instance, Model Geometry ENTITYs) are use-counted. These ENTITYs should be removed (by calling ENTITY::remove()), not lost. Typically, Model Geometry ENTITYs are automatically removed when all of the topological ENTITYs that own them are lost. Thus, most applications do not need to lose or remove Model Geometry ENTITYs that are owned by topological ENTITYs. In fact, most applications do not directly lose any individual ENTITYs. Instead most applications lose a set of connected ENTITYs by calling api_del_entity, which loses the given ENTITY and everything connected to it. For example, if an application needed to lose a BODY and everything in it, the application would call api_del_entity with a pointer to the BODY as an argument. This would lose all the topology, geometry, and attributes associated with the BODY. Alternatively, the application could call api_delent, which loses the given topological ENTITY and all subsidiary ENTITYs. The difference in the behaviors of api_del_entity and api_delent are more significant when losing a lower level topological ENTITY, for instance a FACE within a BODY: api_del_entity would lose everything in the BODY; whereas api_delent would lose only the FACE and the data structure below it.

Identifying

Each ENTITY has an identity method to allow applications and ACIS to inquire about its type. In addition, there is a global function called is_<class> for every class derived from ENTITY. For more information on Identifying ENTITYs, refer to Identifying Model Objects.

Saving and Restoring

An ENTITY and all of the ENTITYs connected to it can be saved to or restored from a file. For instance, a BODY and all of its lower level topology and geometry can be saved to a file. ACIS also supports saving to and restoring from a custom output or input stream. ENTITYs can be saved with or without their history information, and ENTITYs can be saved in either a textual or binary format.

For more information on Saving and Restoring ENTITYs, including descriptions of API functions for Saving and Restoring, refer to SAT Save and Restore.

Copying

In addition to being saved and restored, an ENTITY and all of the ENTITYs connected to it can be copied. Alternatively, it is possible to copy only an ENTITY and all of its subsidiary ENTITYs. As an example, given a pointer to one FACE in a BODY, it is possible to copy the entire BODY or just the FACE and the ENTITYs below it. An application can also choose to perform a shallow copy, in which data may be shared between the original ENTITYs and the copies, or a deep copy, in which no data is shared between the original ENTITYs and the copies. Deep copies are typically used with multiple history streams.

For more information on Copying ENTITYs, including descriptions of API functions for Copying, refer to Copying Objects.

Debugging

Application developers often need to query an ACIS model to understand the behavior or results of an operation. ACIS provides functions that allow a developer to inquire about a specific ENTITY, a set of connected ENTITYs, or obtain a summary of the numbers and types of ENTITYs. The most commonly used functions for debugging ACIS models are:

• ENTITY::debug_ent(FILE* fp) – Prints debug information for an ENTITY.
• debug_entity – Prints debug information for an ENTITY and all of its subsidiary ENTITYs.
• debug_size – Prints the size of an entity and all its subsidiary entities. In addition prints the number of each type of subsidiary entity.

For more information, refer to ENTITY Class Debug Method or Debug File.

Scanning

Deleting, saving, copying, and debugging ACIS models share a common piece of functionality: they all must scan an ACIS model. In general, scanning is a process by which the caller can determine what entities are "reachable" from a given entity. Typically, when an entity is scanned, it simply adds everything it can reach to the scan list; however, depending on the SCAN_TYPE, it may be that some of the entities within reach are excluded. For instance, when performing a down copy, ENTITYs above a given ENTITY are not added to the scan list. Refer to the following descriptions of each SCAN_TYPE to review how each is used.

• SCAN_COPY – The default scan used by ENTITY::copy_scan. This type of scan adds any parents, children, siblings, or attributes (if they are copyable) to the scan list, if they are not already in the list. This type of scan is used by api_copy_entity, api_copy_body, and api_copy_entity_list.
• SCAN_DEEP_COPY – This type of scan is used by api_deep_copy_entity and api_deep_copy_entity_list. This type of scan is similar to a SCAN_COPY, except it requires attributes to be deepcopyable and it tells low-level geometry objects to copy themselves instead of increasing their use count.
• SCAN_DELETE – This type of scan is used by api_del_entity and api_del_entity_list. This type of scan adds any parents, children, siblings, or attributes to the scan list, if they are not already in the list.
• SCAN_DISTRIBUTE – This type of scan finds everything connected to the given ENTITY. It is used by the history mechanism to find everything connected to an ENTITY. This type of scan is similar to a SCAN_DELETE, except it adds ENTITYs that are not normally scanned, such as ANNOTATIONS.
• SCAN_DOWN – This type of scan is used to scan down a topology hierarchy, excluding siblings of a starting entity. This type of scan adds only children to the scan list, if they are not already in the list. It does not add parents, siblings, or attributes. It is used by api_down_copy_entity and api_deep_down_copy_entity.
• SCAN_PATTERN – The type of scan is used when creating a new pattern element. The scan will not add topological or geometrical ENTITYs to the scan list if they do not belong to the pattern element being scanned.
• SCAN_PATTERN_DOWN – This scan is similar to SCAN_PATTERN, except it does not scan parents or siblings.

These SCAN_TYPEs allow a single scanning mechanism to be used by a variety of algorithms. The scanning mechanism is an integral part of the ENTITY class.

Tracking Model Changes

Many applications need to monitor changes to the ACIS model. There are three primary mechanisms for tracking changes in the ACIS model:

• Using the history mechanism, as described above in The History Mechanism,
• Attaching attributes to ENTITYs of interest and using the attribute notification methods,
• Using annotations to track specific ENTITYs and the relationships among ENTITYs; for instance, Face_C was generated by sweeping ProfileEdge_A along PathEdge_B.

The table below describes some of the advantages and disadvantages of each mechanism.

Mechanism	Advantages	Disadvantages
History	Exists for all operations Does not require deriving new classes	Provides low-level information Analysis is done after the operation
Attributes	Provides information in addition to history (For instance, entity was split, copied, and merged) Notification occurs when the event occurs	May not provide all information needed by an application Requires deriving new classes
Annotations	Provides the most information about an operation	Not implemented for all operations Requires deriving new classes

A fourth mechanism, adding application-specific callbacks to ACIS algorithms, is no longer supported and has been replaced by the above set of mechanisms.

Persistent Identifiers

A tagging system exists within ACIS that allows a persistent identifier to be associated with an ENTITY. Applications may choose to use these tags, rather than the addresses of ENTITYs, to connect objects in an application with objects in ACIS. A tag is mapped into the address of an ENTITY using api_get_entity_from_id. Tags can be saved and restored; therefore, tags can persist from one session to the next, whereas the addresses of ENTITYs are not persistent.

For more information, refer to ENTITY Tags and Tag Managers.

See Also

• Attributes – allow an application to add application-specific data to ACIS ENTITYs, connect ACIS ENTITYs to data structures within the application, and to notify the application when an ENTITY is changed.
• Patterns – allow an application to create an instance and replicate it in a repeated arrangement. The instance can consist of one or more BODYs, LUMPs, SHELLs, FACEs, or LOOPs.
• Part Management – provides a layer of abstraction to the ACIS data structure, allowing an application to aggregate ACIS ENTITYs into higher level objects called "parts."
• Assembly Modeling – provides mechanisms to model hierarchical data structures of objects and to exchange data between ACIS applications that contain hierarchical data structures of objects.