Become efficient with Coefficient

The Coefficient platform offers developers open source collaboration software

Online collaboration such as Yahoo! Groups and file sharing are becoming more and more popular. As software projects become more sophisticated, increased interaction among users is becoming more important to system owners. Developers are not only developing collaboration functionality for clients, they are also relying on the same functionality for different tasks, for example, bug tracking and sharing of requirements documentation.

Coefficient is an extensible Java platform for online collaboration software. It comes with a set of built-in functionalities that allow you to create projects immediately. Coefficient uses the term projects, but in other contexts, projects are also called groups, workspaces, or share spaces.

Coefficient is open source (released under the Lesser General Public License, or LGPL). This allows you to freely modify and distribute the platform as part of your business.

Download and installation

Coefficient can be run either in an EJB (Enterprise JavaBeans) server or as a standalone servlet. In this article, I concentrate on the EJB version, but you can refer to the Coefficient documentation for the servlet version. Coefficient has been tested with JBoss and Tomcat, but it should be able to run in most EJB containers.

Prepare JBoss for Coefficient by creating a new datasource. The datasource should be called CoefficientDS and should point to an existing database. You need not create any tables in the database—Coefficient will do that for you.

To install Coefficient, download and extract the archive to a directory of your choice. Copy the coefficient.ear file to your JBoss deployment directory to deploy the core Coefficient runtime. To deploy the different modules, copy the specific .ear files from the modules directory to your JBoss deployment directory.

Assuming you use a default JBoss setup, point your browser to http://localhost:8080/index.html and Coefficient will load. The first screen should prompt you for some configuration details. The SMTP Server setting is the only important setting at this stage. It tells Coefficient which Simple Mail Transfer Protocol server to use for account confirmation email. For the rest of the configuration, defaults will do. Refer to INSTALL.txt for more installation details.

Now you are ready to start with Coefficient!

Configure Coefficient

First things first: log in as the Admin User (password is "admin"), click on Edit Details, and then on Change Password. Select a sensible password for the administrator.

Each project in Coefficient can have numerous attributes. These attributes are used by users to search for specific projects and prove handy if you have many projects. Click on Attribute Search to see how the search interface works. As an administrator, you can define the attributes assigned to projects.

Click on Attributes to manage project attributes. The default Coefficient attributes are based on the attributes used on SourceForge.net and will probably not meet your requirements. Delete the attributes you don't need and add the ones you do. Choose attributes that will help users search for projects.

Projects can be categorized in a hierarchal set of categories. As with project attributes, this structure proves most useful if you expect to have a large number of projects. To set up categories (only administrators can do this), click on Category Management.

Any user can attempt to create a project, but before the project becomes active, an administrator must confirm the project. Click on Confirm Projects to confirm new projects created by users. At this stage, no projects should require confirmation.

Finally, click on Log Out.

Using Coefficient

You are now ready to start using Coefficient. To create a new user, click on Create User Account at the main screen and enter the requested details. The user will receive a confirmation email. After confirmation, the user can log in and use Coefficient. Users can create new projects, but can only start using them when an administrator has confirmed the projects. The best way to learn about Coefficient is to experiment.

Features provided by the default Coefficient installation are:

  • Vote: A basic opinion poll module
  • Discussion: An online threaded discussion forum
  • File upload: Arbitrary file uploads and downloads
  • News: Shows news items to users
  • Issue tracker: Tracks bugs and other issues (Bugzilla)

Build Coefficient

The following sections will only be of interest to you if you plan to alter or extend Coefficient. Before you start, delete all the Coefficient .ear files from your JBoss deploy directory and clean out your Coefficient database. This will ensure that any version incompatibilities are resolved early on.

The first step is to download the source code from the Coefficient Website and extract it to a directory of your choice. This directory will be referred to as $COEFFICIENT_HOME for the remainder of this article.

You will need a JDK and the Apache Ant build tool installed to build Coefficient. The Coefficient build process extensively uses XDoclet, thus, a good working knowledge of XDoclet will help with Coefficient development (see Resources for more information on XDoclet).

The first step is to build the Coefficient core. Create a file called build.properties in the Coefficient base directory—use build.properties.sample as a template and point it to the correct directories. From $COEFFICIENT_HOME, run ant deploy. This should build the Coefficient core and deploy it to your JBoss deployment directory.

Now you need to build the Coefficient modules. In $COEFFICIENT_HOME, you will find a subdirectory called modules and a subdirectory for each module. For each module, you also need to create a file called build.properties, based on the build.properties.sample file in each module's subdirectory.

An Ant task called deploy-all-modules deploys all the modules in the modules directory. I prefer not to use this task because you cannot control the sequence of deployment, and some modules may depend on other modules. Go to each module directory, for example, $COEFFICIENT_HOME/module/vote/, and run ant deploy.

This will deploy each module to the JBoss deployment directory. Coefficient is able to "hot-deploy" modules, meaning that you don't have to restart JBoss or do anything else for the modules to become available. You can also "hot-undeploy" modules by simply removing the .ear files from the deployment directory. Coefficient will discover that the module has been removed and simply remove the functionality. Hot deploy will only work for the EJB version, not the servlet version.

For more details on the build process, see INSTALL.txt in the Coefficient base source directory.

Create a custom module

The most common way to extend Coefficient is to create new modules. For this article, I'm going to develop a simple Wiki module for Coefficient. My Wiki processor is fairly unsophisticated, but good enough to illustrate the development of a Coefficient module. The full source code for this module can be downloaded from Resources.

To start a new module, download sample.jar from the Coefficient Website and extract it into your $COEFFICIENT_HOME/modules/ directory. The sample.jar file contains an example framework for a new Coefficient module.

Rename /modules/sample to modules/wiki; this directory will contain everything for the Wiki module. Edit the application.xml file and change the references from sample to wiki. This is very important for the module name identifies the module to the build process as well as the Coefficient runtime at a later stage. Also update the build.properties file to point to the relevant directories and module names.

You can safely delete the .java files currently in the wiki source directory, unless you'd like to keep them for reference. To create the code for the new Wiki module, you must extend BaseModule as shown here:

/**
 * @pojo2ejb.class 
 *   name="Wiki"
 *   jndi-prefix="za/org/coefficient/navigation/"
 *   interface-extends="za.org.coefficient.interfaces.Module"
 *   interface-local-extends="za.org.coefficient.interfaces.ModuleLocal"
 *
 */
public class Wiki extends BaseModule {
    
    private String wikiText;
    
    public Wiki() {
      wikiText = "This is a *wiki* _page_ ";
    }
    
    public String getModuleDisplayName () {
        return "Wiki";
    }
    public String getModuleDescription () {
        return "Sample Module";
    }
    public String getMainMethod () {
        return "display";
    }
    
    // Some code removed....
}

Some notes about the code:

  • The first thing you will notice is the XDoclet tags in the class's comment section. Refer to the XDoclet homepage for more information about XDoclet.
  • The @pojo2ejb.class tag tells Coefficient how to convert the Wiki class to a stateless session bean implementation (in the case of JBoss deployment).
  • The Coefficient runtime discovers different modules by their JNDI (Java Naming and Directory Interface) names. In this case, the JNDI prefix allows the module to be part of the navigation or menu bar. If your JNDI prefix is incorrect, the module will not appear in the menu. The JNDI name is also used to indicate other types of modules (more on this later).
  • If you plan to deploy Coefficient as a servlet only, you also must add @web.resource-env-ref tags as well. Refer to Sample.java for an example.
  • All Coefficient modules must implement the ModuleLocal interface. BaseModule is a handy base class that implements ModuleLocal and provides default implementations for most of the tedious bits. You only need to provide methods to return the module name, module description, and default method. The default method will execute if a user clicks on the module in the navigation bar.

Now we need to add methods that will handle the business logic. All methods in a Coefficient module are loaded by reflection and must follow the standard signature. Methods must return void and take a single parameter of type CoefficientContext. You may use methods with other signatures, but these methods will not be available to the Coefficient runtime invoker. The following listing shows the method for displaying the Wiki content:

    public void display (CoefficientContext ctx) {
      HashMap map = new HashMap();
      
      String result = wikiText.
        replaceAll(" \\*"," <b>").
        replaceAll("\\* ","</b> ").
        replaceAll(" _","<i> ").
        replaceAll("_ "," </i>").
        replaceAll("\\\\","<br/>");
      
      map.put("wikiText", result);
      StringBuffer sb =
        VelocityScreenUtil.getProcessedScreen("display.vm", map);
      ctx.setModuleContent (sb.toString(), getModuleName());
   }

To return content to the Coefficient processor, use the ctx.setModuleContent() method. This method takes one string parameter for the HTML that will appear in the navigation's body. You can return any string to this method, but Coefficient uses Velocity for its standard screen processing. Velocity is a powerful template engine used for a variety of different text-processing applications. See Resources for more information on using Velocity.

In the code above, HashMap is used to add objects to the Velocity context. All templates are loaded from the classpath relative to the module class's package. In this case, the display.vm template must reside in za.org.coefficient.modules.sample.templates. The Velocity language is easy to use: any key added to HashMap can be accessed by using a $ followed by the key name, as shown here:

  <table border="1" width="100%">
    <tr>
      <td>$wikiText</td>
    </tr>
  </table>

A Wiki module would not prove very useful if the content was not editable. To edit the content, add a new method that displays a form. The updateForm() method adds the current Wiki text to the context and loads the template responsible for the HTML template:

   public void updateForm (CoefficientContext ctx) {
      HashMap map = new HashMap();
      map.put("wikiText", wikiText);
      StringBuffer sb =
        VelocityScreenUtil.getProcessedScreen("updateForm.vm", map);
      ctx.setModuleContent (sb.toString(), getModuleName());
   }

The form's Velocity template is also placed in za.org.coefficient.modules.request.templates. It is a standard HTML form, with the action pointing to the Wiki module and update method:

  <form action="index.html?module=Wiki&op=update" method="POST">
    <textarea cols="50" rows="10">$wikiText</textarea>
    <br/>
    <input type="submit"/>
  </form>

To link to the edit form, simply add the following line to the display.vm template:

  <a href="index.html?module=Wiki&op=updateForm">update</a>

It points the URL to the Wiki module and the updateForm() method that will display the update form.

All that remains is to add a method that will handle the form submit. The method below collects the information from the form and populates the wikiText parameter. It then forwards control to the display() method, which in turn displays the new content.

   public void update (CoefficientContext ctx) {
     wikiText = ctx.getParameter("wikiText");
     ctx.setForward("Wiki","display");
   }

This example showed you the basics of creating a new Coefficient module, and you should be able to create rich and interesting modules in no time. Because Coefficient is open source, the community welcomes any modules for contribution to the core project.

More advanced module techniques

If you managed to create your own module, you are ready to start using Coefficient as a basis for online collaboration. This section summarizes some of the advanced techniques you will need for more complex modules.

Coefficient modules without database access aren't useful. Luckily, Coefficient handles much of the mundane database operations for developers with the help of a tool called Hibernate. Hibernate is a popular object-relation tool; see Resources for more information.

To add a new class or table, you must create a Hibernate data class by adding XDoclet tags. The class is registered with the Coefficient runtime by inserting a static block to your module. Coefficient will handle all table creation and updates automatically at runtime, meaning you never touch any SQL. Refer to the existing modules for database examples.

Coefficient modules can also be used as project modules, meaning they can be added to projects as tools. The Discussion module is a good example of a project module. To develop a project module, you need to add it to the /za/org/coefficient/projects namespace (the Wiki example is in the /za/org/coefficient/navigation namespace) and extend BaseProjectModule. When developing project modules, you must be aware of the current project, which is available from the CoefficientContext object. Refer to the existing Coefficient modules for reference implementations.

The last type of module is a Theme module. Themes are used to determine the look and feel of Coefficient. You can alter the look to correspond to the specific needs of your organization by creating a module that extends the Theme class and adds itself to the /za/org/coefficient/themes namespace. By altering various templates, you will be able to fine-tune the user interface. Refer to PlainWhiteTheme for an example.

Last but not least, is the Coefficient security model. Use the getCurrentUser() method from CoefficientContext to test if the current user is logged in and which user is executing the request. You can also override the module's canExecute() method to check a module's authorization.

Conclusion

Many developers will get involved in online collaboration software during their careers. These developers will either develop collaboration features for their clients, or use collaboration software during the software development lifecycle.

Coefficient is a strong base for online collaboration and is almost immediately useful to a wide range of users. You can easily extend Coefficient to meet any of your organization's collaboration requirements.

Leon Messerschmidt, a Java developer and open source advocate, lives in Pretoria, South Africa with his wife and two dogs. He has been involved in both commercial and open source Web application framework development for many years and currently works for Psybergate.

Learn more about this topic

Join the discussion
Be the first to comment on this article. Our Commenting Policies