ReadMe for MIME Browser 1.3.4

ProgramMIME Browser for EML files
Version1.3.4 (History)
Released01 May 2016
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 JavaFX GUI application that should work on any system with a current Java Runtime Environment (JRE). The precompiled JAR file requires Oracle Java SE 8 Update 66 with JavaFX 8 or later. Older JREs that only support Swing will not work.

Some hyperlink actions rely on Java’s multiplatform support for invoking default applications, such as web browsers and mail 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.

Known JavaFX Issues

There are currently two known JavaFX issues that might affect your system. First, its hardware accelerated graphics may cause some display drivers to crash; and second, its automatic DPI scaling is disabled by default on Windows at 120 DPI (125%) which might cause layout errors. Should you experience these issues you can avoid them using Java startup switches, as described here.

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/mailapi-1.5.5.jarJavaMail library for parsing MIME messages

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:

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

Depending on your JVM, you may also be able to omit javaw -jar and simply execute MimeBrowser.jar directly. MIME Browser does not currently write any configuration data to your system, nor anything else unless you explicitly issue a Save command (see below).

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 8.1 at 120 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. While Filter is active, the search text acts as an incremental search that updates the entry list as you type. This can be slow for long lists, especially if Combine is enabled, so you might want to disable Filter until you’re done typing. 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 — Shows the selected text content, if any, or else information on 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;…. 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 only two simple viewers, for plain text and HTML files. 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.)

4. Source Package

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

build.xmlCustomized build steps
manifest.mfApplication manifest placeholder
nbproject/*NetBeans project configuration
src/*Source code and resources
dist/javadoc/*Javadoc class reference

NetBeans injects custom dependencies into its Ant build scripts, so you’ll need an actual NetBeans installation to rebuild the project. Note that rebuilding will produce a bunch of unnecessary Java Web Start files, but I don’t see a way to disable that.

The NetBeans projects always disable JavaFX hardware acceleration (see Known JavaFX Issues). Remove the corresponding switch from “Project Properties: Run” if you wish to use hardware acceleration.

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.

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.

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 the JavaFX WebView automatically loads remote HTML content, which is even less desirable.

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. JavaFX currently does not provide a text field that allows selecting & copying text, shows a scroll bar for long content, and can be restricted to a single line in height. ScrollPane does not automatically shrink when no horizontal scroll bar is necessary, and TextArea cannot be reliably limited to a single line at all.

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.

MIME Browser cannot currently show any content other than plain text or HTML documents, not even images. A simple image viewer should be possible, and I may attempt it if I get enough requests for it.

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–2016 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 SIL Open Font License. This font is present as the separate file src/resources/FontAwesome.ttf in the source code package.

MIME message parsing is performed by the JavaMail library, made available under the Common Development And Distribution License. Since MIME Browser does not contact mail servers, I use the compact reference implementation without protocol providers. This library is present as file mailapi-1.5.4.jar in both binary and source package.