Intended audience

This document is intended for people who want to understand how the Coefficient MailForum module works.

Introduction

The Coefficient MailForum module integrates Dithaka into Coefficient to provide mailing list and discussion forum support. Dithaka merges the mailing list and discussion forum concepts, so that all postings to the forum generate email to list subscribers, and all messages sent to the list get added to the discussion forum.

Implementation

The MailForum consists out of the following classes:

MailForum: The MailForum class is the core class of the MailForum module and provides the functionality to:

• create a forum
• subscribe to a forum
• Create and set the settings of a forum.
• Create and send messages.

CoefficientMailet: The CoefficientMailet class extends the ForumMailet from Dithaka and provides methods so that we can get information that is specific to the Coefficient model.

CoefficientUserExpert: The CoefficientUserExpert extends the ClassExpert from Dithaka which provides a means to go from the Resource back to the original class to get information from the original class. Please see description of the Resource Concept in Dithaka. This original class in this case is the CoefficientUser in Coefficient.

CoefficientClassExpert: The CoefficientClassExpert extends the ClassExpert from Dithaka which provides a means to go from the Resource back to the original class to get information from the original class. Please see description of the Resource Concept in Dithaka. The CoefficientClassExpert in this case is used to call methods on a specific module by providing the resource id.

ProjectExpert: The ProjectExpert extends the ClassExpert from Dithaka which provides a means to go from the Resource back to the original class to get information from the original class. Please see description of the Resource Concept in Dithaka. The ProjectExpert class is used to take the resource and then go to the Project object and return information about the project. The information returned by this class can be the projectId or the Project object.

DBUpdateUtil: The DBUpdateUtil is used to move from an older version of the MailForum and Dithaka to a new version. It is used to extend the old model to the new one by adding in the new classes and information that is needed.

Interaction and Integration between MailForum and Dithaka

The MailForum integrates with Dithaka by including the Dithaka jars with its own libraries. It then calls the Dithaka-Base methods to create forums, post messages,etc. It uses the MailGenerator class of Dithaka to create and send out the mail. Dithaka-Base and Dithaka-James are deployed on the JAMES mail server. The Dithaka jars contains a hibernate.properties file that are set-up to use the same database. The database functions as a message bridge between the MailForum module and Dithaka on JAMES. The MailForum module saves the Dithaka classes/data to this database and Dithaka on JAMES reads this table to determine if the mail message it has received is already in the database, if not it adds the message. The MailForum module will read from the databases and see that there is a new message and will display it in the forum web page

The usage of the database as a message bridge is illustrated in the diagram below:

There are two important interactions between the MailForum module and Dithaka. These are:

Interaction when a Forum is created:

A user, usually a administrator or project champion can create a forum. When a forum is created some default settings are assigned to the forum. Each forum has a set of project champions assigned to it. When a user in Coefficient are upgraded to a project champion or degraded, the forum's champion set are updated. This update is done by the use of an event system that has been integrated into Coefficient. After the forum has been created the default settings can be changed. Each Forum class is associated with one MailForumSettings class that stores the default settings for this forum.

Interaction when a message is posted to the Forum:

After a forum has been created a user can post messages to the forum. A forum can have a setting so that only subscribers of the forum my post or read messages in the forum. If a subscribed user post a message to the forum, the MailForum class creates a Message object and can associate it with a Conversation. The MailForum also checks to see if an AliasUser object already exist for the current user. If it does not exist and AliasUser object is created. The real and alias e-mail addresses of the AliasUser are set. An AliasUser is created when a user post a message ( thus the forum allows unsubscribed users to post) or when the user subscribes to the forum.

When the Message object is created it is sent to the MailGenerator class. The MailGenerator class creates the Mail object and sends it on to the SMPT mail server, in this case JAMES. JAMES handles the mail and it passes through some matcher and mailets which is like filters. These add and remove some information to the mail and sends it on the the final recipients. These recipients are the subscribers of the forum.

Integration with Project module

The MailForum module uses the new Coefficient event system to receive event notifications when project membership and roles change. It reacts to these events by ensuring that the list of project champions for the mailing list matches that of the project. The main classes involved in this activity are show below:

When it is loaded, the MailForum creates an instance of ProjectMemberRoleChangeEventHandler (an inner class of MailForum), and registers this handler with the EventHandlerRegistry

The MemberAdmin module is responsible for changing a user's role in the system. When this happens, MemberAdmin publishes an event of type RoleChangedEvent. This event is dispatched to the registered ProjectMemberRoleChangeEventHandler instance, which retrieves the project and champion information from the RoleChangedEvent instance. This information is used to update the champions list.

Known issues and future enhancements

Some know issues:

• When an user is created or when a user posts a message for the first time an alias e-mail address is assigned to the user. This e-mail address is created by a domain name and the user's username. This domain name is assigned by the administrator in Coefficient. When the administrator changes this domain name the alias e-mail addresses of the existing users are not changed. This will need to be corrected by using the new event system. Solutions: add a library to do this and an admin page, add sql scripts or remove the alias domain name from the alias entries in Dithaka and concat the username+alias_domain each time it is needed
• If the real address of the users changes the mailforum needs to be notified so that it can update its entries and that of Dithaka. This is not done at the moment.
• A jar file: coefficient-mailForum4james.jar must be deployed on James when using the MailForum. This jar file contains the following classes from the MailForum module and Coefficient:
  1. Coefficient: CoefficientUser and Role
  2. MailForum: CoefficientMailet, CoefficientUserExpert and ProjectExpert
  These classes are needed to extract information that is relevant to Coefficient.