columba 1.4

See our wiki for a complete reference of all configuration options.

Configuration files can be found in /addressbook. This includes currently options.xml, tree.xml and main_toolbar.xml.

All config-files can be accessed in using AddressbookConfig.get(String) method.

Columba uses the CommandReference pattern. Where {@link Command} instances are decoupled from their References ({@link DefaultCommandReference}). Actions ({@link FrameAction}) start Commands and pass the appropriate Reference to them.

This is Preclaiming Scheduler implementation. Meaning tasks get queued until all resources they need are free at once. Which is no problem, because for example a "copy message from folder a to folder b" operation needs only two resources: folder a and folder b.

The org.columba.core.command.Command class has two methods. Execute() is for time consuming background tasks, updateGUI() is called after the execute-method is finished (the thread is finished). The nice thing about updateGUI() is that is called in the awt-event dispatcher thread. It is therefore thread-safe, and can be used to update the gui.

Note, that execute() has {@link Worker} in its signature, which has a couple of methods to display a text in the {@link Statusbar}, or updating the progressbar.

Worker registers at the {@link Taskmanager}, which is basically the model for {@link Statusbar}. We use an easy listener pattern to register all the workers.

This makes it easy for commands to send status updates.

Then we have actions in org.columba.core.action. These provide the glue between the gui-elements and the commands. An action initializes a command and passes it along to the Processor (task scheduler {@link DefaultProcessor}) to execute.

You can find many examples in the packages ending with "action" and "command". Adapting, this schema should be pretty easy for developers.

{@link MailConfig} and {@link AddressbookConfig} are just helper classes which register their configuration files at {@link Config}. This can be seen in the configuration directory structure of the user's configuration directory. Where mail and addressbook have their own folders for storing preferences.

Example on how to get a {@link XmlElement}xml treenode:

  
  XmlElement gui = MainInterface.config.get("options").getElement("/options/gui");
  

This would address the file options.xml . Following a little example on how this file would look like:

  
   <?xml version="1.0" encoding="UTF-8"?>
    <options>
     <gui enabled="true">
      .. your options here
     </gui>
    </options>
   
  

Using the Facade pattern.

This includes language, toolbar style, Look and Feel, font settings, etc.

org.columba.core.action.menu.xml defines the core menu, mail and addressbook define their own menu.xml, which extend the core menu.

We therefore added placeholders we called extensionpoint, which are used by mail/addressbook to address the location where they plug themselves in the core menu.

Note, that the swing menu code is kept separated from the code which actually creates the menu - the generator classes.

{@link MenuPluginHandler} is responsible to handle all the plugins.

The toolbar is created, by using the toolbar.xml file and the actions classes already used to create the menus. As with the menus mail/addressbook just extend the toolbar.

Adding context-specific help to a button

 HelpManager.enableHelpOnButton(helpButton, "configuring_columba");

Looking up topic ID

I've used a very general schema to generate topic IDs. Following a couple of examples, so you don't need to lookup every single topic ID:

• index -> index (index.html)
• introduction -> introduction (ch01.html)
• installation -> installing (ch02.html)
• installation_1 -> installating-windows (ch02.html)
• installation_2 -> installating-linux (ch02_2.html)
• installation_3 -> installating-generic (ch02_3.html)
• using_columba_composing_new_email_messages_2 -> composing new email messages (ch04s03.html)

Note, that we are most probably replacing log4j with the java.util.logging package already shipped with jdk1.4

The extensibility system provides a framework for both, providing extensibility hooks, and for extending the functionality of Columba.

A plugin is a bundle of extensions. An extension provides an implementation of a specific functionality.

The {@link IPluginManager} manages all plugins as a singleton registry. Additionally, it is also a registry for all available extension handlers. {@link IExtensionHandler} is a registry for extensions. It resembles an extension point or hook to extend Columba's functionality. {@IExtension} provides the metadata, describing an extensions. Additionally, it is responsible for instanciating an extension. Every extension must implement the interface {@link IExtensionInterface}.

When looking at {@link IExtensionHandler}, its obvious that it simply resembles a registry for classes. All extensions have a unique id and the classname. The extension handler keeps a hashtable of all extensions and uses a custom classloader to instanciate extensions.

All extension handlers use xml files which can be found in /res directory. This is merely an easy way to specify extensions easily, without hardcoding them in Java. A list of all extension points for the core package can be found in: org.columba.core.plugin.pluginhandler.xml. All core extension handler files can be found in org.columba.core.plugin.

This is an example extension handler file:

Usually, when making use of extensions in Columba, you first get an instance of the plugin manager using PluginManager.getInstance(). Then you have to retrieve an appropriate extension handler getHandler(id). Using this handler, you get the extension using IExtensionHandler.getExtension(id). Now, you instanciate the plugin using IExtension.instanciate().

// use a path-like navigation to get the interesting option
// first part is getting the file "options.xml" from the "mail" directory (MailOptions)
// we also have the same for addressbook -> AddressbookOptions
// second part address the xml-treenode "/options/gui/html"
XmlElement preferHtml = MailConfig.get("options").getElement("/options/gui/html");

// register as observer
preferHtml.addObserver(this);

// example of getting a property
String enableHtml = preferHtml.getAttribute("enable"); 

Every folder class subclasses {@link FolderTreeNode}, which is basically only a mutable treenode, which uses the tree.xml configuration file as {@link TreeModel}.

Unlike {@link FolderTreeNode} which doesn't contain messages, {@link Folder} should be subclasses by every mailbox.

{@link LocalFolder} is used by all local folders and builds a plugin-like approach to make it easy to add new mailbox formats in the futue.

{@link FolderFactory} follows the factory pattern in providing methods to create new folders.

Folder shouldn't be accessed directly. Instead we use {@link FolderCommand}, which in conjunction with {@link FolderCommandReference} provide a looking facility. This makes sure that only one {@link Command} at a time can modify the folder's data.

As explained in org.columba.command, {@link DefaultProcessor} is a preclaiming schedular. FolderCommandReference keeps a list of folders involved in the operation the Command executes. DefaultProcessor will only start the Command if all folders (resources) can be claimed at once.

{@link DefaultSearchEngine} is using filter plugins to perform search requests.

Every {@link QueryEngine} implementation supports a subset of search requests, for example searching in the body or subject of a message.

{@link DefaultSearchEngine} is also the fall-back for every search request which is not performed by implementations of {@link QueryEngine}.

We use composition to plug the {@link QueryEngine} in the {@link DefaultSearchEngine}, using a {@link DummyQueryEngine} which doesn't support any special search requests, as default.

This includes, which columns to show in the message-list. The sorting order, filter properties, enabling/disabling of the threaded-view, etc.

In Columba we never change the message contents, is always saved in the mailbox as it is. But decryption of messages makes it necessary to modify the original message. Therefore a temporary folder is used where the modified message is saved. All references are re-mapped to this temporary folder. This makes it possible to execute all actions on this message as if it would be the original.

Follow these steps if you want to listen to table selection changes:

• Listener should implement SelectionListener
• This also means overwriting public void selectionChanged(SelectionChangedEvent e)
• Don't forget to cast SelectionChangedEvent to TableSelectionChangedEvent

Follow these steps if you want to listen to tree selection changes:

• Listener should implement SelectionListener
• This also means overwriting public void selectionChanged(SelectionChangedEvent e)
• Don't forget to cast SelectionChangedEvent to TreeSelectionChangedEvent

Users enables spam filter on a per-account basis in the account options dialog. {@link SpamItem} keeps all options.

Several commands where modified to plug the spam filter into Columba, without adding additional actions. The user only has to mark messages as spam or not spam to train the spam filter. Additionally to {@link MarkMessageCommand}, {@link AddPOP3MessageCommand} was modified to score new messages downloaded from POP3 servers.

Spam token database is saved in /mail/spam.db.