ReadMe for MIME Browser 2.1.0

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:

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:

• One configuration file named MimeBrowser.cfg in the current directory, supplementing the built-in default file extensions and optionally a Swing Look & Feel.
• One command-line argument to specify the initial directory and/or document. The default is the current user’s home directory, with no document initially selected.

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.

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

• Open Browser (Ctrl+O) — Navigate to a different root directory, e.g. another Windows drive letter.
• Refresh Display (F5) — Reload both the current folder and the current document.
• Current Folder — Jump to any parent of the current folder by clicking on the corresponding directory component. Alt+Backspace goes up one level.
• About MIME Browser (F1) — Shows the application’s version number and release date, plus hyperlinks to send me an email, visit the official website, and show this ReadMe file.

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

• Combine (Alt+C) — Enable to combine all entries from the specified number of subdirectory levels with the entries of the current folder. Subdirectory entries are prefixed by their relative path.
• Filter (Alt+F) — Enable to filter entries by a search term. Matching is case-insensitive (Simple), case-sensitive (Case), or via Java regular expressions (Regex). You can search each file’s Name or Text, or require that Either or Both name and text pass the filter. Only files are filtered, not directories.
• Name — Only considers ordinary file names, not the embedded file names of MIME attachments.
• Text — Examines all textual header fields of MIME messages, as well as any MIME parts that are declared as plain text, HTML or XML. Examines other files only if the extension indicates plain text, HTML or XML contents, according to the Configuration File.

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.

• Click on the Name, Modified, and Size headers to sort by the corresponding values. Click again to invert the sorting order.
• Click & drag the right edge of the Name column to change its width.
• Double-click on any subdirectory entry to make it the new selected folder.
• Double-click on any file entry to show information and contents below.

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.

• Click the file path to launch the document in its associated application, if any.
• Drag the splitter bar above the file path to resize the folder & document views.

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

• Select any text and press Ctrl+C to copy it to the clipboard.
• Click on a header field and use the cursor keys to scroll through long text.
• You can edit header fields but this has no effect (see Known Issues).

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

• Use the drop-down box to show a different part of a multi-part message.

7. Content — Customize and manipulate the selected content.

• Show Text (Ctrl+T) — Toggles plain text view for HTML content and unrecognized file types, and toggles informational text for image content. Plain text for unrecognized content may result in gibberish, and may also take a while if the file is big. Does not work on unsupported MIME parts.
• Save (Ctrl+S) — Save the selected MIME part to disk (for MIME messages), or copy the selected file elsewhere (for all other file types).
• Save All (Ctrl+Shift+S) — Save all parts of the selected MIME message to disk. Has no effect for other file types.
• Zoom In/Out (Ctrl +/–) — Increase or decrease the size of plain txt in 25% steps. The percentage number shows the current zoom level.
• Use the drop-down box to select a different font for plain text, including XML content. This has no effect for HTML 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.

• For plain text, select any text and press Ctrl+C to copy it to the clipboard.
• You cannot select text in HTML content, as noted in Known Issues.

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

• MIME_MESSAGE — a MIME message with one or more parts, e.g. various message formats or attachments. Individual parts are shown if they match one of the other types or an image type.
• TEXT_HTML — an HTML document, equivalent to MIME content type text/html. Shown using CSSBox, a non-browser library for HTML display (see Copyright Notice). There is no support for JavaScript or showing image parts inline, but remote content is automatically loaded.
• TEXT_PLAIN — a plain text document, equivalent to MIME content type text/plain. You can select any installed text font that can display at least the ASCII range of characters. The appropriate character set should be automatically detected by the Java runtime or the JavaMail library.
• TEXT_XML — an XML document, equivalent to MIME content type text/xml. Shown in the the same way as TEXT_PLAIN contents.

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:

• Metal — javax.swing.plaf.metal.MetalLookAndFeel
• Nimbus — javax.swing.plaf.nimbus.NimbusLookAndFeel
• CDE/Motif — com.sun.java.swing.plaf.motif.MotifLookAndFeel
• Windows — com.sun.java.swing.plaf.windows.WindowsLookAndFeel
• Windows Classic — com.sun.java.swing.plaf.windows.WindowsClassicLookAndFeel

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:

• GTK+ — com.sun.java.swing.plaf.gtk.GTKLookAndFeel
• Macintosh — javax.swing.plaf.mac.MacLookAndFeel (found by web search)

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:

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!

When the list of folder entries is resorted using the column headers, subdirectories will no longer appear in alphabetical order at the top of the list, but rather in the requested sorting order.

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 at all, 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.

In rare cases, an image part in a supported format will be decoded correctly only the first time that part is selected. On subsequent attempts decoding will fail, triggering a message about an unsupported format. I cannot currently think of any possible causes or remedies.

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.

7. Copyright Notice

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–2021 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-2019 Radek Burget and made available under the GNU Lesser General Public License v3.0. These libraries are present as lib/cssbox-4.17.jar and lib/jstyleparser-3.5.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.

• antlr4-runtime-4.5.3.jar — ANTLR, a parser generator. Copyright © 2012-2017 The ANTLR Project (Terence Parr and Sam Harwell). The license is present as BSD-ANTLR.txt.
• nekohtml-1.9.22.jar — NekoHTML, an HTML parser. Copyright © 2002-2013 Andy Clark and Marc Guillemot. The license is present as Apache-2.0.txt.
• slf4j-api.17.25.jar and slf4j-nop.17.25.jar — SLF4J, a logging facade. Copyright © 2004-2017 QOS.ch. The license is present as MIT-SLF4J.txt.
• unbescape-1.1.6.RELEASE.jar — unbescape, a text escaping library. Copyright © The UNBESCAPE Team. The license is present as Apache-2.0.txt.
• xercesImpl-2.12.0.jar and xml-apis-1.4.01.jar — Apache Xerces, an XML parser and manipulator. Copyright © 1999-2018 The Apache Software Foundation. The license is present as Apache-2.0.txt.