Skip to end of metadata
Go to start of metadata

Only in DbVisualizer Pro

This document and the Database Profile Framework in general is appropriate only when using the licensed DbVisualizer Pro edition.

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 DbVisualizerXML specification
<ObjectsTreeDef extends="false">
  <GroupNode type="Databases">
    <DataNode type="Catalog">
      <GroupNode type="Schemas">
        <DataNode type="Schema">
          <GroupNode type="Tables">
            <DataNode type="Table"/>
          </GroupNode>
          <GroupNode type="SystemTables">
            <DataNode type="SystemTable"/>
          </GroupNode>
          <GroupNode type="Views">
            <DataNode type="View"/>
          </GroupNode>
          <GroupNode type="Indexes">
            <DataNode type="Index"/>
          </GroupNode>
          <GroupNode type="Triggers">
            <DataNode type="Trigger"/>
          </GroupNode>
          <GroupNode type="Procedures">
            <DataNode type="Procedure"/>
          </GroupNode>
          <GroupNode type="Functions">
            <DataNode type="Function"/>
          </GroupNode>
        </DataNode>
      </GroupNode>
      <GroupNode type="Users">
        <DataNode type="User">
      </GroupNode>
      <GroupNode type="Groups">
        <DataNode type="Group"/>
      </GroupNode>
      <GroupNode type="Types"/>
    </DataNode>
  </GroupNode>

  <GroupNode type="DBA">
    <GroupNode type="ServerInfo"/>
    <GroupNode type="Logins">
      <DataNode type="Login"/>
    </GroupNode>
    <GroupNode type="Devices">
      <DataNode type="Device"/>
    </GroupNode>
    <GroupNode type="RemoteServers"/>
    <GroupNode type="Processes"/>
    <GroupNode type="ServerRoles">
      <DataNode type="ServerRole"/>
    </GroupNode>
    <GroupNode type="Transactions"/>
    <GroupNode type="Locks"/>
  </GroupNode>
</ObjectsTreeDef>

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:

AttributeValueDescription
type The type of node
label The visual label for the node
label1 Optional label which shows additional information about the object
isLeaftrue/falseSpecifies 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
actiondropdrop is useful when extending another database profile to remove the DataNode and all its child nodes
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:

AttributeValueDescription
type The type of node
label The visual label for the node
label1 Optional label which shows additional information about the object
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('mimer.getIndexes.IS_UNIQUE').equals('YES') ? 'uniqueIcon' : (#dataMap.get('mimer.getIndexes.IS_UNIQUE').equals('FK') ? 'fkIcon' : 'indexIcon')"

actiontype Object type used for object actions
isLeaftrue/falseSpecifies 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-outputcontinue/stopIf result set is empty, use this to control whether child GroupNode/DataNodes should be added anyway
actionkeep/dropdrop is useful when extending another database profile to remove the DataNode and all its child nodes
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" name="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 name attribute specifies the label for the filter as it appears in the object type drop-down list.

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.
<DataNode type="Catalog" label="${getCatalogs.TABLE_CAT}">
  <SetVar name="catalog" value="${getCatalogs.TABLE_CAT}"> 
</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.

  • No labels