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).

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>

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:

<taxonomy id="My First Taxonomy"> ... </taxonomy>

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.

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:

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 contain a child node named sql which contains a CDATA element enclosing the query text and can take 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.

Examples of "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.

<query name="getUserSynonyms" nodetype="synonym" nodeidcol="synonym_name" nodenamecol="synonym_name"> <sql> <![CDATA[ select * from dba_synonyms where owner = ? order by lower(synonym_name) ]]> </sql> </query> <query name="getUserObjects" nodetypecol="nodetype" nodeidcol="object_id" nodenamecol="object_name"> <sql> <![CDATA[ select dba_objects.*, lower(object_type) as nodetype from dba_objects where owner = ? order by lower(object_name) ]]> </sql> </query>

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:

For example:

<taxdef level="0"> ... </taxdef> <taxdef nodetype="country"> ... </taxdef>

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:

<taxdef ....> <query refid="MyQuery"> <argument ... /> </query> </taxdef>

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".

<taxdef nodetype="dba_user"> <query refid="getUserFolders" /> </taxdef> <taxdef nodetype="user_folder" nodeid="44"> <query refid="getUserObjects"> <argument nodetype="dba_user" columnname="username" /> <argument value="TRIGGER" /> </query> </taxdef>