ReadMe for Class Diagrammer 2.2.0

Table of Contents

1. System Requirements
2. Package Contents
3. Usage Overview
4. Source Package
5. Changes from .NET Version
6. Known Issues
7. Copyright Notice

1. System Requirements

Class Diagrammer is a JavaFX 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 9.0.4 which can be obtained from the Oracle Technology Network.

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.

2. Package Contents

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

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

3. Usage Overview

Use the command line javaw -jar Diagrammer.jar to run Class Diagrammer. Depending on your JVM, you may also be able to omit javaw -jar and execute Diagrammer.jar directly, or to simply double-click on Diagrammer.jar in your favorite file explorer.

See the help system (Help: Contents, F1) for general functionality and usage details. Open the supplied file SampleProject.xml to see some diagrams based on the Class Diagrammer distribution itself. You can also download the precreated PDF output.

Class Diagrammer creates a folder called DiagrammerFx in the current user’s home directory to store user settings and temporary files for the help system. If creation of that folder fails, Class Diagrammer will attempt to store settings directly in the current user’s home directory.

Console Runner

Use the command line java -jar Diagrammer.Core.jar to start the console runner and see a usage description. Supply the name of a Class Diagrammer project file as an argument, such as the supplied SampleProject.xml, to build all its outputs. The console runner does not access the user-specific DiagrammerFx folder or its contents.

4. Source Package

The source package is available as a separate download on the Class Diagrammer home page. The expected environment is IntelliJ IDEA 2017.3.4 with Oracle JDK 9.0.4. 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.

Class Diagrammer Core

The source package contains two IntelliJ projects: the main project Diagrammer for the JavaFX-based GUI executable, and the library project Diagrammer.Core with the actual layout engine and console runner.

Diagrammer.Core is an almost pure Swing/AWT project whose only JavaFX reference is to SimpleBooleanProperty. The JavaFX-based front-end Diagrammer converts diagrams to a JavaFX Canvas via FXGraphics2D, and Diagrammer.Core produces SVG and PDF via JFreeSVG and OrsonPDF, respectively (see Copyright).

5. Changes from .NET Version

Class Diagrammer is mostly a direct Java/JavaFX port of my older .NET/WPF application. For those who have used the older version, here is a list of significant changes in functionality.

Inputs & Packages

Input files are now JAR files instead of .NET assemblies, and accordingly specified by the XML element jarFile instead of assembly in project files. More importantly, whereas both version support class diagrams the Java version only supports package diagrams (i.e. logical namespaces) whereas the .NET version only supports assembly diagrams (i.e. deployment units).

The .NET version assumes that .NET assembly names are typically identical with the enclosed namespaces, so one diagram covers both use cases. This simplification is not possible in Java where JAR file names are wildly different from the enclosed package names. Since Class Diagrammer is intended to focus on the logical program structure, I chose to ignore deployment units and only offer package diagrams.

The Java version does not allow dynamic loading and unloading of JAR files within a project. This should not much affect users, however. When you change the JAR file setup, the current project is silently closed and reloaded. This is reasonably fast and should rarely be required anyway, once a project has been set up. The Java version does not automatically remove elements along with their JAR files. Should a reload fail because of such elements, an error message appears and the previous JAR file setup is restored.

The Java version refers to “packages” in its GUI display and help system but to “namespaces” in its source code, Javadoc comments, and project XML files. This simplified porting from the .NET version and is also the more common term, used both by .NET and C++.

The command line runner of the Java version requires valid file paths without wildcard characters, unless they are resolved by your shell. The .NET version expands wildcards and automatically searches the user’s home directory for file names without absolute paths.

Output Formats

Both versions support output to BMP, JPEG, PDF, and PNG files. The Java version adds SVG and HTML (= SVG wrapped in an HTML document), courtesy of JFreeSVG. These formats are very useful for embedded diagrams in HTML documentation.

The Java version drops GIF, Print, TIFF, WMP, and XPS. WMP & XPS are Windows niche formats that I never found a use for. GIF & TIFF are popular but provide no benefit over PNG. Print used to be supported because I initially had no PDF output library, so I instead printed to an Adobe Acrobat printer driver. With a direct PDF output target, Print has become obsolete. So has the “Output Orientation” setting (portrait or landscape) which is only meaningful for printers.

Running outputs from the Java GUI executable always brings up a dialog with progress information that remains open when finished. The “Summarize Output” option is therefore redundant and has been removed.

User Interface

The Java version lacks some UI functionality on the diagram display, mostly because UML elements are now drawn directly onto a canvas rather than represented by independent graphical objects.

• There is no dynamic highlight for the element under the mouse cursor.
• You cannot bring one of multiple overlapping elements to the front. Their z-order is now always identical to the alphabetic order of element names.
• Single mouse clicks no longer select elements (or bring them to the front). Instead, they directly show “Change Layout/Relation” dialogs as appropriate. The .NET version employed double clicks for this purpose which the Java version no longer uses at all.
• You cannot move elements with the cursor keys, only by dragging with the mouse. Cursor keys now always operate the scroll bars of the diagram display.

Various Changes

Project XML files are no longer pointlessly tagged with the namespace www.kynosarges.de.

The “Show Packages” option has no effect in package diagrams, as obviously all members of each element box share the same package. This was potentially different in the .NET version, see above.

Nested classes are always shown with the containing class names, but separated with :: (two colons) instead of . (one dot) for greater clarity.

The Java version does not show instance field values from constant expressions because Java cannot extract those without instantiating an object. There is no Java equivalent to FieldInfo.GetRawConstantValue which holds compiled initializer expressions. The Java version does show initial non-default static field values for primitives and strings, regardless of whether they are declared final.

The Java version can show the original names of method parameters, but this requires that the source code is compiled with the -parameters flag. Java class files do not store parameter names by default, so for source code compiled without -parameters synthesized placeholder names of the form argX appear instead. This is also documented in the online help for the “Parameter Names” display option.

6. Known Issues

Modular JAR files are supported but module information is not currently available for diagrams. A future version may support modules in a similar fashion as packages.

To edit the contents of cells in a table view, double-click on them and press Enter when finished. Merely leaving the cell with Tab will keep the cell in editing mode, without committing the new value.

When the bounding rectangles of multiple relations overlap, you can only select the topmost one. Move the mouse pointer outside of the topmost relation’s bounding rectangle to select other relations.

On different Java versions, the interline spacing of existing diagrams may change depending on whether the corresponding Java AWT implementation correctly detects the built-in leading of certain fonts. Use the setting “Display Options: Font: Leading” to correct for such cases. See the online help for details.

Despite lossy compression, JPEG output files may be larger than PNG output files. JPEG compression is not designed for text and cannot reliably shrink Class Diagrammer output files while retaining good image quality. If file size is critical you should try all acceptable formats (except BMP).

7. Copyright Notice

All files – individual files, multi-file packages, and individual files contained in multi-file packages – that constitute the original distribution of Class Diagrammer are Copyright © 2010–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

Class Diagrammer includes three libraries by David Gilbert which are Copyright © 2013–2017 by Object Refinery Limited. They are distributed under two different licenses, as described below. You can find the complete source code at GitHub or Maven Central (my source).

FXGraphics2D — FXGraphics2D 1.6 handles Graphics2D drawing to a JavaFX Canvas. Released as free software under the BSD 3-Clause license.

JFreeSVG — JFreeSVG 3.3 produces SVG & HTML output files. Released as free software under the terms of the GNU General Public License version 3 (GPLv3).

OrsonPDF — OrsonPDF 1.8 produces PDF output files. Released as free software under the terms of the GPLv3, see above.