jwma (java webmail application) version 2.4.2

preamble

• goal: reimplement the interface and (most of the) functionality of older (pre 2.0) versions, but using the stripes framework
• status: stable, mostly complete and largely free from surprises - but please see todo.
• why? to produce a codebase that can easily be maintained and extended to add new features

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.

For the server administrator

• 1)Installation
• 2)Upgrading
• 3)Configuring
• 4)Data storage
• 5)Internalization
• 6)Security

For the user

• 2)Log in
• 3)Main page
• 4)User Configuration
• 5)Message lists
• 6Reading messages
• 7)Sending messages
• 8)Contacts
• 8)The small screen interface

For the developer

• 1)To do
• 2)Development
• 3)Not implemented
• 4)FAQs

Other stuff

• 1)Credits
• 2)License
• 3)Old documentation

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.

New in version 2.4:-

• Improved treatment of in line images. They can now be displayed with a single click if blocked as standard and also downloaded in the same way as attachments
• Up to three files can now be added to messages as attachments
• Overhaul of internationalization; remaining problems should now be down to better translations
• Added an alternative small screen (mobile) interface
• Bug fix; a new mail identity can now be added and made the default in a single operation
• Bug fix; automatically emptying trash setting on exit now works
• Name is now included in signature display of sent mail and incorrect display in html mail is fixed
• Fixed incorrect quoting in saved replies
• Removed redundant duplicate image folder
• A couple of new, more intuitive, navigation icons (necessary for the mobile interface)

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

• failed logins switched from desktop to small screen interface
• faulty display of links to folder / sub-folder in some circumstance

Version 2.4.2 fixes a problem with forwarding email that affected html messages that do not have a plain text part.

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.

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.

• mail_host - the default setting localhost is probably the only one that makes sense at the moment. Auth details are sent in plain text, which non-local imap servers may no longer accept and there is no provision at the moment for authorizing separately against the smtp server
• access_protocol - this can be changed to from imap to imaps, if you do this you may need to insert a certificate into the jvm's store - there is a utility provided to help with this.
• access port - this will probably need to be changed to 993 if you switch to imaps.
• smtp_port - to suit your smtp server config, but probably leave as default 25.
• languages - currently there are five European languages available. You could add to these (see i18n) or even remove from the comma separated list if you don't want to support them.
• language - the default language, one of those that appears in languages. This will be used at the login screen, but individual users are able to select a different languages once they are logged in.
• persistence - this must be set to serialize (the default), postgres or mysql.

• No additional installations and setups necessary with serialization.
• Easier to remove all trace of an ex-user with serialization - after removing the imap account just delete two files from .jwma/data.
• If you have a lot of users, database storage avoids a shed load of files being created in .jwma/data.
• Database storage is an attractive option on a server with an existing postgres or mysql install.
• Serialized files are not guaranteed to be transferable across different versions of the JVM.

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"

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;

mysql -u root -p jwma < utilities/database/jwma.mysql

             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    |       |
+--------------+--------------+------+-----+---------+-------+

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.

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].

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.

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 (seeMessage lists), there is no warning or second chance.

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:-

• 1. geek - plain text only display including the structure of the message
• 2. plain text - a standard plain text display
• 3. block images - html messages displayed as such with all images blocked
• 4. in line images only - in line, but not remote images are displayed
• 5. allow all images - html messages displayed with remote images and stylesheets.

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.

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.

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.

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, thehead 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.

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.

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.

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.

• Vet the language files and improve translations as necessary.
• Test and make work on systems other than Gnu/Linux with tomcat/dovecot/exim. Is there a suitable imap and smtp server that can run on Windows?
• Known issues - resolve the FIXME: labels in the source code (mostly done)
• replace the wyzz widgets with a set that better blends with jwma, better still design a complete set of new widgets
• Apply fixes as necessary to make all email display satisfactorily (mostly done)
• add SMTPS option.
• Encryption? Not sure I see a sane role for this in a webmail client. Nobody should store private keys on a server they don't own, and encrypted or signed content can simply be pasted to and from GPA (for instance).
• Recode the jsp files using stylesheets
• Enable jwma to work with non-local mail exchangers; this would involve adding options to present authentication in other forms than plain text and adding authorizing with a non-local smtp server.

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 sourcerelease.

Eclipse

1. import the code into the Eclipse Workspace
2. add following jar and libraries into Build path
   • apache tomcat (or an alternative)
   • JRE System Library
   • commons-logging.jar
   • log4j.jar
   • mail.jar
   the three jar files are included in the source code (web/WEB-INF/lib)

• Very little contact information can be stored - name and email address only
• Contact list cannot be filtered alphabetically (yet)
• Unsubscribing folders not supported - I don't see the need for mail stores you don't want to see
• Fewer config options for users.
• Fewer admin options - no choice of post offices, ssl libraries.
• Type 3 stores (apart from INBOX) are treated as type 2.
• Other stuff that I can't think of now.

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.

• the original jwma team, who produced a stylish app with appropriate functionality
• but excluding David Matthews, who merely tinkered around the edges, although he did go on to do the stripes rewrite
• the stripes team, for the framework that enabled the coding of a fluently behaved small footprint app
• Afreen Khan, who did some testing on Windows and Eclipse
• Louis Caudwell supplied a couple of icons

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.

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