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

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:

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.
vtn Yes If vtn="true" and the query is used in a metadata element, then the first two columns of the result set are considered to contain a "name-value" pair (NVP). The names and the values of all rows in the result set are then added to the given node as metadata. The metadata key is formed as {query_name}.{column_value}, where query_name is the unique identifier of the query, and column_value is the value of the first column of the result set. The value of the second column is used as the metadata value.

If a query definition has only the "name" 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).
xml An "xml" query — like the "text" query — provides for another way of creating a (nearly) static result set. As with the "text" query the contents can be altered at run-time using the ${arg} placeholder. is another type of a nearly static query, i.e. a query that doesn't 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 or XML 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).

The only attribute you can use when defining an "xml" query is:

"text" attributes Optional Description
argplaceholder Yes The default argument placeholder for sql queries is a question mark (?). However, it can be overriden using this attribute to any script may be convenient (e.g. ${arg})

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.

<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.2.2 "text" element

A query that contains a "text" element, describes the full result set within its body. Most importantly, 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.

<query name="getTableFolders" nodetype="table_folder" nodeidcol="id" nodenamecol="name"> <text columns="id, name"> <![CDATA[ 20, 'Columns' 21, 'Indexes' 22, 'Used by' ]]> </text> </query> <query name="getCollections" nodetypecol="name" nodeidcol="id" nodenamecol="name" iconindexcol="iconindex"> <text headerrow="true"> <![CDATA[ id, name, iconindex 0, List, 17 1, Set, 18 ]]> </text> </query>

2.2.3 "xml" element

"xml" query elements, provide an alternative way of describing a result set. Like the "text" queries, it does not require a connection to a database or any other kind of setup. XML elements describe their data using the well-known XHTML elements <th>, <tr> and <td>.

The column names are described in a nested <th><td> group, and the row data are described in multiple nested <tr><td> groups. The <td> element can contain plain text or a CDATA sub-element if the text is required to retain its structure (e.g. line breaks).

The only attribute you can use when defining an "xml" query is:

"text" attributes Optional Description
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 "xml" 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.

<query name="getSets" nodetypecol="name" nodeidcol="id" nodenamecol="name"> <xml> <th><td>id</td><td>name</td></th> <tr><td>0</td><td>Apples</td></tr> <tr><td>1</td><td>Oranges</td></tr> <tr><td>2</td><td>Peaches</td></tr> </xml> </query>

2.2.4 "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:

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 can either:

These query nodes should also define any arguments that should be passed to the queries. The values for the arguments can come from the attributes of the current node or its ancestors.

A query reference has a single attribute called refid which denotes the name of the query definitions to be used and looks like this:

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

An inline query is identical to the query nodes as defined in section 2.1 with the exception that it obviously doesn't require a "name"::

<taxdef ....> <query nodetype="..." nodeidcol="..." nodenamecol="..."> <sql> ... </sql> <argument ... /> </query> </taxdef>

All kinds of queries (SQL, Text, etc.) can be used as "inline queries".

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>

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:

For example:

<metadata nodetype="country"> ... </metadata>

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

"metadata" 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. Exactly like in the "taxdef" nodes, these child nodes can either:

A metadata Query can be either a normal query or a "name-value-pair" (NVP) query. The difference is in the way the results of the query are added as metadata to a node.
A normal query will add keys of the form column_name[n] where "n" is the number of the row (0 is the first row), and the values will be taken from the contents of the column in the result set. A metadata value will be added for every column of the result-set.
A metadata NVP query will add keys from the value of the 1st column of the result-set and values from the 2nd column of the result-set:

Consider a query with the following results:

id, name blue, #00f green, #0f0 red, #f00

If the query is used as a metadata query the following keys and value will be added to the node:

id[0] = blue name[0] = #00f id[1] = green name[1] = #0f0 id[2] = red name[2] = #f00

If the query is used as a metadata NVP query the following keys and value will be added to the node:

<query_name>.blue = #00f <query_name>.green = #0f0 <query_name>.red = #f00

Examples of metadata nodes with references or inline queries are shown below:

<metadata ....> <query refid="MyMetaDataQuery"> <argument ... /> </query> </metadata> <metadata ....> <query name="inlineQuery"> <sql> ... </sql> <argument ... /> </query> </metadata>

Argument nodes for metadata queries work in exactly the same way as for taxdef elements.