JavaInspect - Utility to visualize java software

1. General
2. Example graphs
3. Usage -
-
4. Embedding JavaInspect in your Maven project
5. Requirements
6. TO DO

JavaInspect - Utility to visualize java software

download latest snapshot
download latest snapshot +
This program is free software; you can redistribute it and/or modify it under the terms of version 3 of the GNU Lesser General Public -License or later as published by the Free Software Foundation.
Program author:
- Svjatoslav Agejenko
- Homepage: http://svjatoslav.eu/
- Email: mailto://svjatoslav@svjatoslav.eu/
Svjatoslav Agejenko +
Homepage: http://svjatoslav.eu +
Email: mailto://svjatoslav@svjatoslav.eu +

+ -

other applications hosted at svjatoslav.eu

other applications hosted at svjatoslav.eu +

1 General

Goal: simplify/speed up understanding the computer program code by @@ -208,12 +247,14 @@ up with 2 solutions:

Add JavaInspect library in your project as a dependency.
Add JavaInspect library in your project as a dependency. +
Create new Java project for the purpose visualizing your other projects and include JavaInspect and your projecs binary artifacts (Jar's) into new project classpath. Built binary Jar's (with no source code) are sufficient because JavaInspect operates via -reflection.

@@ -224,42 +265,42 @@ bitmap graph in PNG format. By default on your Desktop directory.

-Note: GraphViz is developed and tested so far only on GNU Linux. +Note: GraphViz is developed and tested so far only on GNU/Linux.

2 Example graphs

-A very simple example: -
+
A very simple example: -
-
+
+

-
+
Graph legend:
-
-
+
+

-
Example visualization of Sixth project: architecture graphs.
Example visualization of Sixth project: architecture graphs. +

3 Usage

Currently the only way to control JavaInspect is by using Java @@ -273,35 +314,46 @@ product or project artifact I'm just willing to visualize. Control code in general does the following:

Create graph object.
Create graph object. +
Java reflection/classloaders does not provide mechanism for discovering all classes under given package. Therefore you need to declare at least some classes to be added to the graph by:
- Manually adding individual classes to the graph.
- Manually adding individual classes to the graph. +
- and/or: Let GraphViz recursively scan and parse specified -directories with Java source code files to discover class names.
- For every class added to the graph, GraphViz will recursively -inspect it and add all referecned classes to the graph as well.
Graphs easilly get very big and complex so optionally we filter important code using classname wildcards patterns based blacklist -and/or whitelist.
Optionally we can tune some rendering parameters like:
- Possibility to remove orphaned classes (classes with no -references) from the graph.
- Specify target directory for generated visualization -files. (Default is user desktop directory)
- Keep intermediate GraphViz dot file for later inspection.
Render graph.
Keep intermediate GraphViz dot file for later inspection. +
Render graph. +

3.1 example 1: individually picked objects

This example demonstrates generating of class graph from hand picked @@ -310,22 +362,22 @@ classes and visualizing GraphViz itself.

// Create graph
-final ClassGraph graph = new ClassGraph();
+// Create graph
+final ClassGraph graph = new ClassGraph();
 
-// Add some random object to the graph. GraphViz will detect Class from
-// the object.
-graph.add(graph);
+// Add some random object to the graph. GraphViz will detect Class from
+// the object.
+graph.add(graph);
 
-// Also add some random class to the graph.
-graph.add(Utils.class);
+// Also add some random class to the graph.
+graph.add(Utils.class);
 
-// Keep intermediary GraphViz DOT file for reference.
-graph.setKeepDotFile(true);
+// Keep intermediary GraphViz DOT file for reference.
+graph.setKeepDotFile(true);
 
-// Produce bitmap image titled "JavaInspect.png" to the user Desktop
-// directory
-graph.generateGraph("JavaInspect");
+// Produce bitmap image titled "JavaInspect.png" to the user Desktop
+// directory
+graph.generateGraph("JavaInspect");

@@ -334,8 +386,8 @@ Note: if desired, more compact version of the above:

new ClassGraph().add(randomObject, RandomClass.class)
-                .setKeepDotFile(true).generateGraph("JavaInspect");
+new ClassGraph().add(randomObject, RandomClass.class)
+                .setKeepDotFile(true).generateGraph("JavaInspect");

@@ -344,72 +396,77 @@ Note: if desired, more compact version of the above: Result:

Generated DOT file: JavaInspect.dot
Generated PNG image: JavaInspect.png
Generated DOT file: JavaInspect.dot +
Generated PNG image: JavaInspect.png +

3.2 example 2: scan java code, apply filters

// Create graph
-final ClassGraph graph = new ClassGraph();
+// Create graph
+final ClassGraph graph = new ClassGraph();
 
-// Recursively scan current directory for Java source code and attempt
-// to detect class names from there to be added to the graph.
-graph.addProject(".");
+// Recursively scan current directory for Java source code and attempt
+// to detect class names from there to be added to the graph.
+graph.addProject(".");
 
-// Blacklist example classes from being shown on the graph
-graph.blacklistClassPattern("eu.svjatoslav.inspector.java.structure.example.*");
+// Blacklist example classes from being shown on the graph
+graph.blacklistClassPattern("eu.svjatoslav.inspector.java.structure.example.*");
 
-// do not show single classes with no relationships on the graph
-graph.hideOrphanedClasses();
+// do not show single classes with no relationships on the graph
+graph.hideOrphanedClasses();
 
-// Produce bitmap image titled "JavaInspect full project.png" to the
-// user Desktop directory.
-graph.generateGraph("JavaInspect full project");
+// Produce bitmap image titled "JavaInspect full project.png" to the
+// user Desktop directory.
+graph.generateGraph("JavaInspect full project");

Result:

Generated PNG image: JavaInspect full project.png
Generated PNG image: JavaInspect full project.png +

3.3 example 3: GraphViz embedded in another project

Download project Sixth code snapshot.
Inspect and run *DataGraph.java*.
Download project Sixth code snapshot. +
Inspect and run *DataGraph.java*. +

4 Embedding JavaInspect in your Maven project

Declare JavaInspect as dependency:

<dependencies>
+<dependencies>
     ...
-    <dependency>
-        <groupId>eu.svjatoslav</groupId>
-        <artifactId>javainspect</artifactId>
-        <version>1.5</version>
-    </dependency>
+    <dependency>
+        <groupId>eu.svjatoslav</groupId>
+        <artifactId>javainspect</artifactId>
+        <version>1.5</version>
+    </dependency>
     ...
-</dependencies>
+</dependencies>

@@ -419,22 +476,22 @@ Add Maven repository to retrieve artifact from:

<repositories>
+<repositories>
     ...
-    <repository>
-        <id>svjatoslav.eu</id>
-        <name>Svjatoslav repository</name>
-        <url>http://www2.svjatoslav.eu/maven/</url>
-    </repository>
+    <repository>
+        <id>svjatoslav.eu</id>
+        <name>Svjatoslav repository</name>
+        <url>http://www2.svjatoslav.eu/maven/</url>
+    </repository>
     ...
-</repositories>
+</repositories>

5 Requirements

GraphViz - shall be installed on the computer. @@ -450,35 +507,64 @@ On Ubuntu/Debian use:

6 TO DO

BUG: Should not hide references if there are too many of them to classes if referring classes are not visible anyway because of blacklist/whitelist rules. -Basically reference counting should exclude not visible classes.
FEATURE: add dark theme
FEATURE: sort Class fields by alphabet
FEATURE: add dark theme +
FEATURE: sort Class fields by alphabet +
FEATURE: visualize also concrete field values so it could be used as -ultra cool runtime logging framework
FEATURE: possibility to visualize structure and data from JVM -snapshot
FEATURE: possibility to attach to remote process to visualize -data/structure using JVM debug port and mechanism.
FEATURE: possibility to attach to JVM using JVM agent
FEATURE: possibility to script javainspect behavior
FEATURE: possibility to attach to JVM using JVM agent +
FEATURE: possibility to script javainspect behavior +
FEATURE: possibility to select classes/fields/values to be -visualized in SQL like syntax
FEATURE: configurable maven plugin to generate graphs as part of the -project build/release process

+ diff --git a/doc/index.org b/doc/index.org index 42916a3..120b9e8 100644 --- a/doc/index.org +++ b/doc/index.org @@ -14,6 +14,16 @@ - [[http://svjatoslav.eu/programs.jsp][other applications hosted at svjatoslav.eu]] +* (document settings) :noexport: +** use dark style for TWBS-HTML exporter +#+HTML_HEAD: +#+HTML_HEAD: +#+HTML_HEAD: " +#+HTML_HEAD: + * General Goal: simplify/speed up understanding the computer program code by automatically visualizing its structure. @@ -41,7 +51,7 @@ unimportant parts, JavaInspect produces GraphViz dot file that describes data to be visualized. Then launches GraphViz to generate bitmap graph in PNG format. By default on your Desktop directory. -Note: GraphViz is developed and tested so far only on GNU Linux. +Note: GraphViz is developed and tested so far only on GNU/Linux. * Example graphs + A very simple example: -- 2.20.1 From 398b77318e2d84934ef5e2fa853b322df0146707 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Mon, 23 Jan 2017 12:32:04 +0200 Subject: [PATCH 05/16] Updated example links. --- doc/index.html | 6 +++--- doc/index.org | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/index.html b/doc/index.html index 5ee48a2..9f15392 100644 --- a/doc/index.html +++ b/doc/index.html @@ -2,7 +2,7 @@ JavaInspect - Utility to visualize java software - + @@ -293,7 +293,7 @@ Graph legend: -

Example visualization of Sixth project: architecture graphs. +

Example visualization of Sixth 3D project: architecture graphs.

@@ -562,7 +562,7 @@ project build/release process

diff --git a/doc/index.org b/doc/index.org index 120b9e8..085a858 100644 --- a/doc/index.org +++ b/doc/index.org @@ -62,7 +62,7 @@ Note: GraphViz is developed and tested so far only on GNU/Linux. file:legend.png -+ Example visualization of [[http://www2.svjatoslav.eu/gitbrowse/sixth/doc/][Sixth]] project: [[http://www2.svjatoslav.eu/projects/sixth/codegraphs/][architecture graphs]]. ++ Example visualization of [[http://www2.svjatoslav.eu/gitbrowse/sixth-3d/doc/][Sixth 3D]] project: [[http://www2.svjatoslav.eu/gitbrowse/sixth-3d/doc/codeGraph/][architecture graphs]]. * Usage Currently the only way to control JavaInspect is by using Java -- 2.20.1 From 54ee4f18181d978bb0c269b516d9654895e2b395 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Tue, 18 Apr 2017 12:32:37 +0300 Subject: [PATCH 06/16] PlantUML integration idea. --- doc/index.html | 6 ++++-- doc/index.org | 1 + 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/index.html b/doc/index.html index 9f15392..af7b23b 100644 --- a/doc/index.html +++ b/doc/index.html @@ -2,7 +2,7 @@ JavaInspect - Utility to visualize java software - + @@ -515,6 +515,8 @@ On Ubuntu/Debian use: referring classes are not visible anyway because of blacklist/whitelist rules. Basically reference counting should exclude not visible classes. +

FEATURE: integarte with PlantUML. +

FEATURE: add dark theme

FEATURE: sort Class fields by alphabet @@ -562,7 +564,7 @@ project build/release process

diff --git a/doc/index.org b/doc/index.org index 085a858..ac53f6b 100644 --- a/doc/index.org +++ b/doc/index.org @@ -195,6 +195,7 @@ sudo apt-get install graphviz - BUG: Should not hide references if there are too many of them to classes if referring classes are not visible anyway because of blacklist/whitelist rules. Basically reference counting should exclude not visible classes. +- FEATURE: integarte with [[http://plantuml.com/class-diagram][PlantUML]]. - FEATURE: add dark theme - FEATURE: sort Class fields by alphabet - FEATURE: visualize also concrete field values so it could be used as -- 2.20.1 From fa90e6506de0c6c93a087a6edbb52a378b5cded1 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Wed, 19 Apr 2017 22:48:36 +0300 Subject: [PATCH 07/16] Better variable names. --- javainspect.iml | 2 +- .../java/structure/FieldDescriptor.java | 34 +++++++++---------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/javainspect.iml b/javainspect.iml index 9036949..ea566de 100644 --- a/javainspect.iml +++ b/javainspect.iml @@ -1,6 +1,6 @@ - +

diff --git a/src/main/java/eu/svjatoslav/inspector/java/structure/FieldDescriptor.java b/src/main/java/eu/svjatoslav/inspector/java/structure/FieldDescriptor.java index 59f93fc..b6de871 100755 --- a/src/main/java/eu/svjatoslav/inspector/java/structure/FieldDescriptor.java +++ b/src/main/java/eu/svjatoslav/inspector/java/structure/FieldDescriptor.java @@ -1,6 +1,6 @@ /* * JavaInspect - Utility to visualize java software - * Copyright (C) 2013-2015, Svjatoslav Agejenko, svjatoslav@svjatoslav.eu + * Copyright (C) 2013-2017, Svjatoslav Agejenko, svjatoslav@svjatoslav.eu * * This program is free software; you can redistribute it and/or * modify it under the terms of version 3 of the GNU Lesser General Public License @@ -21,35 +21,35 @@ import java.util.List; public class FieldDescriptor implements GraphElement { - private final ClassDescriptor parentClass; + private final ClassDescriptor parentClassDescriptior; private final List typeArguments = new ArrayList(); private String name; private ClassDescriptor type; private boolean isInherited; public FieldDescriptor(final ClassDescriptor parent) { - parentClass = parent; + parentClassDescriptior = parent; } public void analyzeField(final Field field) { if (!field.getDeclaringClass().getName() - .equals(parentClass.getFullyQualifiedName())) + .equals(parentClassDescriptior.getFullyQualifiedName())) isInherited = true; name = field.getName(); - type = parentClass.getClassGraph().getOrCreateClassDescriptor( + type = parentClassDescriptior.getClassGraph().getOrCreateClassDescriptor( field.getType()); type.registerReference(); - final Type genericType = field.getGenericType(); - if (genericType instanceof ParameterizedType) { - final ParameterizedType pt = (ParameterizedType) genericType; - for (final Type t : pt.getActualTypeArguments()) - if (t instanceof Class) { - final Class cl = (Class) t; - final ClassDescriptor genericTypeDescriptor = parentClass - .getClassGraph().getOrCreateClassDescriptor(cl); + final Type fieldGenericType = field.getGenericType(); + if (fieldGenericType instanceof ParameterizedType) { + final ParameterizedType fieldParameterizedGenericType = (ParameterizedType) fieldGenericType; + for (final Type type : fieldParameterizedGenericType.getActualTypeArguments()) + if (type instanceof Class) { + final Class aClass = (Class) type; + final ClassDescriptor genericTypeDescriptor = parentClassDescriptior + .getClassGraph().getOrCreateClassDescriptor(aClass); genericTypeDescriptor.registerReference(); typeArguments.add(genericTypeDescriptor); } @@ -80,10 +80,10 @@ public class FieldDescriptor implements GraphElement { // main type boolean showLink = type.areReferencesShown(); - if (type == parentClass) + if (type == parentClassDescriptior) showLink = false; - if (parentClass.isEnum) + if (parentClassDescriptior.isEnum) showLink = false; if (showLink) @@ -103,7 +103,7 @@ public class FieldDescriptor implements GraphElement { final StringBuffer result = new StringBuffer(); result.append(" // " + name + "\n"); - if (parentClass.isEnum && (type == parentClass)) { + if (parentClassDescriptior.isEnum && (type == parentClassDescriptior)) { result.append(" "); result.append(name + "\n"); @@ -120,7 +120,7 @@ public class FieldDescriptor implements GraphElement { @Override public String getGraphId() { - return parentClass.getGraphId() + ":" + name; + return parentClassDescriptior.getGraphId() + ":" + name; } protected int getOutsideVisibleReferencesCount() { -- 2.20.1 From 2375888de0c132707f1512646210e0f2f366868b Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Wed, 19 Apr 2017 22:50:01 +0300 Subject: [PATCH 08/16] Bugfix: no langer generate illegal square brackets in the dot file --- .../inspector/java/structure/ClassDescriptor.java | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/main/java/eu/svjatoslav/inspector/java/structure/ClassDescriptor.java b/src/main/java/eu/svjatoslav/inspector/java/structure/ClassDescriptor.java index c21761c..3bd1049 100755 --- a/src/main/java/eu/svjatoslav/inspector/java/structure/ClassDescriptor.java +++ b/src/main/java/eu/svjatoslav/inspector/java/structure/ClassDescriptor.java @@ -318,8 +318,12 @@ public class ClassDescriptor implements GraphElement, Comparable Date: Wed, 19 Apr 2017 22:53:29 +0300 Subject: [PATCH 09/16] bugfix: Graphviz warning: aqua is not a known color. --- src/main/java/eu/svjatoslav/inspector/java/structure/Utils.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/java/eu/svjatoslav/inspector/java/structure/Utils.java b/src/main/java/eu/svjatoslav/inspector/java/structure/Utils.java index 41dc633..9f28ad1 100755 --- a/src/main/java/eu/svjatoslav/inspector/java/structure/Utils.java +++ b/src/main/java/eu/svjatoslav/inspector/java/structure/Utils.java @@ -96,7 +96,7 @@ public class Utils { lightColors.add("peachpuff2"); lightColors.add("seagreen1"); lightColors.add("violet"); - lightColors.add("aqua"); + lightColors.add("cyan"); lightColors.add("orange"); } -- 2.20.1 From e058812f4214955233c94e2d23cf23ec48a3f51c Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Wed, 19 Apr 2017 23:03:55 +0300 Subject: [PATCH 10/16] [maven-release-plugin] prepare release javainspect-1.6 --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 47acd34..c9d43e6 100644 --- a/pom.xml +++ b/pom.xml @@ -2,7 +2,7 @@ 4.0.0 eu.svjatoslav javainspect - 1.6-SNAPSHOT + 1.6 jar Java inspect Utility to visualize Java code -- 2.20.1 From 06305a7463d8cd1ad75d055ee226e021847930c4 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Wed, 19 Apr 2017 23:03:59 +0300 Subject: [PATCH 11/16] [maven-release-plugin] prepare for next development iteration --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index c9d43e6..4929dbe 100644 --- a/pom.xml +++ b/pom.xml @@ -2,7 +2,7 @@ 4.0.0 eu.svjatoslav javainspect - 1.6 + 1.7-SNAPSHOT jar Java inspect Utility to visualize Java code -- 2.20.1 From 948a8cc00e3dbfb7448bb76ff4b056d19bdfb863 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Wed, 19 Apr 2017 23:07:16 +0300 Subject: [PATCH 12/16] Updated version number in documentation. --- doc/index.html | 6 +++--- doc/index.org | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/index.html b/doc/index.html index af7b23b..59c8408 100644 --- a/doc/index.html +++ b/doc/index.html @@ -2,7 +2,7 @@ JavaInspect - Utility to visualize java software - + @@ -463,7 +463,7 @@ Declare JavaInspect as dependency: <dependency> <groupId>eu.svjatoslav</groupId> <artifactId>javainspect</artifactId> - <version>1.5</version> + <version>1.6</version> </dependency> ... </dependencies> @@ -564,7 +564,7 @@ project build/release process

JavaInspect - Utility to visualize java software

Table of Contents

JavaInspect - Utility to visualize java software

1 General

1 General

2 Example graphs

2 Example graphs

3 Usage

3 Usage

3.1 example 1: individually picked objects

3.1 example 1: individually picked objects

3.2 example 2: scan java code, apply filters

3.2 example 2: scan java code, apply filters

3.3 example 3: GraphViz embedded in another project

3.3 example 3: GraphViz embedded in another project

4 Embedding JavaInspect in your Maven project

4 Embedding JavaInspect in your Maven project

5 Requirements

5 Requirements

6 TO DO

6 TO DO