Writing your own tool
It is possible to make your own tools for Wandora. To make your own tool you need to make a Java class that implements the WandoraTool interface. Most of the time easiest way to do this is to extend the AbstractWandoraTool class which implements WandoraTool interface and provides some commonly used methods. Wandora Javadocs are also available.
Contents |
AbstractWandoraTool
The simplest way to make your own tool is to extend AbstractWandoraTool class and then implement and override a few methods. Following table lists methods that are most often overridden.
| Method | Description |
|---|---|
| execute(Wandora,Context) | Main method of the tool. In all cases you must implement this method. It should perform all processing of the tool. You can open dialogs for user input if you want to. |
| getName() | This method returns the name of the tool. You should override this method to return the name of your tool. |
| getDescription() | This method returns a description of what the tool will do. You should override this method to return a proper description of your tool. |
| getType() | This method returns the type of the tool which should be one of "generic", "import", "export" or "extract". Default implementation returns "generic" and unless you are making some other kind of tool you don't need to override this method. |
| getMenuIcon() | This method returns the icon to use in menus. If you want to use something else than the default icon, override this method. |
Each tool must have a constructor with no parameters. If you need to do some kind of initialization for the tool, you may also need to override a few more methods.
| Method | Description |
|---|---|
| initialize(...) | Initializes the tool. This is called always after the tool object is created. The method receives as its parameters the WandoraAdmin object, an Options object containing all saved options and a String containing the prefix this tool should use when accessing and saving options. |
| isConfigurable() | Tells if this tools provides a dialog where user can configure the tool. Default implementation returns false so you need to override this if you want the user to be able to configure the tool. |
| configure(...) | If this tool is configurable, this method must be overridden to show the configuration dialog. After user closes the dialog, all options should be written in the options using the prefix given as a parameter. Best way to do this is to call the next method after the dialog is closed. |
| writeOptions(...) | If this tool is configurable, this method must be overridden to write all current options using the prefix given as parameter. Unlike previous method, this method shouldn't open any dialogs or expect user interaction. |
More detailed description of methods and a few more methods that you can override can be found in the AbstractWandoraTool page.
If the tool execution can take a long time, you should try to provide some feedback for the user. Use the log method to show messages. You should also periodically check if the user has aborted the execution. To do this call forceStop method. If returns true, you should abort the execution and return from execute as soon as possible.
Tool context
The execute method receives a Context object as one of its parameters. The context contains objects the tool should modify or inspect. There are many kinds of contexts a tool can use. If the tool modifies topics, then it will probably want to use one of the topic contexts. If it modifies associations then it should use an association context. Depending on what kind of context is used, the context will contain different kinds of objects. You should set the preferred context before invocation of the tool. Best place to do this is in tool constructor. To set the context call setContext method with a new context object. Following table lists some of the more commonly used contexts. Package for all built in contexts is org.wandora.application.contexts.
| Context object | Description |
|---|---|
| LayeredTopicContext | The default context of AbstractAdminTool. The context objects of this context are topics, LayeredTopics to be more specific. If user has selected some topics from a table, context will be those selected topics. It can also be the topic that is currently open or a selected topic in the topic tree. Most of the time this is exactly what the user would expect it to be. |
| TopicContext | Same as LayeredTopicContext but context objects are not topics of the currently selected layer. They will always be Topic objects but might be any implementation of that class. In some cases you want to perform an action specifically on topics of the selected layer in which case you should use this context. |
| ApplicationContext | This context always contains the currently open topic. It will be a LayeredTopic. |
| AssociationContext | This context returns the selected associations in an association table or the associations of the selected topics or the current topic. |
Example tool - HelloWorld
This is a simple tool that just opens log dialog and writes Hello World to the log window.
package org.wandora.application.tools;
import org.wandora.application.contexts.*;
import org.wandora.application.gui.*;
import java.util.*;
public class HelloWorld extends AbstractWandoraTool {
public HelloWorld () {
}
public void execute(Wandora admin, Context context) {
// Next method call initializes the logging system!
setDefaultLogger();
// Ok, this is not necessary but it's nice to have titled log window.
setLogTitle("Hello World Log Window");
// Do the logging!
log("Hello World");
// We want the log window to stay open although tool execution ends. So we need to...
setState(WAIT);
}
public String getName() {
return "Hello World";
}
public String getDescription() {
return "Hello World simply writes Hello World to the log dialog!";
}
}
Example tool - SearchAndReplaceOccurrences
This is a simple tool that searches for a regular expression in occurrences of context topic(s) and replaces matches with some other string. The tool asks for both the regular expression and the replacement string. The input dialogs are shown with a WandoraOptionPane class. This class is similar to the javax.swing.JOptionPane class and has several static methods to show input and message dialogs.
package org.wandora.application.tools;
import org.wandora.topicmap.layered.*;
import org.wandora.topicmap.*;
import org.wandora.application.*;
import org.wandora.application.contexts.*;
import org.wandora.application.gui.*;
import java.util.*;
import java.util.regex.*;
public class SearchAndReplaceOccurrences extends AbstractWandoraTool {
public SearchAndReplaceOccurrences() {
this.setContext(new TopicContext());
}
public void execute(final Wandora admin, Context context) {
String search=WandoraOptionPane.showInputDialog(admin,"Enter search string","","Search and replace");
if(search==null || search.length()==0) return;
String replace=WandoraOptionPane.showInputDialog(admin,"Enter replace string","","Search and replace");
if(replace==null) return;
Iterator iter=context.getContextObjects();
Pattern pattern;
try{
pattern=Pattern.compile(search);
}catch(PatternSyntaxException pse){
singleLog(pse);
return;
}
int counter=0;
while(iter.hasNext() && !forceStop()){
Object cObject=iter.next();
if(!(cObject instanceof Topic)) continue;
Topic cTopic=(Topic)cObject;
try{
for(Topic type : cTopic.getDataTypes()){
Hashtable<Topic,String> data=cTopic.getData(type);
for(Topic version : data.keySet()){
String occurrence=data.get(version);
Matcher matcher=pattern.matcher(occurrence);
occurrence=matcher.replaceAll(replace);
cTopic.setData(type,version,occurrence);
}
}
}
catch(TopicMapException tme){
singleLog(tme);
return;
}
}
if(forceStop()) {
singleLog("Execute aborted!");
}
}
public String getName() {
return "Search and replace in occurrences";
}
public String getDescription() {
return "Tool searches for matches of a regular expression in topic occurrences and replaces them with another string. "+
"Replacement is done with the Java java.util.regex.Matcher.replaceAll method which allows you to refer to mathed "+
"subsequences with with a dollar sign ($). Backslash (\\) can be used to escape literal characters, especially the "+
"dollar sign and backslash itself.";
}
}
