ReadMe for Class Diagrammer 2.1.0

ProgramClass Diagrammer for Java
Version2.1.0 (History)
Released02 December 2016
AuthorChristoph Nahr (Copyright)
Contactwebmaster@kynosarges.org
Websitekynosarges.org/Diagrammer.html

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 desktop 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.

2. Package Contents

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

ReadMe.htmlThis file
WhatsNew.htmlClass Diagrammer version history
project.cssStyle sheet for ReadMe & WhatsNew
Diagrammer.jarClass Diagrammer GUI executable
Diagrammer.Core.jarClass Diagrammer console runner
SampleProject.xmlClass Diagrammer sample project
help/*Class Diagrammer help system (view index.html)
lib/Diagrammer.Core.jarClass Diagrammer core library (see below)
lib/*Third-party libraries for Class Diagrammer

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

Technical Note. The same file, Diagrammer.Core.jar, is installed in two locations: in the top-level directory and in the lib subdirectory. This is intentional. The lib copy exists so that Diagrammer.jar can load it as a library, and the top-level copy exists to be run from the command line (which in turn needs a lib subdirectory to find its own required third-party libraries).

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 directly 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.

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.

4. Source Package

The source package is available as a separate download on the Class Diagrammer home page. The expected environment is NetBeans 8.2 with Oracle JDK 8u112. 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.

Class Diagrammer Core

The source package contains two NetBeans 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).

The Javadoc class reference for the main project links into that for the core project, using relative file paths. For this to work you need to keep both projects side-by-side in the same parent directory. When rebuilding you must first generate Javadoc files for the core project, then for the main project.

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.

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

Resizable windows do not have sensible minimum sizes because JavaFX does not currently scale minimum (or maximum) sizes with screen DPI. This bug will hopefully get fixed in a future Java release.

If you manually edit the value of an input field, you must press Enter to ensure the new value is committed. Simply leaving the input field with Tab will show the new value to the user, but supply the old value to the application. This is a JavaFX issue regarding input controls losing focus.

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.

Despite lossy compression, JPEG output files are much bigger than PNG output files. From my experimentation, JPEG compression cannot shrink Class Diagrammer output files while retaining good image quality. Use PNG output unless JPEG is absolutely required.

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

Class Diagrammer includes three libraries which are Copyright © 2013–2016 by Object Refinery Limited. Each is distributed under a different license, as described below. You can find the complete source code at the linked home pages.

FXGraphics2DFXGraphics2D 1.5 handles Graphics2D drawing to a JavaFX Canvas. Released as free software under a BSD-style license, packaged as lib/fxgraphics2d-license.txt.

JFreeSVGJFreeSVG 3.2 produces SVG & HTML output files. Released as free software under the terms of the GNU General Public License version 3 (GPLv3), packaged as lib/gpl-3.0.txt.

OrsonPDFOrsonPDF 1.7 produces PDF output files. Released as free software under the terms of the GPLv3, see above. Also available as proprietary software for non-GPL projects.