|Program||MIME Browser for EML files|
|Released||05 February 2019|
|Author||Christoph Nahr (Copyright)|
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.
The directory to which the binary package was unpacked contains the following files:
|MIME Browser version history|
|Screenshot for display & controls|
|Style sheet for ReadMe & WhatsNew|
|Project file for overview diagram|
|Precompiled executable Java archive|
|Sample configuration file for file extensions|
|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.
MIME Browser supports the following explicit and implicit start-up options:
MimeBrowser.cfgin the current directory, supplementing the built-in default file extensions and optionally a Swing Look & Feel.
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"
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
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).
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.
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.
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
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_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
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.)
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:
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.
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:
|IntelliJ project file|
|IntelliJ project metadata|
|Javadoc class reference|
|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.
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.
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.
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.
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.
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.
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.activation-1.2.0.jar in both binary and source package.
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/jstyleparser-3.2.jar, along with the license as
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
nekohtml-1.9.22.jar— NekoHTML, an HTML parser. Copyright © 2002-2013 Andy Clark and Marc Guillemot. The license is present as
slf4j-nop.17.25.jar— SLF4J, a logging facade. Copyright © 2004-2017 QOS.ch. The license is present as
unbescape-1.1.6.RELEASE.jar— unbescape, a text escaping library. Copyright © The UNBESCAPE Team. The license is present as
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