RoKlib Library Documentation

Managing the set of conditions responsible for the visibility of components is a cross-cutting concern which should be organized in one central place. The conditions involved usually refer to a lot of different parts of an application. So, instead of spreading visibility management over the whole application, it should be concentrated in a single manager component. Each part of the application which influences one of the Boolean variables x_i should exclusively be responsible for setting the value of this variable and nothing else. In the example above, for instance, the part of the application which loads printable documents should only need to set the values of the two Boolean variables refering to whether a document is loaded and whether the current document is locked. After a document has been loaded by the user, variable x₁ can be set to true indicating that a document is available for printing. If that document is locked, variable x₂ is set to true as well, otherwise it is set to false. However, the decision whether the print option now must be enabled or disabled has to be made elsewhere.

RoKlib supports you with the kind of problem described above with its package info.rolandkrueger.roklib.util.groupvisibility. This package offers you an API which directly aims at solving the problem of managing the visibility of an application's components centrally. It provides methods for organizing a set of Boolean conditions which refer to different parts of an application. You can assemble these conditions into composites of conditions and manage the visibility of component groups with a central manager class using these composite conditions as a basis.

This manager class is implemented by class VisibilityGroupManager in package info.rolandkrueger.roklib.util.groupvisibility. This is the central class for organizing visibility conditions for an application. As its name indicates it manages groups of related components which can be set visible or invisible - and likewise enabled or disabled - based on a particular predefined condition. Switching the state from visible to invisible or from enabled to disabled and vice versa is done automatically by the manager. This does not need to be done manually. You as an application designer only need to declaratively define the conditions for such state transitions and to set the corresponding Boolean variables accordingly when the application state changes.

There are three constituents which take part in centralizing component visibility management. These are in particular the components that can be made visible/invisible or enabled/disabled, a Boolean expression which defines when a component's state has to be switched, and the manager component itself. We're going to look at each of these parts in the following subsections and will discuss how they will be applied, respectively.

public interface IVisibilityEnablingConfigurable extends Serializable {
  void setVisible (boolean visible);
  void setEnabled (boolean enabled);
  boolean isVisible ();
  boolean isEnabled ();
}

public class JButtonEnablementProxy implements IVisibilityEnablingConfigurable {
  private JButton button;

  public JButtonEnablementProxy (JButton pButton) {
    button = pButton;
  }

  public void setVisible (boolean visible) {                                  (1)
    button.setVisible (visible);
  }

  // implement all other methods of IVisibilityEnablingConfigurable accordingly
}

// name idendifier for the component group
private final static String PRINT_GROUP = "PRINT_GROUP";                                      (1)

// create the button objects
private JButton printNow    =  new JButton ("Print");                                         (2)
private JButton printDialog =  new JButton ("Print...");

// create the proxies
private JButtonEnablementProxy printNowProxy    = new JButtonEnablementProxy (printNow);      (3)
private JButtonEnablementProxy printDialogProxy = new JButtonEnablementProxy (printDialog);

// create a VisibilityGroupManager
private VisibilityGroupManager vgManager = new VisibilityGroupManager ();

// add the component proxies to the manager
vgManager.addGroupMember (PRINT_GROUP, printNowProxy);                                        (4)
vgManager.addGroupMember (PRINT_GROUP, printDialogProxy);

Currently, RoKlib offers only one data structure, which is an implementation of a Ternary Search Tree. This is a map with some interesting properties making it most suitable for very fast prefix matching and spell checking operations.

RoKlib's implementation of a ternary search tree comes as a class implementing the java.util.SortedMap interface with one particularity. As opposed to common Java maps, RoKlib's ternary search tree map does only have one generic class parameter which defines the type of the map's value object. The data type of the keys is predefined as having to be a subclass of java.lang.CharSequence. This is due to the nature of ternary search trees which don't use integer hash values to store their map values but instead split up a key's String representation into single characters to form a sort of a character path to the value. Hence, the only sensible key type for a ternary search tree is a textual type.

There are three similar classes available based on the ternary search tree data structure. Two of them are the aforementioned map in a case sensitive and case insensitive version (TernarySearchTreeMap and TernarySearchTreeMapCaseInsensitive). The third one is simply an implementation of java.util.SortedSet<CharSequence> that uses a ternary search tree map as its internal data model. This class TernarySearchTreeSet offers the same features as the ternary search tree map except that it doesn't offer to associate a value with the String data. Thus, a TernarySearchTreeSet is best used when you only need the prefix matching or spell checking feature of a ternary search tree.

Let's have a look at the class structure of these map and set classes.

Figure 3.1. Class diagram for the ternary search tree data classes

You can see that the functionality specific to ternary search trees is declared in two interfaces ITernarySearchTreeQuery and ITernarySearchTreeMap<V>.

Iterable<CharSequence> getPrefixMatch (CharSequence prefix);
Iterator<Entry<CharSequence, V>> getPrefixSubtreeIterator (CharSequence prefix);

Even though most modern web application frameworks go to great lengths to hide the context of the web from the programmer and make writing a web application as natural as writing a desktop application, it often cannot be avoided to also address the particularities of the web. One of these areas is dealing with URLs. In spite of modern web technologies such as AJAX, which abstract away the request-response model of the web, you will often want to handle URLs visited by the user directly. RoKlib assists you in doing so in a structured, accurate and well maintainable way. It lets you define action handlers for every URL that can be visited by the user. To these handlers you add action commands which will be executed when a corresponding URL has been visited. These action handlers are arranged in a tree-like structure which mimics the directory strucure of a website's URL structure.

Before we talk about the classes making up the URL action handling framework of RoKlib, we take a look at the general structure of URLs. We're doing this to gain a better understanding of how the library classes work and why they are handling URLs in their particular way.

The general URL structure of a website is inherently hierarchical. A URL can be seen as an equivalent to a file system path where the first part points to a specific directory and the last part selects one particular file in that directory. We can outline the structure of a website similar to a file system. Let's take a contrived website www.example.com as an example.