deferred class
	OBJECT_GRAPH_TRAVERSABLE

General
	cluster: elks
	description: 
		"Utility class to traverse object graphs starting at a root object.
		
		
		When traversing a graph the class distinguishes four different types of references:
		
		(1) Normal references
		(2) References with copy-semantics, which are usually seen when attaching 
		an expanded object to an ANY reference
		(3) User-defined expanded objects, embedded inside another object. 
		Semantically this is a special case of a copy-semantics reference.
		(4) Language-defined expanded objects (INTEGER, POINTER etc) embedded inside another object. 
		Semantically, this is a special case of a copy-semantics reference.
		
		This class will follow all reference types except (4). 
		
		During traversal the agent on_processing_object_action will be called for each object
		and the agent on_processing_reference_action for each reference, if present. This includes
		references to objects that have already been processed.
		
		The algorighm has two output values: visited_objects and visited_types:
		Any standard object without copy-semantics (i.e. reference type (1)) will be stored
		by aliasing inside visited_object. For references of type (2) and (3) a copy will be stored.
		The visited_types hash table contains the dynamic type id of all types encountered during 
		traversal. The key and value in the hashtable are the same.
		
		Setting is_skip_copy_semantics_reference to true means that references of (2) and (3) will
		not be stored in visited_types. Note that this is the only effect of this setting - i.e.
		the traversal algorithm will still follow the references, the agents will be called, and the
		visited_types array will be extended anyway.
		
		NOTE:
		
		Due to a limitation in the reflection library, references of type (2) and (3) within TUPLE 
		and references of type (3) within SPECIAL cannot be handled without causing a copy. This is 
		problematic for agents, especially when they want to change the object. Therefore
		the algorithm will raise an exception when an agent is attached.
		In read-only situations it may be acceptable to use a copy of an object. Therefore to disable the
		exception behaviour you can set is_exception_on_copy_suppressed to True.
		
		NOTE:
		
		To maintain backwards compatibility the traversal algorithm will silently ignore any kind of 
		exception and just return normally, with traversed_objects set to whatever value it had before 
		invoking traverse. In order to get exceptions you need to set is_exception_propagated to True."

Ancestors
	ANY

Queries
	has_failed: BOOLEAN
	has_reference_with_copy_semantics: BOOLEAN
	is_exception_on_copy_suppressed: BOOLEAN
	is_exception_propagated: BOOLEAN
	is_object_action_set: BOOLEAN
	is_root_object_set: BOOLEAN
	is_skip_copy_semantics_reference: BOOLEAN
	is_skip_transient: BOOLEAN
	object_action: detachable PROCEDURE [separate ANY]
	on_processing_object_action: detachable PROCEDURE [REFLECTED_OBJECT]
	on_processing_reference_action: detachable PROCEDURE [REFLECTED_OBJECT, REFLECTED_OBJECT]
	root_object: detachable ANY
	visited_objects: detachable ARRAYED_LIST [separate ANY]
	visited_types: detachable HASH_TABLE [INTEGER_32, INTEGER_32]

Commands
	set_is_exception_on_copy_suppressed (v: [like is_exception_on_copy_suppressed] BOOLEAN)
	set_is_exception_propagated (v: [like is_exception_propagated] BOOLEAN)
	set_is_skip_copy_semantics_reference (v: [like is_skip_copy_semantics_reference] BOOLEAN)
	set_is_skip_transient (v: [like is_skip_transient] BOOLEAN)
	set_on_processing_object_action (an_action: [like on_processing_object_action] detachable PROCEDURE [REFLECTED_OBJECT])
	set_on_processing_reference_action (an_action: [like on_processing_reference_action] detachable PROCEDURE [REFLECTED_OBJECT, REFLECTED_OBJECT])
	set_root_object (an_object: [like root_object] detachable ANY)
	traverse
	wipe_out


Generated by ISE EiffelStudio