Setup Instructions for Development

Developer setup instructions are the same as the regular install instructions. Take special note of the instructions below if you wish to run the unit tests.

Eclipse Setup

The 3 of the 4 core developers use Eclipse as their IDE of choice. We suggest you do as well. =)

In order to setup Eclipse, you should first make sure to install the Subclipse plugin. Once you have installed that plugin. Select File->Import->Checkout projects from SVN. Select "Create a new repository location". Enter the URL for SubEtha's repository: http://subetha.tigris.org/svn/subetha

Note: The default svn username and password for tigris.org are Guest with no password.

Once you have the project checked out you need to define the location of JBOSS_HOME in Eclipse. Select Project->Properties. Java Build Path->Add Variable. Configure Variables->New and set the name to JBOSS_HOME and the folder location where you installed JBoss. Now, Eclipse should properly find all the right libraries it needs.

The next step is to build SubEtha. From the Java perspective, select Window->Show View->Ant. Right click in the Ant view and Add buildfiles. Then look for the top level SubEtha build file and add it. Once that is done, you can double click the 'deploy' target which will build SubEtha and install it in the right JBoss directory location.

JUnit Ant Eclipse Setup

(Option 1)

In the Windows->Preferences select the Ant->Runtime node. Add an external jar to

<eclipse dir>\plugins\org.junit<version>\junit.jar

Suggested Eclipse Plugins

• Check Style: http://eclipse-cs.sourceforge.net/
• Subclipse: http://subclipse.tigris.org/

Linked Resources (Optional)

You can also setup Linked Resource support in eclipse so that you can edit the deployed files in JBoss. These folders can also allow direct editing (in eclipse) of jboss configuration files. To do this, please add a JBOSS_HOME variable to the workspace linked resources properties. These setting can be found at Window -> Preferences under the General : Workspace : Linked Resources section. Select New from the dialog and specify a name of JBOSS_HOME to the jboss home folder. The linked folders in the project are named "jboss-X", where X points to the server/default/X folder.

Note: You will need to refresh the linked folders each time you deploy. JBoss creates a new folder in deploy/tmp each time the ear is unpacked.

Startup

Start up JBoss. The default web interface is http://localhost:8080/se/ When SubEtha runs for the first time, it creates a site administrator account named root@localhost, with the password password.

Directory Layout

The subdirectories correspond to various components:

• appmain - Build system for the main ear archive which gets deployed in the appserver. No source code, just some packaging instructions and some metadata. Depends on all of the other components.
• common - A common jar of utility classes, shared by all components. Includes some constants defined for the data model.
• core - The core business logic, implemented as a set of session EJBs. There may also be some service EJBs here. There is also a special component built, a sar, which contains thirdparty jars and some configuration instructions to JBoss.
• plugin - Implementation of all the plugins distributed with SubEtha. Note that the plugin interfaces are part of core and built into the core api jar.
• entity - The data model. Contains EJB3 entity beans and a simple session EJB Data Access Object pattern. All queries are defined here as well.
• rtest - All junit regression testing code and instructions. JUnit tests are remote clients to the core ejb interface.
• frontend - The front end web application, packaged as a war. Contains JSPs and all other content, acts as a client to the core layer.

Running Regression Tests

How to run the JUnit regression tests from ant:

• Make sure the code you want to test is deployed. ant deploy will build the latest and deploy it.
• Make sure your ${jboss.dir}/server/default/deploy/mail-service.xml points to localhost, port 2525. Make sure this port is free; the unit tests start a mock SMTP server on this port.
• You MUST set the system property in the JBoss JVM: -Dorg.subethamail.dev=true. This causes JBoss to annotate the automated messages with flags that the unit tests can recognize. Edit ${jboss.dir}/bin/run.bat (on Windows) or ${jboss.dir}/bin/run.conf (Linux/Unix/MacOSX) and add this instruction to JAVA_OPTS.
• Start JBoss. The unit tests are run against the live container.
• Run ant junit. All your regression tests will run.
• If you want to run just one set of tests, edit the junit.special.tests property in your build.properties or better yet user.properties. Then run the ant junit-special target.
• If you want to run the special unit test(s) in the debugger, run the ant junit-debug target. The JVM will pause and wait until you attach with Eclipse.

Developing Filters

We have written some intro documentation for developing your own filters for making modifications to the incoming and outgoing mail streams in SubEtha. If you write a useful filter and you want to contribute it we would love to hear about it on the developers mailing list.

Mail client setup for testing

For testing of SubEtha, it is possible to easily inject email from your mail client directly into an instance of SubEtha. The way to do it is to setup a mail account in your client with a From: address of a subscriber on the list, the To: address is an existing list email, and the outgoing mail server is the host SubEtha is running on at port 2500.

Coding Conventions

You may wish to read the SubEtha Coding Conventions.