jwma (java webmail application) version 2.4.1

preamble

As with older versions, it provides access to an imap email store. Multiple users can authenticate, read, send and manipulate email and store a list of contacts and email identities. Currently, the assumption is that it will be running locally on the same machine as the mail exchanger. It would be simple to extend it's use to allow interaction with non-local servers (see to do).

The server administrator configures basic options by editing a simple config file. Here are set protocol (imap or imaps), ports and the default language that's offered to users. Individual users can separately choose the language of the interface and select from a few other options.

Jwma depends on a java webapp server (tested with tomcat7), imap server (tested with dovecot) and smtp server (tested with exim4). It was developed on a Gnu/Debian/Linux machine, but it should run on Windows with no more than minimal changes, although we did not yet find a suitable imap server to authenticate against. In addition to the stripes framework, jquery is used for javascript, javamail for interaction with the mail exchanger, the wyzz editor for writing html email and jericho-html for parsing html when this is necessary to obtain plain text.

Installation

This assumes a machine running a supported imap server (known to work with dovecot), a smtp server and java webapp server. Download from sourceforge and copy the webmail.war file into the appropriate place for your webapp server (webapps for tomcat) and it will start up and load the login page - if you're upgrading from an earlier version please first check out the next section.

If you have an account on the imap server and it's offering an imap service on port 143, you will be able to login and access your email. See the user guide section.

Upgrading

New in version 2.4:-

Version 2.4.1 is a maintenance release, squashing these bugs:-

If you're upgrading from 2.1 onwards all users must delete and then re-enter their mail IDs, even if they never changed from the default JWMA User<username@localhost> setting. This is necessitated by a rationalization of the way in which mail IDs are stored. On this occasion there are no changes to underlying storage schema, which is not meant to indicate this is likely to happen in the future :-)

If you're upgrading from version 2.0 you need to delete the existing home folder .jwma (or jwma on Windows) to enforce a new default configuration file to be written. Unfortunately the user config and contact storage formats have also changed, so there is no point in saving the .jwma/data folder files. This should never be necessary again (until the next time ~_^)

If you intend to switch to database storage of user configs and contacts (serialization remains as default) and you used database storage with versions 0.98 - 1.01, existing databases must be dropped and recreated.

Configuring

The first time it starts the .jwma (jwma on Windows) directory is written and a default config file jwma.config. The location of this directory will likely be in the base of the webapp server installation, but it's logs should have an indication where this is. If you make changes to the config file, you need to reload the webmail app or restart the app server, to have the changes picked up.

No per user configuration is necessary other than there must be an pre-existing imap account. Jwma passes login details through to the imap server and a jwma account is automatically created for each user the first time they log in. With the default persistence setting, preferences and contacts for each user are stored in two separate files, inside the .jwma/data directory. Before switching to database persistence see the next section.

Data storage

Pro and con:- Before editing the persistence field in jwma.config and restarting the app server, you must create the database:-

postgresql

$>su postgres
postgres$>createuser -P jwma
Enter password for new role: 
Enter it again: 
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n

postgres$>createdb -O jwma "jwma"
nb the password must be webmail
finally create the schema by inserting the empty database in utilities/database
psql -d jwma -f utilities/database/jwma.postgres

mysql

$>mysql -u root -p; 
mysql>create database jwma; 
mysql>grant all on jwma .* to 'jwma'@'localhost' identified by 'webmail';
mysql>flush privileges;
as with postgres, the schema can be created by inserting the supplied empty database:-
mysql -u root -p jwma < utilities/database/jwma.mysql
Important: You also need a suitable jdbc driver for your version of postgres or mysql, this can be put in the tomcat/lib folder.

In case you prefer to create the schema manually, the two databases view them as below:-
             Table "public.jwma_user"
    Column    |          Type          | Modifiers 
--------------+------------------------+-----------
 username     | character varying(20)  | not null
 auto_empty   | boolean                | not null
 auto_quote   | boolean                | not null
 auto_sign    | boolean                | not null
 contact_list | bytea                  | 
 draft_folder | character varying(30)  | not null
 language     | character varying(2)   | not null
 mail_id      | character varying(150) | not null
 processor    | integer                | 
 sent_folder  | character varying(30)  | not null
 sort_order   | integer                | not null
Indexes:
    "jwma_user_pkey" PRIMARY KEY, btree (username)
mysql> describe JWMA_USER;
+--------------+--------------+------+-----+---------+-------+
| Field        | Type         | Null | Key | Default | Extra |
+--------------+--------------+------+-----+---------+-------+
| USERNAME     | varchar(20)  | NO   | PRI | NULL    |       |
| AUTO_EMPTY   | bit(1)       | NO   |     | NULL    |       |
| AUTO_QUOTE   | bit(1)       | NO   |     | NULL    |       |
| AUTO_SIGN    | bit(1)       | NO   |     | NULL    |       |
| DRAFT_FOLDER | varchar(30)  | NO   |     | NULL    |       |
| LANGUAGE     | varchar(2)   | NO   |     | NULL    |       |
| MAIL_ID      | varchar(150) | NO   |     | NULL    |       |
| PROCESSOR    | int(11)      | YES  |     | NULL    |       |
| SENT_FOLDER  | varchar(30)  | NO   |     | NULL    |       |
| SORT_ORDER   | int(11)      | NO   |     | NULL    |       |
| CONTACT_LIST | blob         | YES  |     | NULL    |       |
+--------------+--------------+------+-----+---------+-------+

Internalization

Version 2 (esp 2.4 on!) of jwma is a genuinely internationalized app; the system administrator can configure the default language (but please note that supplied translations from English are probably flawed - see to do). All users make their own selection which is recorded in their config settings, they do this entirely independently of other users and the default language, although this is always presented in the login screen.

To add another language copy a StripesResources properties file in /webmail/web/WEB-INF/classes to StripesResources_xx.properties (where xx is something suitably representative), translating the right hand side of = on each line of the file. Add the appropriate xx to the languages list in jwma.config and reload or restart the app server. Please submit a copy of your file for inclusion in the next release.

Security

Mostly this is not a jwma issue (famous last words?); authentication is managed by the imap server with jwma merely passing details through to it. When it's running locally, I don't believe that passing these in plain text is an issue. The user name, but not the password is stored in the session object. Databases are protected from malicious input, by checking and sanitizing user input for storage.

However, Jwma writes logs files; with tomcat or another app server that explodes the .war file, these will be in the .jwma (or jwma) folder. If the app server runs from the war file without exploding it, it's not possible for the code to manipulate the log4j.properties file. Bets are off, but try looking in the folder from where the app server runs. If you're responsible for a system with a lot of users, it's worth looking out for WARN and ERROR entries. All login attempts are recorded, together with the source ip address if authentication fails.

If you see something like this

ERROR JwmaExceptionHandler - net.sourceforge.stripes.exception.ActionBeanNotFoundException: Could not locate an ActionBean that is bound to the URL [/Admin.jwma].
I'd recommend having a word with the user in question (there is no Admin.jwma page).

Log in

On a desktop machine if you browse to the address given you by the administrator, you'll get the login screen where you can authenticate with your imap username and password to access your email.



If you tick the Remember box a cookie is written to your browser. Depending on the browser's configuration, the Username field may be pre-filled next time you access the page. The link on the top left is there in case you arrived here using a small screen device; it will take you to the mobile interface.

Main Page

This is where you land after a successful login and where you can quickly return to from the left most link on the navigation bar.



From top working down, you see that the INBOX has 3 messages, one of which has not been read. The already mentioned navigation bar takes you to the other parts of the app as well as returning you here. Next the pre-exisiting folders and mailboxes are displayed. Folders, which can contain mailboxes are shown on the left and Mailboxes which contain messages on the right. Below here are options to delete selected folders or mailboxes, move mailboxes from their logical position inside the INBOX to another folder and create new folders or mailboxes. Finally the icon at bottom right shows that the Trash folder is not empty.

In this state (not empty), the icon is a link that will take you to a list of messages in the Trash folder. The INBOX icon is also a link as are the folders and mailboxes in their respective lists. Be aware that deleting mailboxes and folders removes all messages and sub folders; unlike deleting a message, which actually moves it to the trash folder (see Message lists), there is no warning or second chance.

User Configuration

Select Settings in the navigation bar and you'll be taken to this screen, which initially displays the default settings for each user.



You'll want to replace the Mail identity with one or more of your own email addresses. Note that you cannot delete the default until at least one alternative is in place. This is because it's not possible to send email without this setting.

If you select a different language all the screens (except the login page) will be translated accordingly. Note that by default Trash messages are automatically deleted when you logout; if you stick with this, although deleting messages from other mailboxes actually moves them to Trash, on logging out, they really will be gone.

By default, sent mail is not archived to an Outbox and there is no Draft folder for saving messages (even if there is a mailbox of that name); you'll probably want to select mailboxes for these roles, possibly creating them first back in the app's Main page.

Message display options:-

Of these options 1. and 2. are now reliable. 3. - html display without images mostly works as webmail filters out style options known to mess up it's appearance, but it's possible some will still cause problems. I'd appreciate receiving a copy of these so the issue caused can be fixed.

Option 4 - displaying in line images also seems reliable; email with these seems to be one of two flavors. Firstly a misplaced idea in my opinion of company branding and a waste of bandwidth or a photo added to the email sent from a phone (possibly a similar waste!). Option 5. (and html email in general) is a poor choice in my opinion, but displaying remote images is not problematical if that's what you want. Blocking them is a harder coding task, although I believe this works well. Suggested reading in this regard. Also note that as described in the Reading messages a section, a sensible user, who selects options 1 or 2 here can quickly switch to option 3 to read an individual html message.

You must press the Update button to make changes stick. Don't forget to do this after changing mail identities.

Message lists

Here's an mailbox with 3 messages; looking directly below the navigation bar, you see this is the INBOX, but listings of the mail boxes will appear the same.



You can Select all messages for a mass Delete or Move to; that can also be done on an individual basis by checking boxes on the left as appropriate. Delete is actually a move to Trash except for messages already there, when it really is a delete. Looking at the three individual messages, you see that two have been read R and the third has been answered A. The first message has an attachment, which is indicated with *.

All are sent using mail@dmatthews.org as the from address, so there's little point (even if there were more messages!) in changing the sorted by setting to list messages by from address. The setting shown is not the default (rather Date oldest first), when this is changed the selection sticks automatically for all mailboxes and is remembered even if you logout.

Search allows you to create a list of messages from the current mailbox which contains your search term in the body of the message. Clicking on the subject of a message displays it (see Reading messages) and to the right, delivery date and message size are displayed.

Reading messages




The appearance of messages depends on the setting chosen in Settings.

This mail is a phishing attempt; it's the third #3 message in the folder named specimen which means it's the oldest message bar two (chosen sort order has no bearing on this). The current message display setting is option 1 geek so there is information about the structure of the message; lamentably as well as being an attempt to steal, there is also no plain text part, so jwma has to parse the marked up html. If the plain text / html toggle is selected, the html is displayed without images, ie equivalent to setting option 3.




If in Settings an unwise user selects 5 allow all images, the messages is displayed as the sender intended (more or less, although some styling may be removed to avoid unwanted changes to the appearance of Jwma itself) and since remote images have been fetched, his email address may now be marked as known to be live in a spammers database.

The screen will be the same for messages in all other mailboxes including the INBOX, except in a mailbox you designated to be Draft, when a compose window will be opened with the saved message already in place.

Top and bottom to the far right are widgets for cycling through the messages in the current mail box and presenting this message in a screen suitable for printing. If clicked, the head and shoulders icon, far right from the subject will reveal (or conceal) the message headers. Here's the headers of the same message, they appear above the body of the message.



If you enabled Automatically quote in User Configuration, the Toggle auto-quote is useful for turning this off if you want to reply without reference to the original mail.

If you tick the With Attachments box, Forward to sends messages on mostly unaltered, leaving the recipients email client to decide how to display them. More on this in the next section.

Here's a second example email, shown both with settings 1 and 2 selected.







Setting 1 displays the plain text part of the message and notes the presence of other parts. Setting 2 omits what might be considered to be this extraneous information. Although supporting html email standards is not of particular concern to Jwma, it generally does a pretty fair job at this. This particular email is unusual in that the content of the text/plain and text/hml parts are not identical. Here's the same message in it's full html glory (using setting 5 - allow all images).




Lastly, here's a third mail using setting 2; it has three images attached in line.



With out going to the Settings page, they can be displayed by selecting one of the Display image: links, which temporarily switches you to allowing in line images (setting 4).



Irrespective of display option, attached files and in line images also, are presented as downloadable links.

Sending Messages

As standard Jwma creates and sends messages as plain text




The rich text link replaces the text area with an embedded html editor to allow the creation of html messages.




If you use the Browse button to add a file attachment, two further file selectors will appear automatically, giving the option to attach up to three files.

Save Draft allows you to save a partially complete message into the folder you configured as described in the User configuration. section. If you have not done this a a warning is displayed. It is not functional if rich text was selected.

No attempt is made to display forwarded messages before they are sent on; you see that the subject and recipient have been rewritten and a preamble stating that this is a forwarded message. You can edit this preamble before sending, but apart from removing any attachments (unless you ticked the box as described above) (see With Attachments box note) the original message is included unaltered.





Contacts





This simply allows you to store a list of contacts with email addresses. Clicking on the email address takes you to the compose window, with the To field pre-entered.

The small screen interface

If you access Jwma using your smart phone, you should be automatically directed to an alternative interface, but as a fall back the login screen of each interface allows you to switch manually. Compared to the desktop interface there are optimizations both in layout and in a reduction of the feature set.

These screenshots where taken from a galaxy 2 running cyanogenmod; the mobile interface looks pretty much the same on the iphone.

 

A successful login takes you directly to the INBOX rather than a folder listing. The folder list is accessible in the same way as on the desktop interface (the first left navigation icon) a major difference being that type 2 mailboxes (ie folders containing mailboxes) and the mailboxes they hold are not accessible. Other differences include the absence of a save draft option, no option to create html mail, message lists are displayed in recent first order and message display being set to plain text (option 2).

There is no contradiction between the two interfaces in that their settings do not clash. Any type 2 mailboxes you created via desktop access remain untouched by small screen access and if you normally read messages using some setting other than plain text, that setting will remain in place for desktop access.

To do

If you'd like to contribute in any way please get in touch; especially if you want to do something major that you would like included in future releases. This list is not necessarily exhaustive, all patches that add or improve functionality or squash bugs will be considered and you'll be credited for your work. Please see the development section for help getting started. David Matthews<mail@dmatthews.org>

Development

You'll need a java development environment, a java webapp server and a locally running mail exchanger, which includes an imap server. The imap server needs to be configured with a username and password and needs to accept authentication from webmail in plain text.

At the moment the program has only been tested with the linux imap server, dovecot. If you are serious about helping and are unable to get a suitable mail exchanger set up on your development machine, I may be able to help with an account on another server.

Here's how to get started in two major development environments.

Netbeans

  1. File/New Project/Java Web/Web Application
  2. name the project to be webmail
  3. choose the server and java version, leave context path unaltered as /webmail
  4. don't select a framework
  5. delete all auto created files and folders from the new webmail directory
  6. replace them with the src and web directories from the source archive and the nbproject directory and build.xml file from the netbeans archive, available in the 2.0 source release.

Eclipse

  1. import the code into the Eclipse Workspace
  2. add following jar and libraries into Build path the three jar files are included in the source code (web/WEB-INF/lib)

Not implemented

The purpose here is to avoid I need this feature from 0.9x / 1.0x type disappointment. There's some overlap with to do here, but it was not my intention to include every last feature. If it's missing and you want it enough to code it, I'd be interested in including it in a future release even if it was not mentioned in the to do section.

FAQs

1) Database storage without any hibernate/castor etc?
answer: Yes. I implemented a version with OpenJPA, which increased the .war files size by x4. That would be just about acceptable if the OpenJPA library could be removed in installations using serialization. That's not possible without recompiling as the domain files need to be byte enhanced which then necessitates the presence of OpenJPA at runtime.
Another trial was done with hibernate - no byte enhancement issues, but the .war files size is x8!
Short answer is that writing sql manually is not fun, but performance is much better and this is anyway not a database heavy app.

2) Can I use a database other than mysql or postgres?
answer: Provided there is a jbdc driver available, yes. You would need to add the database into the getConnection() method of Datastore.java and recompile.

Credits

Not necessarily in order of merit:-

License

Earlier versions of jwma (from 0.9x to 1.x) were covered by a BSD style license, which still applies to those files that the program has retained - for instance the files in the images directory. A copy of this file is included in the license directory in the file LICENSE.

Starting with version 2.0, the java source code files were completely rewritten and these are now covered by the GPL3 license a copy of which is included in the same directory in the file GPL.

The licenses of all bundled software including stripes, javamail, jquery, jericho-html and wyzz are acknowledged. There is an explanatory note in the file license/README.

Old documentation

The documentation for the orginal versions (99.x to 1.0) is still available here.

version 2.0
version 2.1
version 2.2
version 2.3