MagicTree supports different sorts of nodes that can be used to represent various kinds of objects and data.
Two Branch nodes
Branch nodes are represented by MrBranchObject class.
In XML a branch node with value "nodevalue" is represented as follows:
<nodevalue id="999" status="none" class="MtBranchObject" />
When branch nodes are compared for equality during merge only the node values are compared. Two branch nodes are equal if their values are equal.
Branch nodes, when represented in XML, should not have any text. If a branch node is read from XML representation any text is ignored by MagicTree.
During merge no special processing is done for branch nodes.
The host is represented by a Simple node (with type "host" and name "127.0.0.1")
Simple nodes are represented by MtSimpleObject class.
In XML a simple node is represented as follows:
<host id="999" status="none">127.0.0.1</host>
Simple nodes represented in XML may have "class" attribute with value set to "MtSimpleObject". If an XML element does not have a "class" attribute, it is treated as simple node.
When simple nodes are loaded from XML the text data is trimmed (the whitespace in the beginning and the end of the text is removed).
When simple nodes are compared for equality during merge, the types and the names of the nodes are compared. Two simple ndoes are equal if they have the same type and the same name. Names are trimmed of whitespace.
During merge no special processing is done for simple nodes.
A text node in the tree on the left and its text content in the tab on the right
Text nodes are represented by MtTextObject class.
In XML a text node is represented as follows:
<text id="999" status="none" class="MtTextNode" title="Executive Summary">This report is about something.</text>
Text nodes always have "text" as their XML tag. The "title" attribute is used to store the title.
When compared for equality during merge, only titles are compared, not the text. If the two text objects have the same title, but different text, the merged object has the text of the object in the merging tree.
At the moment, when two text nodes are merged, the text of the node in the second tree is copied to the resulting object. In the future, we will probably implement some representation that shows the original text and any modifications in the merged node.
Data nodes look like this in the tree:
Data node
Currently MagicTree GUI does not provide a way to attach a file to data node.
Data nodes are represented by MtDataObject class.
In XML a data node is represented as follows:
<data id="999" status="none" class="MtDataObject" filename="packetdump.bin">Packet dump</data>
The actual data is stored outside of the XML file in a subdirectory inside the project file (see Project File Structure)
During merge data objects are compared for equality based on their titles and data. If two data objects have equal titles and bit-by-bit equal data files, they are considered equal.
No special procesing is performed for text nodes during merge.
XML data nodes are represented by MtXmlDataObject class.
A image node in the tree on the left and its content in the tab on the right
Cross-reference pointing to a host node
Cross-references can not have child nodes.
To link a cross-reference to a node, right click on the cross-reference node, select "Link to object" from the context menu and then select the object you want to link the cross-reference to.
Cross-references can also be created by drag and drop. Select the nodes you want to link to (link targets). Press Ctrl+Shift (Command+Option on Mac) and drag the nodes to the location where you want to create the cross-references.
To follow a cross-reference Ctrl+click it (Command+click on Mac).
Cross-references are represented by MtXrefObject class.
In XML data a cross-reference is represented as follows:
<xref id="7" status="none" class="MtXrefObject" href="#2"/>
The "xref" attribute contains the id of the node that the cross-reference links to.
During merge, cross-references are compared for equality based on the objects they point to. For two cross-references to be equal, the objects they point to have to be equal and all ancestors of the nodes they point to up to the tree root have to be equal. The reason behind it is that a cross-reference pointing to port 80 of host 127.0.0.1 is not the same a cross-reference pointing to port 80 of host 192.168.1.1. Therefore to establish the equality, we have to compare all ancestor nodes as well.
When two cross-references are merged the resulting cross-reference will point to the target in the first tree (if the target hasa already been merged). If the target has not yet been merged, the cross-reference will point to the node in the second tree. When the target node is merged, the cross-reference pointing to it is updated to point to the merged node in the first tree.
A tree containing a finding represented by Overview node
An Overview node has a name and a value, similar to a Simple node. The main difference is how it is displayed. The detailed view panel on the right shows an overview of all Text nodes under the selected Overview node.
Overview nodes are represented by MtOverviewObject.
In XML Overview nodes are represented as follows:
<finding id="999" status="none">Oh the world must be coming to an end</host>
During merge, the Overview nodes are compared for equality similar to the Simple nodes - both the name and the value are compared.
No special processing is performed while merging Overview nodes.
Queries, Methods and Tasks
No special processing is performed for query nodes during merge.
During merge methods are compared for equality similar to cross-references. A method is actually a cross-reference to query it uses (and MtMethodObject is a subclass of MtXrefObject). In addition to that the commands of the two methods are compared for literal equality.
No special processing is performed for method nodes during merge, except updating the cross-reference same as for the cross-reference nodes.
Since only UUIDs are compared for equality, during merge two equal tasks can have different data. This can happen if, for example, a copy of the project file was made when a task was scheduled or still running. When the project file is opened on the computer where the task was originally started, the task will be picked up by the MagicTree process monitor and the task will eventually complete. When the project file is opened on a different computer or by different user, the process monitor will fail to pick up the task and it will have an error state. When the two project files are subsequently merged, MagicTree takes care to preserve the data from the task node that is most likely to contain relevant data. To accomplish this, when merging two equal task nodes, MagicTree will retain the data from the task with highest state that is not an error state. The task states have the following order (from lowest to highest):
NEW (not an error) - the task is submitted for execution, the task controller may be busy starting it
START EXCEPTION (error) - the task controller has failed to start the task
STARTED(not an error) - the task is running, the task controller may be monitoring it
MONITOR EXCEPTION (error) - the task controller has failed to monitor the progress of the task
EXITED (not an error) - the task has exited, the task controller is probably busy picking up its results
PICKUP EXCEPTION (error) - the task controller has failed to pick up the results of the task
FINISHED (not an error) - the task has finished its execution and its results are available