The tree node's user data object

To build a tree, you insert a root node, add children to it, add children to those children, and so on. Swing manages the links between nodes and dbSwing manages the data-awareness. In addition to the information it needs for housekeeping, Swing lets you put one object, the user data object, in each node.

Goals for a user data object: Your biggest decision is what the user data object should contain. Ideally, it will satisfy these conditions:

A String data object: If your data meets these conditions, it will be a String. This is good. It's easy to build a tree when the user data object is a String because Swing and dbSwing do more of the work: Swing uses the String as the caption for the node, and dbSwing can find the node that matches a data value from the data set without any help from you. The tree for this help system is close to this ideal. Our user data object is a String, but it is a value like "\Overview\MainCategory\TopicName". We want to display only "TopicName" in the tree, so we do need a cell renderer.

When your data object is not a String: Often, you won't be able to satisfy all the conditions for node data of type String. For example, you might plan to use a unique numeric code to represent each node. You'll put just this code in the data set column that your tree is bound to, and you'll put the code and a String interpretation of it in the tree node. In this case, you have to do three tasks that weren't necessary in the simpler case above:

  1. Define a class - we'll call it MyNodeObject - containing these two data items and any methods you need that manipulate them. Make MyNodeObject the user data object in the tree node.
  2. Override the default definition of equals() in MyTree. JdbTree and JdbNavTree use equals() to compare values in the tree with values in the data set. Because equals() returns true only for identical object instances, dbSwing will never find a match. Your version of equals() should compare the value from the data set column with the corresponding value from an instance of MyNodeObject. In this example, we specified that you store a numeric code and a string in MyNodeObject, but only the numeric code in the data set. This is common: the value in the data set is smaller and easier to work with, and you can look up its interpretation when you need it. So your equals() method should extract the numeric code from MyNodeObject and compare it to the value from the data set.
  3. Because MyNodeObject is not a String, you'll need to define a cell renderer that displays an appropriate String translation of it in the tree.

To summarize: If the data you want to carry in each node of a tree can be a simple, unique string, working with the tree is easy. If the data is a String but doesn't work well as the node's caption, add a cell renderer. If it's a code, or several data items, Swing and dbSwing can't interpret your user data object without help, so you must