XML element - ObjectsTreeDef
The ObjectsTreeDef element section controls how the database objects tree should be presented and which commands should be executed to form its content (nodes).
<ObjectsTreeDef extends="false">
<GroupNode type="xxx" label="xxx">
<DataNode type="yyy" label="yyy">
...
</DataNode>
</GroupNode>
</ObjectsTreeDef>
Setting the extends attribute to "true" attribute specifies that the ObjectsTreeDef will extend the ObjectsTreeDef definition in the profile being extended.
The mapping between the graphical representation in DbVisualizer and its ObejctsTreeDef XML is as quite straight forward:
| Representation in DbVisualizer | XML specification |
|---|---|
 | <ObjectsTreeDef extends="false"> |
The screenshot in the above example show all nodes representing the GroupNode definitions in the ObjectsTreeDef. One exception is the Logins object, which has been expanded (jstask, probe and sa child objects) to illustrate how DataNode objects look like. The ObjectsTreeDef in the example has been simplified to show only the type attribute. (The label of the nodes as they appear in the screenshot is not listed in the example XML). The difference between a GroupNode and a DataNode is that GroupNode represent a static object in the tree while DataNode is dynamically created based on result sets produced by running a SQL statement. See GroupNode as a container holding other GroupNodes and DataNodes.
The database objects tree in DbVisualizer is the core visual component and it is the place where the user open object details and launch actions. To connect object actions and object views with a node in the objects tree, the type attribute is used. The type should be a descriptive word for a node such as Table, Schemas, MaterializedQueryTable, and so on. The type also map to a predefined icon. Check the database profile utilities for information how to show all bundled icons and their type mappings.
There is no limitation on the number of levels in the objects tree expressed by nesting GroupNode and DataNode elements. A good rule is as always to keep it intuitive, simple and clean.
XML element - GroupNode
The GroupNode element represents a static object in the tree. A GroupNode do not have any associated SQL and appear only once where they are defined. A GroupNode is primarily used for structural and grouping purposes. The GroupNode element have the following attributes.
<GroupNode type="SystemTables" label="System Tables" isLeaf="false">
...
</GroupNode>
The isLeaf attribute is optional (default is false) and controls whether the GroupNode may have any child objects or not. It can always be set to false, the effect in the visual database objects tree is then that an expand handle always will be visible next to the icon, even if the node don't have any child nodes.
If isLeaf is set to true and there are child Group and/or Data -nodes, these will not appear. The result may cause some frustration during the design of the database profile.
The complete set of attributes for the DataNode element:
| Attribute | Value | Description |
|---|---|---|
| type | The type of node | |
| label | The label attribute must identify the object apart from other objects. This label should uniquely identify the object in the list of objects for the same parent node. It is used as part of the object identifier when opening object view tabs. | |
| label1 | Optional label which shows additional information about the object | |
| isLeaf | true/false | Specifies if the node cannot have child objects |
| icon | Icons are typically mapped using the type attribute with an icon name in the icon.prefs file(s). The icon attribute for a GroupNode can be set to specify an alternative icon. Conditions can be used to identify alternate icons (see below) | |
| drop-label-not-equal | Do not add the node if the label is not equal to this value or variable | |
| drop-on-condition | Read more in drop-on-condition attribute | |
| order-before | Specifies the order of this GroupNode among a collection of nodes having the same parent node. It can either be an index starting at 0 (first) or a node type. Ex. order-before="Views" will order this GroupNode before nodes defined by the type="Views" attribute | |
| order-after | Specifies the order of this GroupNode among a collection of nodes having the same parent node. It can either be an index starting at 0 (first) or a node type. Ex. order-after="0" will order this GroupNode after the first node definition |
XML element - DataNode
The DataNode element feeds the tree with nodes produced by a Command. The example in the Command section querying for all logins in Sybase ASE look as follow in the ObjectsTreeDef:
<GroupNode type="Logins" label="Logins">
<DataNode type="Login" label="${sybase-ase.getLogins.Name}" isLeaf="true">
<Command idref="sybase-ase.getLogins"/>
</DataNode>
</GroupNode>
First, there is a GroupNode element with the purpose to group all child objects in a Logins node. The DataNode in this example have the same attributes as the GroupNode, the type is however singular Login instead of plural Logins (as it is for the GroupNode). This difference is important when the user decide to open one of the nodes, since the object view will show the matching views based on the object type. For Logins a list of all logins is displayed while opening a Login, details for that specific login is displayed.
The DataNode definition can be seen as a template, as the associated command fetches rows of data from the database and DbVisualizer uses the DataNode definition to create one node per row in the result set.
The label attribute for the data node introduce the use a variable. The real value for the label will, in this example, be the value in the Name column produced by the sybase-ase.getLogins command (variable names are automatically prefixed with the command id that produced them).
The Command element uses the idref attribute to identify the command that should be executed. The command in this case produce a result set with 3 rows and 8 columns. The result will be two nodes for each row, with the label of the Name column in the result set.
The label1 attribute can be set to any other valid variable, a combination of several variables or even static text:
label1="${sybase-ase.getLogins.Default Database}"
The example above results in the following labels:
jstask master
probe subsystemdb
sa master
The complete set of attributes for the DataNode element:
| Attribute | Value | Description |
|---|---|---|
| type | The type of node | |
| label | The label attribute must identify the object apart from other objects. This label should uniquely identify the object in the list of objects for the same parent node. It is used as part of the object identifier when opening object view tabs. | |
| label1 | label1 should show useful additional information about the object. For column objects, it typically shows generic information about the columns. For index objects it typically shows the source table name. | |
| icon | Icons are typically mapped using the type attribute with an icon name in the icon.prefs file(s). The icon attribute for a DataNode can be set to specify an alternative icon. A condition can be specified which is used to choose an icon based on evaluating other variables for the node. Ex: icon="#dataMap.get('getColumnDefinitions.IS_PRIMARY_KEY') eq true ? 'PrimaryKey' : 'Column'" | |
| tip | An optional description that is displayed when hovering the node. This is useful to describe why a different icon is displayed for the node using the icon attribute. Ex: tip="#dataMap.get('getColumnDefinitions.IS_PRIMARY_KEY') eq true ? 'This is a primary key column' : ''" | |
| actiontype | Object type used for object actions | |
| isLeaf | true/false | Specifies if the node cannot have child objects |
| drop-label-not-equal | Do not add the node if the label is not equal to this value or variable | |
| stop-label-not-equal | The node will be a leaf if the label doesn't match the specified value or variable value | |
| warnstate | A condition expression returning either true or false. For true, show a warning overlay icon for the node. Ex: errorState="!#dataMap.get('oracle.getTriggers.STATUS'). equals('ENABLED')" | |
| errorstate | A condition expression returning either true or false. For true, show an error overlay icon for the node. Ex: errorState="!#dataMap.get('oracle.getObjectsByType.STATUS'). equals('VALID')" | |
| is-empty-output | continue/stop | If result set is empty, use this to control whether child GroupNode/DataNodes should be added anyway |
| drop-on-condition | Read more in drop-on-condition attribute | |
| order-before | Specifies the order of this DataNode among a collection of nodes having the same parent node. It can either be an index starting at 0 (first) or a node type. Ex. order-before="View" will order this node before nodes defined by the type="View" attribute | |
| order-after | Specifies the order of this DataNode among a collection of nodes having the same parent node. It can either be an index starting at 0 (first) or a node type. Ex. order-after="0" will order this DataNode after the first node definition |
The Command definition in the example above is simple, since it doesn't use any variables in the SQL. Continue reading the next section for details about passing input data to commands.
XML element - Command
The SQL used to generate the data used by the DataNodes are defined in the Command element.
A command is referenced by the idref attribute and that id must already be defined in the Commands section of the profile. For most DataNode definitions input must be supplied with the command and this is done by adding Input elements as children to the Command.
<DataNode type="Login" label="${sybase-ase.getLogins.Name}" isLeaf="true">
<Command idref="sybase-ase.getLogins">
<Input name="name" value="sa">
<Input name="suid" value="${sybase-ase.getProcesses.suid}">
</Command>
</DataNode>
The value for a variable specified in an Input element is evaluated using the syntax outlined in the result set section.
For detailed information about the capabilities with the Command element, check the Command section.
XML element - Filter
The Filter element is specific for Command elements that appear in the DataNode element. A filter define which data for a DataNode that can be searched in filter. This filter functionality is commonly referred as the Database Objects Tree Filtering in DbVisualizer. The filtering setup appears below the database objects tree, and the following example shows that filtering may be specified for these object types:
- Catalog
- Table
- System Table
- View
- User
- Group
- Trigger
- Procedure
For each of the filter definitions, one or several columns can be included in the filtering criteria.
<DataNode type="View" label="${sybase-ase.getViews.Name}" isLeaf="true">
<Command idref="sybase-ase.getViews">
<Filter index="TABLE_NAME" label="View Table"/>
</Command>
</DataNode>
The above filter definition specifies a filter for the Catalog (database) object type. The index attribute should specify a column name or index in the result set while the label attribute is the name how it appears in the object type drop-down list.
Show only Default Database/Schema
This generic action available with any profile uses a special filter definition that must be declared for Show only Default Database/Schema to work:
For Catalog objects (name="Name" is the required name while index should identify the column in the result set):
<Filter>
<Column index="TABLE_CAT" name="Name"/>
</Filter>
For Schema objects (name="Name" is the required name while index should identify the column in the result set):
<Filter>
<Column index="TABLE_SCHEM" name="Name"/>
</Filter>
XML element - SetVar
The SetVar element is used in the ObjectsTreeDef for GroupNode and DataNode elements. Some object types have special meaning in DbVisualizer. Two examples are the Catalog and Schema object types. For DataNode objects, you must use SetVar elements to identify them with the name attribute set to catalog or schema, respectively.
Catalog:
<DataNode type="Catalog" label="${getCatalogs.TABLE_CAT}">
<SetVar name="catalog" value="${getCatalogs.TABLE_CAT}">
</DataNode>
Schema:
<DataNode type="Schema" label="${getSchemas.TABLE_SCHEM}">
<SetVar name="schema" value="${getSchemas.TABLE_SCHEM}">
</DataNode>
All DataNodes except Catalog and Schema must use SetVar to set the objectname variable:
<DataNode type="View" label="${sybase-ase.getViews.Name}" isLeaf="true">
<SetVar name="objectname" value="${sybase-ase.getViews.Name}">
<SetVar name="rowcount" value="true">
</DataNode>
The objectname variable is used to identify the object represented by the data node, so that it can be uniformly referenced in object views and object actions. Its value should be the identifier for the object as it is identified in the database, for example a table name or view name.
The rowcount variable is optional (default is false) and controls whether the object supports showing row count information when Show/Hide Table Row Count right-click menu choice is enabled for the database connection.
Another optional variable (not shown in the example above) is named acceptInQB (default is false). If set to true, nodes of this type can be used in the Query Builder. It should only be set to true for object types representing tabular data that can be queried with an SQL SELECT statement, such as tables, views, materialized views, etc.
Variables defined with SetVar are by default invisible in for example the node form viewer. If you want to override this behavior then add the action attribute and set its value to show. If you want to drop a variable completely from the node simply set the action attribute to drop.
Using SetVar for GroupNode's is used to set static values (since GroupNode's doesn't execute a Command). This may be used to pass a static value for later use in an Action or DataView. See vertica.xml which illustrates using SetVar for GroupNode's.