ENTITY

List of:	Classes
Subjects:	Entity, SAT Save and Restore
Contents:	Kernel

Purpose:

Represents common data and functionality that is mandatory in all classes that are permanent objects in the model.

Derivation:

ENTITY : ACIS_OBJECT : -

SAT Identifier:

"unknown"

Filename:

kern/kernel/kerndata/data/entity.hxx

Description:

All classes representing permanent objects in ACIS derive from the ENTITY class. ENTITY does not represent any object within the modeler. Instead, ENTITY represents common data and functionality that is mandatory in all classes that represent permanent objects.

ENTITY contains a pointer to the bulletin. By default the the bulletin board logging mechanism is on, and the pointer supports roll back mechanisms. At the start of a modeling operation, the bulletin pointer is initialized (to NULL) in every entity. When an entity is changed, the backup function creates a new bulletin, if needed.

ENTITY constructors and destructors also manipulate bulletin board records. Because entities are continually backed up onto the bulletin board, all objects descended from ENTITY must be allocated on free store using the new operator. The new operator is overridden for entities. It calls a special free store allocator that manipulates a private free list. Use of a private free list allows ACIS extensive control over memory management. Refer to the Kernel Component Manual for additional information on bulletins and the 3D ACIS Application Development Manual for additional information on memory management.

ENTITY also contains pointers from objects to system-defined and user-defined attributes. Not all objects use these attribute pointers, but automatic creation and deletion of attributes for any object is supported.

Deep Copying Entities

For a copy of an entity that does not share underlying information with the original, a deep copy should be used. A deep copy is a copy made by replicating the object plus any assets owned by the object, including objects pointed at by data members of the object being copied. The copied item does not share any data with the original. A deep copy allocates new storage for all member data and any pointers, so that all the information about that item is self-contained in its own memory block.

An example of when a deep copy of an entity is needed is when a copy of the entity needs to be moved into a different history stream, breaking all ties with the previous history stream.

A call to function api_deep_copy_entity can be used to create a deep copy. There are some entities that are can not be deep copied (by design). If such entities are present during a deep copy, a sys_error will be thrown. A flag can be passed into the API if attributes that can't be deep copied need to be skipped over when doing a deep copy. Any non-attribute entities that cannot be deep copied will throw a sys_error regardless of the logical flag setting.

Entity Macros

Macros simplify the definition of user entities. Many of the methods required for any entity are the same for all entities at the source level. Other methods have elements in common. All of these methods are defined in the following nested macros in the entity.hxx file:

MASTER_ENTITY_DECL

ENTITY_FUNCTIONS

LOOKUP_FUNCTION

TRANSFORM FUNCTION

MASTER_ENTITY_DEFN

ENTITY_DEF

UTILITY_DEF

DEBUG_DEF

LOOKUP_DEF

SAVE_DEF

RESTORE_DEF

COPY_WITH_DEEP_COPY_DEF

SCAN_DEF

FIX_POINTER_DEF

TERMINATE_DEF

SIMPLE_COPY_LOSE

Classes Derived From ENTITY

The model data structure is based on derivatives of the C++ base class ENTITY (must be uppercase). The data structure allows consistent performance in generic operations such as system debugging, change records (bulletin board), roll back, attributes, and model archiving and communication.

The classes derived from ENTITY that represent the topology of the model include: BODY, LUMP, SHELL, SUBSHELL, FACE, LOOP, COEDGE, EDGE, VERTEX, and WIRE. Each class inherits all properties of ENTITY, adds unique structural data, and provides access to that data. Data access provides a layer of removable checking. Data structures derived from ENTITY allow extensions that can remove some redundancy in the model. This data structure also permits segmentation, which can limit the data to only the regions of interest in a large model.

The classes derived from ENTITY that represent the geometry of the models include: CURVE, which derives ELLIPSE, INTCURVE, and STRAIGHT; PCURVE; POINT; SURFACE, which derives CONE, PLANE, SPHERE, SPLINE, and TORUS; and TRANSFORM. The specific geometric information is private to these subclasses. All access to these classes passes through member functions.

The ENTITY-derived class ATTRIB provides a generic access function from which system derived attributes are defined and user-defined attributes can be defined. ATTRIB allows the application a means to determine the type of attribute represented, and the way it is processed. The modeler uses system-defined attributes during its operations. Refer to the Kernel Component Manual and the 3D ACIS Application Development Manual for more information about using the ATTRIB class. The relationship of model classes is illustrated in the following figure.

Lowercase classes (surface, curve, plane, cone, straight, ellipse, etc.) are not derived from ENTITY but are defined as a convenient means of recording and passing around groups of data.

Restoring Entities

Restore proceeds in two stages:

1.

Read the save file record and construct the new object, leaving pointers to other restored entities in symbolic form (as indices into an array), and entering the address into the array.

2.

After all new objects have been constructed, visit each to convert the symbolic ENTITY pointers into genuine ones.

Restore Stage 1. The restore_entity_from_file function reads the id string from the start of each save file record, and searches its tables for the id components, starting with the last (base) one, and proceeding towards the leaf. It then calls the restore function for the leaf-most class found. That function constructs an object of the appropriate derived type, and then calls its restore_common member function. That function in turn calls its parent's restore_common member function, and then reads data specific to the derived class. Finally, restore_entity_from_file reads any more data in the save file record, and constructs an unknown_entity_text record to contain it, together with any unrecognized id strings.

Restore Stage 2. The fix_pointers member function for each entity in the array is called, with the array as argument. This calls fix_common, which calls its parent's fix_common, and then corrects any pointers in the derived class. In practice there is never anything special for fix_pointers to do, but it is retained for consistency and compatibility.

References:

KERN

ATTRIB, pattern_holder, unknown_text_pointer

by KERN

APOINT, ATTRIB, ATTRIB_TAG, BULLETIN, COEDGE, COPY_ANNOTATION, CREATE_TOL_ANNO, CURVE, EE_LIST, ENTITY_PTR, HISTORY_STREAM, PCURVE, REVERT_TOL_ANNO, SPLIT_ANNOTATION, SURFACE, WIRE, entity_gedge, entity_gvertex, entity_with_ray, pattern_holder, standard_error_info

Constructor:

public: ENTITY::ENTITY ();

C++ allocation constructor requests memory for this object but does not populate it. The allocation constructor is used primarily by restore. Applications should call this constructor only with the overloaded new operator, because this reserves the memory on the heap, a requirement to support roll back and history management.

public: ENTITY::ENTITY (

const ENTITY& e

// entity

);

C++ assignment constructor.

Destructor:

protected: void ENTITY::check_destroy () const;

Checks that entity deletion is legitimate. It complains if there is an attempt to delete an entity other than through the private member function destroy, which is carefully controlled.

public: virtual void ENTITY::lose ();

Posts a delete bulletin to the bulletin board indicating the instance is no longer used in the active model. The lose methods for attached attributes are also called.

protected: virtual ENTITY::~ENTITY ();

This C++ destructor should never be called directly. Instead, applications should use the overloaded lose method inherited from the ENTITY class, because this supports history management. (For example, x=new ENTITY(...) then later x->lose.)

Methods:

public: virtual void ENTITY::add ();

If the entity is use counted, add one to the count. If the entity is not use counted, signal an error.

On a use counted entity, each held pointer to it should be declared by calling add. There should be matching calls to remove when done with the pointer. For normal entities, simply call lose when the entity is no longer part of the active model. For use counted entities, the implementations of add and remove come from macros in usecount.hxx. Use counted entities implemented without the macros should implement these virtual methods manually.

public: static MethodFunction ENTITY::add_method (

METHOD_ID const&,

// id

MethodFunction

// function

);

Registers an implementation function for a run-time virtual method. (Supplied by the ENTITY_FUNCTIONS and UTILITY_DEF macros.)

public: virtual logical ENTITY::apply_transform (

SPAtransf const&,

// transform to apply

ENTITY_LIST&,

// ENTITYs transformed

logical

// negate

= FALSE

);

The ENTITY_LIST is used to prevent sub entities from being transformed more than once. Transforms an ENTITY. This is not included in the standard ENTITY methods to allow nontransformable entities to use the default implementation. (Supplied by the TRANSFORM_FUNCTION and TRANSFORM_DEF macros.)

public: ATTRIB* ENTITY::attrib () const;

Returns the ENTITY's attribute pointer, or NULL if there is no attached attribute.

public: ENTITY* ENTITY::backup ();

Creates a duplicate record and a change bulletin, if needed, as a backup for roll back. The duplication is done via the virtual function, make_copy to let each derived type do its own backup. Before performing a change, each routine checks whether the data structure is posted on the bulletin board. If not, the posting is done automatically. Called by all system change functions.

protected: SPAbox* ENTITY::box_ptr () const;

This is a bounding_box access function.

public: int ENTITY::bulletin_count () const;

Returns the count of bulletins referring to this entity.

protected: virtual logical

ENTITY::bulletin_no_change_vf (

ENTITY const* other,

// other entity

// in bulletin

logical identical_comparator

// identity compare

) const;

Virtual function for comparing subclass data - called by bulletin_no_change. For the identical_comparator argument to be TRUE requires an exact match when comparing doubles and returns the result of memcmp as a default (for non-overridden subclasses). FALSE indicates tolerant compares and returns FALSE as a default.

public: virtual logical ENTITY::call_method (

METHOD_ID const&,

// method id

METHOD_ARGS const&

// method args

);

Executes the implementation function for a routine virtual method. (Supplied by the ENTITY_FUNCTIONs and UTILITY_DEF macros).

protected: void ENTITY::copy_common (

ENTITY_LIST&,

// ENTITYs being copied

ENTITY const*,

// ENTITYs being copied

pointer_map* pm

// pointer map

= NULL,

logical dpcpy_skip

// skip deep copy or not

= FALSE,

SCAN_TYPE reason

// scan type

= SCAN_COPY

);

Fills in the entity with data from the copied entity, converting pointers into indices in the entity list. Supports the copy operation. (Supplied by the ENTITY_FUNCTIONS and COPY_DEF macros.)

Each derived class's save_common first writes out that class's identifier, calls its parent class's save_common, and then writes out data particular to the derived class. Thus the save record consists of identifiers in leaf-to-base order, followed by class data in base-to-leaf order. As it writes out any ENTITY pointers, it adds them to the ENTITY_LIST, so that any dependent data also gets written to the file.

public: virtual ENTITY* ENTITY::copy_data (

ENTITY_LIST&,

// ENTITYs to copy

pointer_map* pm

// pointer map

= NULL,

logical dpcpy_skip

// skip deep copy or not

= FALSE,

SCAN_TYPE reason

// scan type

= SCAN_COPY

) const;

Allocates a new ENTITY and calls copy_common to fill it in. Supports the copy operation. (Supplied by the ENTITY_FUNCTIONS and UTILITY_DEF macros.)

public: virtual logical ENTITY::copy_pattern_down (

ENTITY* target

// target

) const;

Copy the pattern holder of this entity to target, and add the target entity to the other_ents list of the pattern holder. Should be overridden if there are child entities that should implement this behavior as well.

public: virtual void ENTITY::copy_scan (

ENTITY_LIST&,

// ENTITYs to copy

SCAN_TYPE reason

// type of scan

= SCAN_COPY,

logical dpcpy_skip

// skip deep copy or no

= FALSE

) const;

Supports the copy operation. Adds dependent entities to the list of entities to be copied. (Supplied by the ENTITY_FUNCTIONS and SCAN_DEF macros.) The default type of scan (reason) is SCAN_COPY.

public: virtual void ENTITY::debug_ent (

FILE*

// file pointer

) const;

Prints the type and address of this object, roll back pointer, attributes, and any unknown subtype information. This is called by DEBUG_LIST::debug for an entirely unknown entity type, or at the start of any derived class's debug_ent method. Each derived class's debug_ent method uses the debug function described in the 3D ACIS Application Development Manual to print information added at that level. (Supplied by the ENTITY_FUNCTIONS and DEBUG_DEF macros.)

public: virtual logical ENTITY::deletable () const;

Indicates whether this entity is normally destroyed by lose (TRUE), or whether it is shared between multiple owners using a use count, and so gets destroyed implicitly when every owner has been lost (FALSE). Most entities are destroyed explicitly using lose, and so the default returns TRUE.

protected: void ENTITY::fixup_copy (

ENTITY*

// one to copy for backup

) const;

Fixes any pointers in the ENTITY after copying for backup. For ENTITY, it has nothing to do, but because it is called by all data types, it is required to terminate the copy chain. (Supplied by the ENTITY_FUNCTIONS and SIMPLE_COPY_CONE macros.)

protected: void ENTITY::fix_common (

ENTITY* [],

// ENTITY pointers to fix

SCAN_TYPE reason

// type of scan

= SCAN_COPY

);

Called by fix_pointers. Converts pointers from copy indices into real pointers. For ENTITY converts the attribute pointer, and any pointers in the unknown_entity_text record. (Supplied by the ENTITY_FUNCTIONS and FIX_POINTER_DEF macros.)

public: virtual void ENTITY::fix_pointers (

ENTITY* [],

// ENTITY pointers to fix

SCAN_TYPE reason

// type of scan

= SCAN_COPY

);

The fix_pointers method for each entity in the restore array is called, with the array as argument. This calls fix_common, which calls its parent's fix_common, and then corrects any pointers in the derived class. In practice there is never anything special for fix_pointers to do, but it is retained for consistency and compatibility. (Supplied by the ENTITY_FUNCTIONS and UTILITY_DEF macros.)

public: virtual void ENTITY::get_all_patterns (

VOID_LIST& list

// list of patterns

);

Adds the pattern on this entity, if any, to the list, if the pattern is not already there. Needs overriding if there are child entities to be queried.

public: pattern_holder* ENTITY::get_pattern_holder (

logical consider_parent

// possible

= FALSE

// parent

) const;

Gets the pattern holder, if any, from the entity (default) or from its parent.

public: ENTITY* ENTITY::get_pattern_owner ();

Gets the entity that owns the pattern on this entity, if there is one. If one of the entity's siblings is the seed entity, it returns a pointer to this sibling.

public: HISTORY_STREAM* ENTITY::history () const;

Returns a pointer to the history stream for this entity.

public: virtual int ENTITY::identity (

int

// level

= 0

) const;

If level is unspecified or 0, returns the type identifier ENTITY_TYPE. If level is specified, returns ENTITY_TYPE for that level of derivation from ENTITY. The level of this class is defined as ENTITY_LEVEL.

A positive level specifies the level of derivation down from the ENTITY class to examine. ENTITY itself is level 0. If level is unspecified or 0, the type of the most specific class of object is returned. If level is 1, the type of the class one level down from ENTITY is returned. If level is 2, the type of the parent class 2 levels down from ENTITY is returned, and so on. If level is greater than the level of the instance, -1 "unknown" is returned.

A negative level similarly specifies the level of derivation up from the most specific class of object returned.

(Supplied by the ENTITY_FUNCTIONS and UTILITY_DEF macros.)

public: virtual logical ENTITY::is_deepcopyable (

) const;

Returns TRUE if this can be deep copied.

public: virtual logical ENTITY::is_pattern_child () const;

An entity is a "pattern child" when it is not responsible for creating new entities when the pattern is applied, this being the responsibility of some owning entity. If an entity is either always or never a pattern child, this can be overridden to always return either TRUE or FALSE.

public: virtual logical ENTITY::is_use_counted () const;

Tell whether this entity is use counted. The default implementation returns FALSE.

public: virtual int ENTITY::lookup (

logical

// insert into debug list

) const;

Looks up an entity in the appropriate debug list. This is not included in the standard ENTITY methods because often subclasses may wish to be included in their parent's debug list. This is done by not including a lookup method in the subclass. If the logical is TRUE, the ENTITY is inserted into the debug list if it does not already exist on the list. If the logical is FALSE and the ENTITY does not exist on the list, a -1 is returned. (Supplied by the LOOK_FUNCTION and LOOKUP_DEF macros.)

public: logical ENTITY::needs_rollback () const;

Checks whether the record is already backed up.

public: ENTITY& ENTITY::operator= (

const ENTITY& e

// entity

);

Sets the string value from a pointer to the entity.

public: virtual ENTITY* ENTITY::owner () const;

Identifies the owner, if any, in the data structure of this ENTITY. NULL indicates no owner or an unidentifiable one. Objects of the ENTITY base class have no identifiable owner.

public: virtual logical ENTITY::patternable () const;

Indicate whether or not a pattern can be applied to this entity. The default is FALSE, so this needs to be overridden for patternable entities. An entity can have a non-NULL pattern_ptr even if it is not patternable, for a pattern may be put upon a patternable parent entity.

public: int ENTITY::pattern_index () const;

Gets the pattern index associated with this entity, returning -1 if no pattern is present.

public: virtual void ENTITY::remove (

logical lose_if_zero

// use counted or not

= TRUE

);

If the entity is use counted, subtract one from the count and if the count goes to zero and lose_if_zero is set, lose the entity. If the entity is not use counted, signal an error.

On a use counted entity, each held pointer to it should be declared by calling add. There should be matching calls to remove when done with the pointer. For normal entities, simply call lose when the entity is no longer part of the active model. For use counted entities, the implementations of add and remove come from macros in usecount.hxx. Use counted entities implemented without the macros should implement these virtual methods manually.

public: virtual logical

ENTITY::remove_from_pattern ();

Removes the pattern element associated with this entity from the pattern. Returns FALSE if this entity is not part of a pattern element, otherwise TRUE. Should be overriden if this entity can be a parent pattern entity, as the default behavior is simply to pass the call on to the entity's owner.

public: virtual logical

ENTITY::remove_from_pattern_list ();

Removes the entity from its pattern list. Should be overridden if there are child entities to be removed as well

public: virtual logical ENTITY::remove_pattern ();

Removes the pattern from the parent entity owning the pattern, returning FALSE if no pattern was found. Should be overridden if the pattern needs to be removed from siblings.

public: logical

ENTITY::remove_pattern_if_unsavable ();

Removes the pattern if there are unsavable or pattern-incompatible attributes present.

public: void ENTITY::restore_common ();

Restores data for a record from disc to memory, writing pointers as indices (fix_pointers turns them back into pointers) and returning a pointer to the entity made. Generally "common" functions which do the main work are protected, as they are only called from the main entry functions or by themselves up the derivation tree.

restore_common is public because the main restore function is not a member function, and making it a friend would make it unable to be declared static, i.e. local to the defining module. (Supplied by the ENTITY_FUNCTIONS and RESTORE_DEF macros.)

Restore data for a record from disc to memory, writing pointers as indices (fix_pointers turns them back into pointers) and return pointer to entity made.

read_ptr

Pointer to record in save file for first attribute owned by entity.

if (restore_version_number >= ENTITY_TAGS_VERSION)

read_int

new tag

public: void ENTITY::restore_end (

char*

// id_string

);

Terminates a restore record, reading any trailing text and filling in the unknown text pointer. Used only by the save/restore system.

public: BULLETIN*& ENTITY::rollback ()const;

Returns the pointer to the bulletin board entry for this ENTITY.

protected: virtual void ENTITY::roll_notify (

BULLETIN_TYPE,

// type of bulletin being

// rolled back

ENTITY*

// info to be restored

// into this argument

);

Field notification of a rollback operation. The first argument specifies the type of bulletin being rolled back (create, delete or change). In the case of a change notification, the second argument contains the information to be restored into this object. The base implementation, which is used for almost every derived class, does nothing at all.

public: virtual void ENTITY::save (

ENTITY_LIST&

// ENTITYs to save

) const;

Performs a save operation by calling save_begin, the particular class's save_common, and then save_end. (Supplied by the ENTITY_FUNCTIONS and UTILITY_DEF macros.)

This save method is just like any other save, except that it calls save_begin with an optional argument to suppress writing of a trailing dash, because save_common does not write out an identifier, or call any parent class's save_common.

protected: void ENTITY::save_begin (

logical

// terminator flag

= FALSE

) const;

Starts the save record by writing out a preamble to a save file record containing any subclass identifiers not known to this version of ACIS. Called by the save method.

protected: void ENTITY::save_common (

ENTITY_LIST&

// ENTITYs to save

) const;

Handles the save operation by writing out the savable data associated with the base class. In the case of ENTITY, saveable data is simply the attribute pointer. In the case of child classes derived from ENTITY, class-specific save_common methods handle the class-specific data. Called by the save method. (Supplied by the ENTITY_FUNCTIONS and SAVE_DEF macros.)

protected: void ENTITY::save_end (

ENTITY_LIST&

// ENTITYs to save

) const;

Writes out any data associated with subclasses not known to this version of ACIS, and terminates the save file record. Called by the save method.

public: void ENTITY::set_attrib (

ATTRIB*

// new attribute

);

Changes the attribute pointer to point to the new attribute.

protected: void ENTITY::set_box (

SPAbox* bound

// bounds

);

This is an access method for bounding boxes.

public: virtual void ENTITY::set_pattern (

pattern* in_pat

// pattern

);

Sets the pattern on this entity, replacing any existing pattern. This needs to be overridden if the pattern needs passing down to any child or sibling entities.

public: void ENTITY::set_pattern_holder (

pattern_holder* in_pat

// pattern holder

);

Replaces the existing pattern holder (if any) with a new one.

public: virtual void ENTITY::set_use_count (

int

// use counted or not

);

If the entity is use counted, set the count. If not use counted, do nothing.

public: virtual unsigned ENTITY::size () const;

Returns the size, in bytes, of the object. (Supplied by the ENTITY_FUNCTIONS and UTILITY_DEF macros.)

public: tag_id_type ENTITY::tag (

logical assign_new

// assign new tag

= TRUE

// number or not

) const;

Data reading routine.

public: virtual const char*

ENTITY::type_name () const;

Returns the string "unknown".

public: virtual int ENTITY::use_count () const;

If the entity is use counted, get the count. If not use counted, return zero.

Internal Use:

full_size

Related Fncs:

get_history_size, is_ENTITY

PDF/KERN/31CLE.PDF
HTM/DATA/KERN/KERN/31CLE/0005.HTM