Custom topic panel

Revision as of 16:02, 13 February 2008

Custom topic panel is one of several available topic panels in Wandora. Custom topic panel can be customized to suit the needs a specific topic map.

Configuration

Query language

Introduction

Wandora does not use any standard query language. Instead queries are done by invoking a method of a Java class implementing a certain interface. The class may then perform anything whatsoever as long as in the end it returns query results in the format specified by the Java interface. Wandora does however include a number of classes designed in a way that makes it possible to build complex queries by combining these simple predefined query directive classes. This somewhat resembles a traditional query language.

The queries are defined using a generic scripting language. Wandora uses Java scripting API so it should be possible to use a number of different languages. Examples in this article use Mozilla Rhino 1.6 language that should be found in most installations. This scripting language uses a syntax that is identical to regular Java syntax in nearly every way. Because of this you should be at least somewhat familiar with Java syntax to understand the examples on this page.

As an example, the default configuration contains the following query:

 1 importPackage(com.gripstudios.applications.wandora.query);
 2 importPackage(com.gripstudios.applications.wandora.topicmap);
 3 new RecursiveDirective(
 4     new RolesDirective(
 5         new IsContextTopicDirective(
 6             new SelectDirective(XTMPSI.SUPERCLASS_SUBCLASS,
 7                                 XTMPSI.SUPERCLASS,XTMPSI.SUBCLASS),
 8             XTMPSI.SUBCLASS),
 9         XTMPSI.SUPERCLASS),
10     XTMPSI.SUPERCLASS
11 );

The first two lines import needed packages. This is one of the few exceptions where syntax is different to normal Java syntax. The query package contains the predefined directives, the topicmap packages contains the XTMPSI class which contains some subject identifiers as static variables. The rest is the actual query definition technically all in one line but broken on several lines for readability. The query is defined by constructing several directives inside one another.

The query is executed selecting different sets of topics in the topic map using a specified context topic as the basis of the selection. Starting with the innermost directive on lines 6 and 7 in the above example, this directive selects topics that are found with association type SUPERCLASS_SUBCLASS and are players with either role SUPERCLASS or SUBCLASS. These should usually be the only players of the association, and the context topic will be one of these. This directive alone is a valid query and the result is a table that is identical to the superclass-subclass table in traditional topic panel, i.e. it contains all associations of type superclass-subclass that are related to the context topic and for all association both players are included.

The next directive on lines 5 to 8 is a filtering directive that removes certain rows from the results the directive inside it, in this case the select directive. This directive only includes rows where a certain topic is the same topic as the context topic. What topic is compared to context topic is defined as the second parameter of the constructor on line 8, in this case the topic with role SUBCLASS. Again, this directive is a valid query on its own (with the select defined inside it of course). It will select only those superclass-subclass associations where context topic is the subclass.

Next directive on lines 4 to 9 filters columns, or roles, in the query defined inside it. It only includes columns with label SUPERCLASS. We previously only included rows where subclass is the context topic itself so that column is a bit redundant to show. Again this is a valid query on its own.

The outermost query is the most complex in this example. It recursively applies the query inside it to different contexts and collects all the results. It starting with the context of the query itself, that is the topic where this query is executed. After that it applies the same query but uses results of previous execution as the context, each individually. The second parameter specifies which topic of the query result is used as context for further queries. The directive collects the results of each query execution in a single collection, removing duplicate rows however. The directive is smart enough not to get caught in infinite loops. When there are no new rows found, the query terminates and returns all rows it collected. The inner query finds all super classes of the context so this query then recursively finds all super classes, all super classes of super classes and so on.

The example above is a typical example of how to build a query. The innermost query is often a SelectDirective or InstancesDirective. SelectDirective selects topics using associations of a specified types and including topics of specified roles. Only associations related to the context topic are considered. InstancesDirective selects all instances of the context topic. Results of the inner query can then be filtered with other queries. Another typical example is joining several queries together by using results of one select as context for another.

 1 importPackage(com.gripstudios.applications.wandora.query);
 2 importPackage(com.gripstudios.applications.wandora.topicmap);
 3 new UnionDirective(
 4     new RolesDirective(
 5         new JoinDirective(
 6             new RecursiveDirective(
 7                 new SelectDirective(XTMPSI.SUPERCLASS_SUBCLASS,XTMPSI.SUBCLASS),
 8                 XTMPSI.SUBCLASS),
 9             XTMPSI.SUBCLASS,
10             new InstancesDirective()),
11         XTMPSI.INSTANCE)
12 );

Here lines 7 to 8 specify a similar recursive query as in previous example. In this case subclasses are selected recursively instead of super classes. Lines 5 to 10 contain a JoinDirective. This directive executes one directive using results of another as the context. The first constructor parameter is the source directive, next parameter defines what topic of the source results are used as context for next query and third parameter is the next query. In this case all instances of all subclasses (subclasses selected recursively) are returned. The other queries are only used to tidy the results. RolesDirective removes all but the instance column and UnionDirective when used with only one parameter removes duplicate rows. UnionDirective could also be used to combine results of several queries.

Directives