ReadMe for MIME Browser 2.0.0

ProgramMIME Browser for EML files
Version2.0.0 (History)
Released05 February 2019
AuthorChristoph Nahr (Copyright)
Contactwebmaster@kynosarges.org
Websitekynosarges.org/MimeBrowser.html

Table of Contents

  1. System Requirements
  2. Package Contents
  3. Usage Overview
    1. Display & Controls
    2. Configuration File
  4. Source Package
  5. Text Encodings
  6. Known Issues
  7. Copyright Notice

1. System Requirements

MIME Browser is a Java Swing GUI application that should work on any 64-bit operating system with a current Java Runtime Environment (JRE). The minimum requirement is Oracle Java SE 8 or compatible, such as OpenJDK. Users of high DPI displays should note that Java SE 9 or later is required for high DPI scaling.

Some hyperlink actions rely on Java’s multiplatform support for invoking default applications, such as web browsers and email clients. These should work on all desktop platforms, assuming your applications are properly configured to handle the desired URLs or file types. If some action is entirely unsupported on your platform, the hyperlink’s tool tip will state that fact.

2. Package Contents

The directory to which the binary package was unpacked contains the following files:

ReadMe.htmlThis file
WhatsNew.htmlMIME Browser version history
controls.pngScreenshot for display & controls
project.cssStyle sheet for ReadMe & WhatsNew
Diagrams.xmlProject file for overview diagram
MimeBrowser.jarPrecompiled executable Java archive
MimeBrowser.cfgSample configuration file for file extensions
lib/*Third-party libraries (see Copyright Notice)

These files are all you need to run MIME Browser. Java programmers may also want to download the source package which is available separately.

3. Usage Overview

MIME Browser supports the following explicit and implicit start-up options:

The following usage samples show how to invoke MIME Browser with a specific Windows directory and EML file, respectively, quoted to preserve the embedded spaces:

    java -jar MimeBrowser.jar "D:\My MIME Messages"
    java -jar MimeBrowser.jar "D:\My MIME Messages\Purchase Confirmation.eml"

Use javaw instead of java on Windows to launch without a command line console. Depending on your JVM, you may also be able to omit java[w] -jar and simply execute MimeBrowser.jar directly.

Drag & Drop — Once MIME Browser is running, you can also navigate to any document or folder by dragging & dropping it onto the application window. Your system may show an inappropriate verb such as “Copy” or “Move,” but the operation really just opens the dropped object. Note that you cannot start MIME Browser via drag & drop since that only works for native executables (at least on Windows).

3.1 Display & Controls

The following screenshot, taken on Windows 10 at 192 DPI, shows MIME Browser in action. The user interface is divided into eight functional groups, described in the rest of this section. You can also hover over most controls to show tooltips while MIME Browser is running.

Annotated Screenshot

1. Folder — Shows the selected folder and some navigation controls.

2. Search — Customize what entries appear for the selected folder.

All options immediately affect the entry list, except for the Filter term which is applied by pressing Enter while in the editing field. When Regex is selected, any search term that does not form a valid regular expression appears in red and has no effect.

3. Entries — Shows the files & folders selected by the previous options.

Hidden or inaccessible files are silently ignored. Use Refresh to display entries that have been temporarily inaccessible and are now accessible again.

4. Document — Shows the full file path of the selected document.

5. Headers — Shows MIME headers if a MIME message is selected.

6. Part — Shows MIME part information if a MIME message if selected.

7. Content — Customize and manipulate the selected content.

Save prompts you to select a file name whereas Save All prompts you to select a directory. In the latter case, file names are taken from the MIME message if available, or else generated by appending a plausible extension to the name of the message itself. If a new file has the same name as an existing one, MIME Browser prepends a unique number to the new file name.

8. Text/Image — Shows the selected content if display is possible and enabled (plain text, HTML, images) or else information on unrecognized or non-text content.

3.2 Configuration File

The optional configuration file must be named MimeBrowser.cfg and is read line-by-line. Non-ASCII characters must use UTF-8 encoding. All leading and trailing spaces are trimmed. Empty lines and lines beginning with a hash (#) are ignored. All non-ignored lines must map known document types to file extensions, using the syntax TYPE=.ext;.ext;…. (See below for the exception LOOK_AND_FEEL.)

Extensions are not case-sensitive, must include the starting dot, and may include multiple dots. Multiple extensions are separated by semicolons. The following table shows all supported document types with their default extensions. These are specified in the sample configuration file, but are also in effect without a configuration file.

MIME_MESSAGE=.eml
TEXT_HTML=.htm;.html
TEXT_PLAIN=.txt
TEXT_XML=.xml

MIME Browser currently includes two configurable simple viewers, for plain text and HTML files, as well as an image viewer that is only used for image parts of MIME messages and non-configurable. Thus, the supported document types are handled as follows:

Since the configuration file is optional, MIME Browser will run even if none is found in the current directory, or if an error occurred while attempting to read it. Any such errors are printed to stderr. To see them, start MIME Browser from a command line prompt using java rather than javaw. Finally, start MIME Browser from a directory other than its current directory to use different configuration files on the same system. (That’s rather clumsy but I don’t anticipate any great need for multiple sets of file extension definitions per system.)

Swing Look & Feel

The configuration file allows one additional option unrelated to document types. Specify LOOK_AND_FEEL=Name to change the Swing “Look & Feel” for the application, i.e. the general visual theme for all controls. The Name must match either the L&F’s display name, or part or all of its class name. For example, these are the available names and class names on my Windows system:

Apple Macintosh and Solaris/Linux with GTK+ 2.2 or later each replace the two Windows L&Fs with another system-specific one, according to Oracle’s possibly outdated Swing Tutorial:

By default, MIME Browser attempts to select Nimbus and falls back on Metal if that fails. The other L&Fs are system-specific and may result in poor visual results. For example, CDE/Motif has strange ideas about control sizing that are incompatible with good-looking layouts in other L&Fs.

4. Source Package

The source package is available as a separate download on the MIME Browser home page. The expected environment is IntelliJ IDEA 2018.3.4 with Oracle JDK 10.0.2. This package contains all of the files in the binary package, except for the precompiled Java archive, plus the following:

MimeBrowser.imlIntelliJ project file
.idea/*IntelliJ project metadata
javadoc/*Javadoc class reference
res/*Embedded resources
src/*Source code and JAR manifest

The source package does not include standard build files (e.g. Ant) but you can simply download the free IntelliJ Community Edition and generate such files from the project.

Overview Diagram

To help understand the source code, you can download an overview class diagram that visualizes how the central classes interact. This diagram was created from the included file Diagrams.xml which is a Class Diagrammer project. To view or edit the project in Class Diagrammer, open Diagrams.xml in the same directory that holds MimeBrowser.jar. Note that the precreated PDF output linked above was created with locally installed Adobe Myriad Pro fonts, so you may have to adjust the diagram layout for wider fonts.

5. Text Encodings

MIME Browser relies on the JavaMail library to correctly identify text encodings, although I can make no guarantees that it will always succeed. For the benefit of other programmers using the JavaMail library, I’ll document one manual correction for a failure case I’ve seen in my own EML archive using JavaMail 1.5.

The error is triggered by MIME attachments that are declared as text (in this case text/xml) but encoded in Base64 and lack a charset declaration. JavaMail automatically decodes Base64 and stores the resulting text as a Java string – but assumes 8-bit ASCII/ANSI encoding since no character set was specified. This results in garbled text if the original characters actually use a Unicode encoding.

We can attempt to fix this (only) if the original text started with a Unicode byte-order mark (BOM). The wrongly encoded JavaMail string stores each BOM byte as a separate 16-bit character. If the original text was UTF-8, each code point is likewise stored as a separate 16-bit character. The method DocumentReader.correctUnicode checks for the BOMs of Unicode encodings supported by Java 7 (UTF 16 BE, UTF-16 LE, UTF-8) and, if found, correctly re-encodes the string.

6. Known Issues

MIME Browser only supports normal (individual) addresses, not the rarely used RFC 822 group addresses. Moreover, Reply-to addresses are intentionally hidden if they are exactly the same as From addresses.

All files and folders are read directly from the UI thread, as blocking operations. This should not matter for the intended use case, but beware that MIME Browser will freeze for quite a while if you decide to show a huge binary file as text!

MIME envelope fields are editable even though changing them has no effect. The sole purpose is to show a text cursor for easier scrolling through long contents.

HTML View Issues

Multipart MIME messages that contain both plain text and HTML contents default to plain text view. The HTML view must be explicitly selected by the user. This is undesirable but CSSBox automatically loads remote HTML content and may display complex pages slowly or incorrectly, which is even less desirable.

The HTML view supports neither selecting & copying text nor clickable links. This is a limitation of CSSBox. An enhanced implementation with these features exists, but has fallen out of maintenance years ago. Open the MIME message in your email client (via the title link) as a workaround.

Changing the text font affects plain text and subsequent HTML notifications, but not any currently displayed HTML notification. Changing the text size does not affect the HTML view, as this is another feature that CSSBox currently does not support.

Other Display Issues

The display is not automatically updated when files or folders change on the disk. Please use Refresh (F5) to manually update the display in that case.

While full-text search scans the same content that appears in the text view, the search term itself is not highlighted there. I’m not sure if this is feasible with an acceptable amount of effort.

All files – individual files, multi-file packages, and individual files contained in multi-file packages – that constitute the original distribution of MIME Browser are Copyright © 2013–2018 by Christoph Nahr, except where otherwise noted.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Exceptions

All icons are rendered from the embedded Font Awesome by Dave Gandy, made available under the Font Awesome Free License. This font is present as the separate file res/FontAwesome.ttf in the source code package.

MIME message parsing is performed by the JavaMail library and the JavaBeans Activation Framework, made available under the Common Development And Distribution License. These libraries are present as lib/javax.mail-1.6.2.jar and lib/javax.activation-1.2.0.jar in both binary and source package.

CSSBox Libraries

HTML display is performed by the CSSBox and JStyleParser libraries, both © 2007-2018 Radek Burget and made available under the GNU Lesser General Public License v3.0. These libraries are present as lib/cssbox-4.14.jar and lib/jstyleparser-3.2.jar, along with the license as lib/Gnu-LGPL-v3.txt.

MIME Browser contains a modified version of the CSSBox class BrowserCanvas which you can find under the name of BrowserCanvas2.java in the source package. My modifications support DPI scaling on Java SE 9 and later, as described in DPI Scaling for CSSBox.

Lastly, CSSBox relies on a number of additional third-party libraries, all present with their respective licenses under lib in both binary and source package. You can find the source code for each library at the project home pages linked below.