This package is part of the goedegep.util project, which is document on the page . It is documented on this separated page because of the size of this documentation.
Main concepts
The XTree design is based on the following main concepts.
- A data type that can represent any kind of hierarchical data.
- Different representations:
- Language specific ‘real tree’ implementations, which are modifiable
- Language independent, serialized, representations that only provide read access
XTree logical model
This chapter describes the logical model of an XTree.
The basic structure of an XTree is shown in the following figure. The nodes in this figure are numbered. These numbers have no meaning, they are only there to be able to refer to them in the text.
Each node contains one data item of a specific type. This is indicated via the data type XNodeDataType, of which the possible values are:
- TAG
- BOOLEAN
- INTEGER
- STRING
- BLOB
A node can have any of the following relations to other nodes:
- first child
If a node has any children, this relation points to the first child. The other children are found via sibling relations. - next sibling
This relation points to the next child of the same parent. - Parent
The parent of the node. Each node, except the root node and its siblings, has a parent. These nodes without a parent are also referred to as the top-level nodes.
The figure shows the following:
- The top-level nodes are the nodes 8 and 11.
- node 8 has three children, the nodes 5, 2 and 4.
- node 2 has one child, node 18.
- node 11 has one child, node 6.
XTree Data Notation
This section describes a notation which can be used for describing the content of XTree Data, usually referred to as a data model.
A model definition is described as follows:
model-name ::=
<model-content>
The complete definition is written in the Italics and in a box (as shown above).
The model-name is the name of the data model. This name is referred to in interface definitions, and it can be used in <model-content> as well (see below).
The format of the <model-content> is as follows:
- Each line represents a node or a sub-model.
- Indentation, using spaces, is used to indicate parent/child relations. The structure is based on DFS (Depth First Search). This means that for each node first all its children and their nested children are shown, before its next sibling.
- The first child of a Node is on the line following that node, with an indentation increased by 2 spaces.
- The sibling of a node has the same indentation as that node.
- A node is represented as follows:
- A single character node type. The following types and related characters are currently defined:
BOOLEAN – B
Integer – I
String – S
Tag – G
Binary data – D - A type delimiter ‘:’.
- The node content. This can either be a literal, or a variable (notated as ‘<variable-name>’). Literal String values are given in single quotes, other values are not quoted.
- Container tags are shown in bold.
A container tag is a tag with a list of children of type Tag, all with the same tag value. E.g. the container tag TAG_ICONS only has children with the value TAG_ICON.
- A single character node type. The following types and related characters are currently defined:
- A sub-model is simply represented by its model-name.
- Both a node or a sub-model can be followed by an optional occurrence indicator, which indicates how often the node shall occur. This indicator is represented as follows:
‘[‘<MinOcc>-<MaxOcc>’]’
Where:
<MinOcc> is the minimum number of times the node shall occur.
<MaxOcc> is the maximum number of times the node shall occur.
The value ‘*’ is used to indicate an unbounded number of occurrences.
The part “-<MaxOcc>” may be omitted, in which case <MaxOcc> is the same as <MinOcc>.
The default value for the occurrence indicator is [1]. - Recursive definitions are allowed. This means for example that the model-name may also appear as a sub-model.
- Two slashes (‘//’) indicate a comment. This means that from a syntax point of view, these slashes and everything behind it on the same line shall be ignored.
XTree documentation
The following figure provides an overview of XTree interfaces and implementation.
Package goedegep.util.xtree
This package provides the interface for the most basic XTree implementation.
interface XTree
This interface is for the most basic XTree; a tree which cannot be modified and where you can only walk through the tree with the provided traverse() method.
enum XNodeDataType
This enum defines the types of data that can be stored in an XTree.
interface XTreeNodeVisitor
An implementation of this interface is to be passed as a parameter to the traverse() method.
enum XTreeNodeVisitResult
This enum defines the return values for the methods of the XTreeNodeVisitor interface.
enum XTreeTag
This enum defines the values for nodes of type TAG.
Package goedegep.util.xtree.nodebased
This package adds the possibility to walk through the tree via its nodes.
interface NodeBasedXTree
This interface adds the possibility to walk through an XTree via its nodes.
interface XTreeNode
This interface represents a node in a NodeBasedXTree, it defines the functionality of an XTree node.
The following functionality is provided:
- Basic methods to walk through the tree, like getFirstChild(), getNextSibling().
- Getting the data from a node or from the first child of a node.
A sequence of calls that would frequently occur is: node = node.getFirstChild(), node.getXxxData(), node = node.getParent(). Therefore there are the convenience methods getXxxChildData(). - Debug support like getting a String representation for the structure of a node.
Package goedegep.util.xtree.mutable
This interface adds the functionality to build and modify a tree.
interface MutableXTree
This interface adds modification methods to a node based XTree.
interface MutableXTreeNode
This interface represents a node in a MutableXTree.
Package goedegep.util.xtree.serialized
This interface adds funtionality for serialization to an XTree.
interface SerializedXTree
This interface adds funtionality for serialization to an XTree.
Package goedegep.util.xtree.impl
This package contains the common implementation for an xtree.
class XTreeAbstract
Common part of the implementation of the XTree interface (which isn’t much).
class XTreeNodeVisitorForPrinting
This class is an XTreeNodeVisitor which is used by the toString implementation of the XTree (in XTreeAbstract).
Package goedegep.util.xtree.impl.nodebased
This package contains the common implementation for a node based xtree.
class NodeBasedXTreeAbstract
This class implements the common functionality for a node based xtree.
class XTreeNodeAbstract
This class implements the common functionality for the nodes in a node based xtree.
Package goedegep.util.xtree.impl.ascii
This package provides the implementation of an ASCII serialized tree.
Note: There is no AsciiSerializedXTreeNode yet, as the node base xtree part isn’t implemented yet.
enum AsciiDirection
This class defines the char values for the tree movement directions for an ASCII serialized tree.
class AsciiSerializedXTree
This class provides an XTree, or more specific a SerializedXTree, in ASCII Serialized Form.
enum AsciiTypeIndication
This enum defines the chars for the data types in an ASCII serialized XTree.
Package goedegep.util.xtree.impl.binary
This package provides the implementation of a binary serialized tree.
enum BinaryDirection
Direction indication, used in the binary serialized XTree format.
class BinarySerializedXTree
This class provides an XTree, or more specific a SerializedXTree, in Binary Serialized Form.
enum BinaryTypeIndication
This enum defines the values for the data types in a binary serialized XTree.
class BinarySerializedXTreeNode
This class represents a node in a binary serialized tree.
Package goedegep.util.xtree.impl.defaultmutable
class DefaultMutableXTree
This class provides an implementation of a MutableXTree.
class DefaultMutableXTreeNode
Common part for a node in a DefaultMutableXTree.
class DefaultMutableXTreeBlobNode
A node in a DefaultMutableXTree which can contain a XNodeDataType.BLOB.
class DefaultMutableXTreeBooleanNode
A node in a DefaultMutableXTree which can contain a XNodeDataType.BOOLEAN.
class DefaultMutableXTreeIntegerNode
A node in a DefaultMutableXTree which can contain a XNodeDataType.INTEGER.
class DefaultMutableXTreeStringNode
A node in a DefaultMutableXTree which can contain a XNodeDataType.STRING.
class DefaultMutableXTreeTagNode
A node in a DefaultMutableXTree which can contain a XNodeDataType.TAG.