7 January 2020

Visualising Architecture: GraphML Charting Module Dependencies

When working with existing code, analysing module dependencies helps me understand the bigger picture. For well defined modules like Eclipse OSGi or Maven there are tools to show all modules and their inter dependencies, e.g. the Eclipse Dependency Visualization tool or the Maven Module Dependency Graph Creator. For legacy technologies like COBOL and NATURAL - and probably some more platforms - we struggle due to the lack of such tools. Then the best approach is to extract the necessary information and put it into a modern, well known format. I wrote about such an approach in the past, e.g. loading references from a CSV into Neo4j for easy navigation and visualization. Today I want to sketch another idea I have used since many years: Using GraphML to chart module dependencies. For example, the following graph shows the (filtered) modules of a NATURAL application together with their dependencies in an organic layout.

Some modules of a NATURAL application in an organic layout, 2017
Process
GraphML is an XML-based file format for graphs. [...] It uses an XML-based syntax and supports the entire range of possible graph structure constellations including directed, undirected, mixed graphs, hyper graphs, and application-specific attributes. That should be more than enough to visualize any module dependencies. In fact I just need nodes and edges. My process to use GraphML is always the same:
  1. Start with defining or extracting the modules and their dependencies.
  2. Create a little script which loads the extracted data and creates a raw GraphML XML file.
  3. Use an existing graph editor to tweak and layout the diagram.
  4. Export the the diagram as PDF or as image.
Get the raw data
Extracting the module information is highly programming language specific. For Java I used my JavaClass class file parser. For NATURAL I used a CSV of all references which was provided by my client. Usually regular expressions work well to parse import, using or include statements. For example to analyse plain C, scan for #include statements (as done in Schmidrules for Application Architecture. Unfortunately there is not much documentation available about Schmidrules, which I will fix in the future.)

Create the XML
The next task is to create the XML. I use a little Ruby script to serializes a graph of nodes into GraphML. The used Node class needs a name and a list of dependencies, which are Nodes again. save stores the graph as GraphML.
require 'rexml/document'

class GraphmlSerializer
  include REXML

  # Save the _graph_ to _filename_ .
  def save(filename, graph)
    File.open(filename + '.graphml', 'w') do |f|
      doc = graph_to_xml(graph)
      doc.write(out_string = '<?xml version="1.0" encoding="UTF-8" standalone="no"?>')
      f.print out_string
    end
  end

  # Return an XML document of the GraphML serialized _graph_ .
  def graph_to_xml(graph)
    doc = create_xml_doc
    container = add_graph_element(doc)
    graph.to_a.each { |node| add_node_as_xml(container, node) }
    doc
  end

  private

  def create_xml_doc
    REXML::Document.new
  end

  def add_graph_element(doc)
    root = doc.add_element('graphml',
      'xmlns' => 'http://graphml.graphdrawing.org/xmlns',
      'xmlns:y' => 'http://www.yworks.com/xml/graphml',
      'xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance',
      'xsi:schemaLocation' => 'http://graphml.graphdrawing.org/xmlns http://www.yworks.com/xml/schema/graphml/1.1/ygraphml.xsd')
    root.add_element('key', 'id' => 'n1',
                     'for' => 'node',
                     'yfiles.type' => 'nodegraphics')
    root.add_element('key', 'id' => 'e1',
                     'for' => 'edge',
                     'yfiles.type' => 'edgegraphics')

    root.add_element('graph', 'edgedefault' => 'directed')
  end

  public

  # Add the _node_ as XML to the _container_ .
  def add_node_as_xml(container, node)
    add_node_element(container, node)

    node.dependencies.each do |dep|
      add_edge_element(container, node, dep)
    end
  end

  private

  def add_node_element(container, node)
    elem = container.add_element('node', 'id' => node.name)
    shape_node = elem.add_element('data', 'key' => 'n1').
      add_element('y:ShapeNode')
    shape_node.
      add_element('y:NodeLabel').
      add_text(node.to_s)
  end

  def add_edge_element(container, node, dep)
    edge = container.add_element('edge')
    edge.add_attribute('id', node.name + '.' + dep.name)
    edge.add_attribute('source', node.name)
    edge.add_attribute('target', dep.name)
  end

end
Layout the diagram
I do not try to layout the graph when creating it. Existing tools do a much better job. I use the yEd Graph Editor. yEd is a Java application. Download and uncompress the zipped archive. To get the final diagram
  1. I load the GraphML file into the editor. (If the graph is huge, yEd needs more memory. yEd is just an executable Jar - Java Archive - it can get more heap on startup using java -XX:+UseG1GC -Xmx800m -jar ./yed-3.16.2.1/yed.jar.)
  2. Then I select all nodes and apply menu commands Tools/Fit Node to Label. This is because the size of the nodes does not match the size of the node's names.
  3. Finally I apply the menu commands Layout/Hierarchical or maybe Layout/Organic/Smart. In the end it needs some trial and error to find the proper layout.
Conclusion
This approach is very flexible. The nodes of the graph can be anything, a "module" can be a file, a folder or a bunch of folders. In the example shown above, the nodes where NATURAL modules (aka files), i.e. functions, subroutines, programs or includes. In another example shipped with JavaClass the nodes are components, i.e. source folders similar to Maven multi module projects. The diagram below shows the components of a product family of large Eclipse RCP applications with their dependencies in a hierarchical layout. Pretty crazy, isn't it. ;-)

Components of an Eclipse RCP application in hierarchical layout, 2012

27 December 2019

New Classes in Java 11

Java 11 is a LTS (Long Term Support) release, which means that it will get public updates till September 2022 and extended support until September 2026. While it is an important release, it does not add much to the platform, much like Java Update 10. Still Simon Ritter found 90 new features and APIs in JDK 11. Let's have a look at the new classes.

New HTTP Client
The Standard HTTP Client has been moved from jdk.incubator.http to java.net.http:
java.net.http.HttpClient
java.net.http.HttpClient$Builder
java.net.http.HttpClient$Redirect
java.net.http.HttpClient$Version
java.net.http.HttpConnectTimeoutException
java.net.http.HttpHeaders
java.net.http.HttpRequest
java.net.http.HttpRequest$BodyPublisher
java.net.http.HttpRequest$BodyPublishers
java.net.http.HttpRequest$Builder
java.net.http.HttpResponse
java.net.http.HttpResponse$BodyHandler
java.net.http.HttpResponse$BodyHandlers
java.net.http.HttpResponse$BodySubscriber
java.net.http.HttpResponse$BodySubscribers
java.net.http.HttpResponse$PushPromiseHandler
java.net.http.HttpResponse$ResponseInfo
java.net.http.HttpTimeoutException
java.net.http.WebSocket
java.net.http.WebSocket$Builder
java.net.http.WebSocket$Listener
java.net.http.WebSocketHandshakeException
Security
JEP 324: Key Agreement with Curve25519 and Curve448 comes with a few classes,
java.security.interfaces.XECKey
java.security.interfaces.XECPrivateKey
java.security.interfaces.XECPublicKey
java.security.spec.NamedParameterSpec
java.security.spec.XECPrivateKeySpec
java.security.spec.XECPublicKeySpec
as do the ChaCha20 and Poly1305 Cryptographic Algorithms: javax.crypto.spec.ChaCha20ParameterSpec.

Other Smaller Changes
There are around 20 other new classes including support for Dynamic Class-File Constants and the jaotc command.
java.lang.invoke.ConstantBootstraps

javax.print.attribute.standard.DialogOwner

jdk.nio.Channels
jdk.nio.Channels$SelectableChannelCloser

jdk.swing.interop.DispatcherWrapper
jdk.swing.interop.DragSourceContextWrapper
jdk.swing.interop.DropTargetContextWrapper
jdk.swing.interop.internal.InteropProviderImpl
jdk.swing.interop.LightweightContentWrapper
jdk.swing.interop.LightweightFrameWrapper
jdk.swing.interop.SwingInterOpUtils

jdk.tools.jaotc.aarch64.AArch64ELFMacroAssembler
jdk.tools.jaotc.aarch64.AArch64InstructionDecoder
jdk.tools.jaotc.binformat.elf.AArch64JELFRelocObject
jdk.tools.jaotc.binformat.elf.AMD64JELFRelocObject
Removal
Besides these few new classes, the real new thing in Java 11 is removal. The new Java drops much from the JDK. Really much: JavaFX is removed - it was just added in Java 8 and 9. Dropped packages are
javafx.* [8-10]
javafx.css [9-10]
javafx.css.converter [9-10]
javafx.fxml [9-10]
javafx.scene [9-10]
javafx.util [9-10]
Java EE and CORBA Modules are dropped:
javax.activation [6-10]
javax.activity [5-10]
javax.annotation [6-10]
javax.jnlp [5-10]
javax.jws [6-10]
javax.rmi.CORBA [3-10]
javax.security.auth.Policy [4-10]
javax.transaction [3-10]
javax.xml.bind [6-10]
javax.xml.soap [6-10]
javax.xml.ws [6-10]
jdk.management.cmm.SystemResourcePressureMXBean [8-10]
jdk.management.resource [8-10]
jdk.packager.services.singleton [only 10]
jdk.packager.services.userjvmoptions [9-10]
org.omg.CORBA [2-10]
Most of these classes have been added with Java 6, some even in the previous release (10).

List of all public classes
You can download the complete history of all public classes ever available in Java from version 1.0 to 11.0.2. Each class name is annotated with [release] showing the release it first appeared, e.g. java.lang.annotation.Annotation [5].

21 December 2019

Coderetreat Facilitation Podcast

tl;dr: I am podcasting about Coderetreat facilitation.

Impression Global Day of Coderetreat 2013 (C) Michael LeberI regularly facilitate Coderetreats - as part of my work as Code Cop and for the local Software Crafters community. To support people organising events in other cities, I run Coderetreat facilitation trainings each year, especially in the months before the Global Day (of Coderetreat). Based on the feedback I get, e.g. Thanks for the training today! Very helpful! I see that these trainings are helpful for people who want to run Coderetreats. Often people ask the same questions, so I decided to record the most common questions. I will publish the recordings as I create them, so it is a podcast. (A podcast is an episodic series of digital audio files that a user can download in order to listen.)

Get it here: coderetreat-facilitation.code-cop.org

About
In the podcast I am answering questions about Coderetreat hosting, facilitation and participation. It will help you run Coderetreats, Coding Dojos, hands on meetups and even classic training. Each episode covers two to three questions and takes up to 10 minutes. From time to time I will invite guest facilitators to discuss with me. In the first few episodes I will also cover basic questions about the Coderetreat itself, e.g. What is a Coderetreat?

Frequency
As each episode is short, I plan to release at least two each month. While I am too late for #GDCR19, there should be around 30 questions and answers ready for people who want to help organising the next #GDCR20. That would be like three hours facilitation training. That would be great. Let's see how far I get.

Questions
If you have any questions regarding your Coderetreat, Coding Dojo or hands-on workshop, please send me an email or leave a comment. I will answer the question in one of the next episodes.

Get it here: coderetreat-facilitation.code-cop.org