Taxonomy Definition - XML Descriptor
VirtualTreeNavigator's taxonomy definition are written as plain XML files. There's no DTD, since the XML is fairly simple. This section describes the XML Descriptor elements.
1. XML Header
Start your XML file with an XML header like the one below. You may want to use different encodings in case you are using different language characters (e.g. in hard-coded strings).
2. Root Document Element - The "taxonomy" node
Every taxonomy definition contains one and only one taxonomy element. The taxonomy node can have an id attribute, which will be displayed in the UI as the name of the top-level tree node:
The taxonomy node can have three types of child nodes as described below:
Child Node | Cardinality | Description |
---|---|---|
nodeicon | 0..* | Optional cosmetic feature. Using these kind of nodes you can customize the icon image that will be displayed in the UI instead of the default |
query | 1..* | Specification of an SQL queries (nodetype olf resultset, identifier column, name column, etc.) |
taxdef | 1..* | Definition rules for the Taxonomy based on level, nodetype, etc. |
metadata | 0..* | Meta-data query references for gathering additional data for each node. |
2.1. "nodeicon" element
Node Icon definitions are optional. VirtualTreeNavigator will by default use (two-state) folder icons to display the nodes of the hierarchy. Every level of the hierarchy has a different color and there are 16 colors in VirtualTreeNavigator's icon sets, so level 17 has the same colored icon as level 0. "nodeicon" elements can take the following attributes:
- nodetype, the Node Type that will receive the icon annotation
- nodeid, (optional) if specified only the nodes with matching Id and Node Type will receive the icon annotation
- iconindex, the Icon Index that will be used. The Node will be displayed in the grayscale version of the icon until its contents are read from the database. For a list of icons press the [F4] key.
2.2. "query" element
Query definitions are the low-level interface of the Taxonomy Definition. They specify the result set that will be retrieved when the query is called. Query definitions can be used for:
- structuring your taxonomy definitions (normal queries), or
- simply adding meta-data attributes to your nodes (meta-data queries).
Query definitions can have the following attributes:
"query" attributes | Optional | Description |
---|---|---|
name | No | The unique identifier of the query. |
nodetype | Yes | The Node Type of each of the query's result nodes. This attribute is useful when the query returns a constant type of nodes (e.g. you are reading from the "COUNTRY" table, therefore all nodes are of type="country"). It can be ommitted when the "nodetypecol" is present. If the "nodetypecol" attribute exists and the query returns a non-null value for the specified column then that value will determine the Node Type of the node. |
nodetypecol | Yes | The name of the column which signifies the Node Type of the node. This attribute is helpful when a query can return nodes of different types, in which case one of the columns in the query should contain the type. |
nodeidcol | No | The name of the column which denotes the unique identifier of the node. The identifier will be used to match "taxdef" elements during run-time. |
nodenamecol | No | The name of the column denoting the Name of the node. The name of the node is only required for the UI and will be displayed next to the icon in the Tree representation at run-time. The column can be the same as the id if required. |
iconindexcol | Yes | The name of the column which can be used to drive the Icon that will be displayed in the UI for each node in the result set. Use this if you want to override the default icons and only if you wish to display a different icon for each child node. You can also use the global "nodeicon" definitions if that's more appropriate. |
If a query definition contains only the "data" attribute, it is considered to be a Meta-data Query and can only be used to collect additional data for nodes (see the "metadata" node).
Queries can be written in SQL, plain text or a scripting language. A "query"
node should therefore contain
one and only one of the following node elements:
"query" elements | Description |
---|---|
sql | This is a simple SQL query that can contain parameter placeholders (?). For each parameter placeholder an argument need to be specified when this query is used. |
text | A "text" query is simply a comma-separated list of data that gets added to the node. Text can be manipulated at
run-time using the ${arg} placeholder for arguments (the placeholder can be overwritten). |
script | Not Implemented Yet. This feature will allow the inclusion of scripting languages which will be able to produce CSV output to be used for building taxonomies. |
2.2.1 "sql" element
SQL elements contain a simple CDATA
XML element that in turn contains the SQL query description in a free-text
format. Placeholders are indicated with ? and when the query is executed the number of placeholders should match the number
of arguments given to the query reference. The text of the SQL query can be arbitrarily large, although we recommend to keep
structural SQL queries relatively short and use meta-data queries for additional node data (see the metadata
element).
Examples of SQL "query" elements
Below you can see two examples of "query" elements. The first example returns nodes of "synonym" type for a given database
owner (Oracle).
The second example returns any full list of objects that belong to a database schema (Oracle), using the lower(object_type) as
the Node Type.
2.2.2 "text" element
A query that contains a "text" element, first and above all does not require a connection to a database or any other kind of setup. Theoretically you can build a taxonomy using just text data. However, since text queries do not contain any information on the columns and structure of the data (unlike SQL queries which can retrieve this information from the database driver), they require some additional attributes. The attributes you can use when defining a text query are:
"text" attributes | Optional | Description |
---|---|---|
columns | No, if "headerrow" not specified. | A comma-separated list (e.g., columns="id, name" ) that specifies the names of the columns that appear
in the textual data of the query. The number of columns in this list must match the number of columns in every row of the
result set. |
headerrow | No, if "columns" not specified. | If headerrow="true" the first row of the result set (the CDATA section) is used for acquiring
the names of the columns of the result set (see examples below).
|
argplaceholder | Yes | The default argument placeholder for textual data is ${arg} . If however this string has any particular
significance in your text, then you can use this attribute to override it. For example, you may want to use the string
#arg# as a placeholder. |
Examples of text "query" elements
The first example is a text query, that defines two columns with names "id" and "name" and contains three rows of results.
Each time this query is used will generate the same three nodes in the hierarchy.
The second example is a text query which contains the header row within the CDATA
section.
2.2.3 "script" element
Not Implemented Yet. This feature will allow the inclusion of scripting languages which will be able to produce CSV output to be used for building taxonomies.
2.3. "taxdef" element
TaxDef rules are the backbone of the XML descriptor. These rules determine how a hierarchy is built and which queries will be used to build each node of the hierarchy. The taxdef element can take three attributes, all of which are optional:
- level, the Level of the hierarchy this rule applies to
- nodetype, the Node Type of the node this rule applies to
- nodeid, the Node Identifier of the node this rule applies to (requires nodetype attribute)
For example:
Depending on how specific to a node they are, the taxdef elements are sorted by the Taxonomy Engine in order of precedence:
"taxdef" attributes | Rule Applies To... | ||
---|---|---|---|
level | nodetype | nodeid | A specific node in the hierarchy which appears at the specified level. All node attributes must match |
nodetype | nodeid | A specific node in the hierarchy appearing at any level | |
level | nodetype | All nodes of the specified Node Type appearing at the specified level of the hierarchy | |
nodetype | All nodes of the specified Node Type appearing at any level | ||
level | All nodes of the specified Level | ||
<none> | Matches any node. This can be used for hierarchies where a recursive relationship exist in the database. |
A taxdef element can have one or more query child nodes. These child nodes refer to the query definitions of the previous section 2.1 and define the arguments that will be passed to the queries. The values for the arguments come from the meta-data of the current node or its ancestors. A query referenc looks like this:
The query node gets a one and only attribute refid which denotes the name of the query definitions
to be used.
Argument nodes can take one of the following attribute sets:
"argument" attributes | Argument Value is taken from... | ||
---|---|---|---|
columnname | The value for the argument will be taken from the specified column of the parent node (the node we are expanding) | ||
level | columnname | The value for the argument will be taken from the specified column of the node with the specified level in the hierarchy. The level can be either absolute (e.g. 0, 1, 2, ...) with zero being the root node of the hierarhcy, or relative (e.g. -1, -2, -3, ...) denoting the number of levels up the hierachy we will retrieve attributes from. A value of "-1" for the level means the parent node, i.e. it can be ommitted as the rule is the same as the previous one. | |
nodetype | columnname | [order] | The value will be taken from the specified Column of an ancestor node of the specified Node Type.
If more than one node of the same Node Type exist in the hierarchy the order attribute comes into play: - when order="asc" the Taxonomy Engine will look for the node of the specified Node Type from Top to Bottom (i.e. from level 0, 1, ...) - when order="desc" the Taxonomy Engine will look from the current level of the hierarchy, going upwards. Order is assumed to be ascending by default. |
value | The argument value will be the one specified (hard-coded). This attribute is particularly useful when one query can be reused for more than one Taxonomy Definitions. |
Examples of "taxdef" elements
Below you can see two examples of "taxdef" elements. The first example simply calls the "getUserFolders" query when a node of
"dba_user" Node Type is found in the hierarchy.
The second example will call query "getUserObjects" when the "user_folder" with id="44" is encountered. The query takes two arguments,
the first will be the "username" of a "dba_user" ancestor of the current node, the second will be the word "TRIGGER".
2.4. "metadata" element
Meta-data elements are used to populate the attribute-list of a node with additional data that can be generated by means
of executing another query. Similar to the "taxdef"
element they can take three attributes, all
of which are optional:
- level, the Level of the hierarchy this rule applies to
- nodetype, the Node Type of the node this rule applies to
- nodeid, the Node Identifier of the node this rule applies to (requires nodetype attribute)
For example:
In an exactly similar fashion to taxdef elements, the metadata elements are sorted by the Taxonomy Engine in order of precedence (depending on how specific to a node they are):
"taxdef" attributes | Rule Applies To... | ||
---|---|---|---|
level | nodetype | nodeid | A specific node in the hierarchy which appears at the specified level. All node attributes must match |
nodetype | nodeid | A specific node in the hierarchy appearing at any level | |
level | nodetype | All nodes of the specified Node Type appearing at the specified level of the hierarchy | |
nodetype | All nodes of the specified Node Type appearing at any level | ||
level | All nodes of the specified Level | ||
<none> | Matches any node. This can be used for hierarchies where a recursive relationship exist in the database. |
Hint! Even though the above options are all available, metadata elements are practically more used in combination with the "nodetype" attribute, i.e. it is much more likely to collect additional data depending on the type of a given node rather than the level of the hierarchy a node appears in.
A metadata element can have one or more query child nodes. These child nodes refer to the query definitions of the previous section 2.1 and define the arguments that will be passed to the queries. The values for the arguments come from the meta-data of the current node or its ancestors. A query reference looks like this:
The query node gets a one and only attribute refid which denotes the name of the query definitions
to be used.
Argument nodes work in exactly the same way they work for taxdef elements.
Examples of "metadata" elements
Below you can see two examples of "taxdef" elements. The first example simply calls the "getUserFolders" query when a node of
"dba_user" Node Type is found in the hierarchy.
The second example will call query "getUserObjects" when the "user_folder" with id="44" is encountered. The query takes two arguments,
the first will be the "username" of a "dba_user" ancestor of the current node, the second will be the word "TRIGGER".