#+TITLE: JavaInspect - Utility to visualize java software
------
-- [[http://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz][download latest snapshot]]
+* (document settings) :noexport:
+** use dark style for TWBS-HTML exporter
+#+HTML_HEAD: <link href="https://bootswatch.com/3/darkly/bootstrap.min.css" rel="stylesheet">
+#+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
+#+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.5/js/bootstrap.min.js"></script>
+#+HTML_HEAD: <style type="text/css">
+#+HTML_HEAD: footer {background-color: #111 !important;}
+#+HTML_HEAD: pre {background-color: #111; color: #ccc;}
+#+HTML_HEAD: </style>
-- This program is free software; you can redistribute it and/or modify
- it under the terms of version 3 of the [[https://www.gnu.org/licenses/lgpl.html][GNU Lesser General Public
- License]] or later as published by the Free Software Foundation.
+* General
+- This program is free software: you can redistribute it and/or modify
+ it under the terms of the [[https://www.gnu.org/licenses/lgpl.html][GNU Lesser General Public License]] as
+ published by the Free Software Foundation, either version 3 of the
+ License, or (at your option) any later version.
- Program authors:
- Svjatoslav Agejenko
- - Homepage: http://svjatoslav.eu
+ - Homepage: https://svjatoslav.eu
- Email: mailto://svjatoslav@svjatoslav.eu
+ - [[https://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]
- Tony Bargnesi
- GitHub fork for the project:
https://github.com/abargnesi/javainspect
-- [[http://www.svjatoslav.eu/programs.jsp][other applications hosted at svjatoslav.eu]]
+** Source code
+:PROPERTIES:
+:ID: 032b7997-f582-4203-b31a-43ef7b654ed6
+:END:
+- [[https://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]]
-* (document settings) :noexport:
-** use dark style for TWBS-HTML exporter
-#+HTML_HEAD: <link href="https://bootswatch.com/4/darkly/bootstrap.min.css" rel="stylesheet">
-#+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
-#+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.1/js/bootstrap.min.js"></script>"
-#+HTML_HEAD: <style type="text/css">
-#+HTML_HEAD: footer {background-color: #111 !important;}
-#+HTML_HEAD: pre {background-color: #111; color: #ccc;}
-#+HTML_HEAD: </style>
+- [[https://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=summary][Browse Git repository online]]
-* General
+- Clone Git repository using command:
+ : git clone https://www2.svjatoslav.eu/git/javainspect.git
+
+* Goal and operating principle
Goal: simplify/speed up understanding the computer program code by
automatically visualizing its structure.
-[[http://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[http://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]].
+[[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[https://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]].
JavaInspect can be used as a [[id:acf1896a-74b4-4914-acf6-a77075e07f25][standalone commandline utility]] as well as
[[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][java library]]. JavaInspect uses primarily Java built-in reflection to
discover and visualize any part of Java program.
-JavaInspect currently has no GUI, configuration files, embedded
-scripting support, direct Maven or Ant integration. See [[id:2ad2889e-6c95-4662-b3f4-2c341fc74522][usage]] to learn
-how to instuct Javainspect what to do.
+JavaInspect currently has no graphical user interface, configuration
+files, embedded scripting support, direct Maven, Gradle or Ant
+integration. See [[id:2ad2889e-6c95-4662-b3f4-2c341fc74522][usage]] to learn how to instuct Javainspect what to do.
After discovering application structure and optionally filtering out
unimportant parts, JavaInspect produces GraphViz dot file that
-describes data to be visualized. Then launches GraphViz to generate
+describes data to be visualized. Then launches [[https://graphviz.org/][GraphViz]] to generate
bitmap graph in PNG or SVG format.
-By default on your Desktop directory when operated in library mode or
-current working directory when operated as standalone commandline
-application.
-
-Note: GraphViz is developed and tested so far only on GNU/Linux.
+Notes:
++ JavaInspect is developed and tested so far only on GNU/Linux.
* Example graphs
+ A very simple example:
- [[file:example.png][file:example.resized.png]]
+ [[file:example.png][file:example-thumbnail.png]]
Graph legend:
file:legend.png
-+ [[http://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[http://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]].
+
++ [[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[https://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]].
+
+* Installation
+[[http://www.graphviz.org/][GraphViz]] - shall be installed on the computer.
+
+On Ubuntu/Debian GraphViz can be installed using:
+#+BEGIN_SRC sh
+sudo apt-get install graphviz
+#+END_SRC
+
+To use JavaInspect via Java API, no further installation is
+needed. JavaInspect will be embedded into your project as dependency.
+This is described in [[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][usage via Java API]]. It will expect GraphViz to be
+available in the system.
+
+To use JavaInspect as a commandline tool, JavaInspect source
+repository has to be cloned locally: See [[id:032b7997-f582-4203-b31a-43ef7b654ed6][Source code]].
+
+Then study and execute installation script:
+: commandline launcher/install
+
+After installation, new commandline tool should be available
+: javainspect
+
+Quick commandline usage help can be viewed by issuing
+: javainspect --help
* Usage
:PROPERTIES:
+ [[id:acf1896a-74b4-4914-acf6-a77075e07f25][as standalone commandline utility]]
+ [[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][as embedded Java library via Java API]]
-** usage as commandline utility
+** Usage as commandline utility
:PROPERTIES:
:ID: acf1896a-74b4-4914-acf6-a77075e07f25
:END:
-To enable commandline support, (study and) execute script:
-: commandline launcher/install
-
-Warning: It was tested only on Debian Stretch linux.
-
-Available commandline arguments:
+*** Available commandline arguments
#+BEGIN_VERSE
-j (existing files)...
JAR file(s) to render.
--n (mandatory, string)
- Graph name.
+-c (existing directories)...
+ Classpath directories
+
+-n (string)
+ Graph name. (default: "graph")
--debug
Show debug info.
+-h, --help
+ Show commandline usage help.
+
-k
Keep dot file.
--h
+-ho
Hide orphaned classes.
-w (one to many strings)...
-b (one to many strings)...
Blacklist glob(s).
--d (existingdirectory)
+-r (one to many strings)...
+ root class(es).
+
+-d (existing directory)
Target directory. Default is current directory.
-t (options: png, svg)
Target image type. Default is: svg.
#+END_VERSE
-** usage via Java API
+*** Specifying classes to render
+Normal Java application has immense complexity. In addition to code
+that was directly written by particular project developers, lots of
+functionality is typically added as frameworks or libraries to the
+project. In addition there is significant Java standard library.
+
+Because JavaInspect uses reflection, it does not easily distinguish
+between those. In normal situation you would rather want to visualize
+only code that was developed specifically for your project and leave
+frameworks like Spring etc. out. If you visualize all classes that are
+possibly reachable from you project, you will easily get huge and
+incomprehensible graph.
+
+JavaInspect can digest compiled Java classes in 2 modes:
+1. Provide list of Jar files. Use *-j* option.
+2. Provide list of filesystem directories that can be used as
+ classpath root. Use *-c* option.
+
+Currently JavaInspect uses following algorithm to add classes to
+rendered graph:
+
+- All classes that were found in Jar files are added to graph by default.
+- None of the classes that were found in filesystem directories are
+ added to the graph by default (unless explicitly referenced). (TODO:
+ for consistency it would be better to add them too by default)
+- If whitelist is specified (*-w* option) everything that is not
+ matched by whitelist pattern(s) will be removed from the graph.
+- If blacklist is specified (*-b* option) everything that is matched
+ by blacklist pattern(s) will be removed from the graph.
+- Root classes can be specified using *-r* option. Root classes will
+ be added to the graph. JavaInspect will then try to recursively
+ discover all classes that were referenced by root class and add
+ those also to the graph.
+
+** Usage via Java API
:PROPERTIES:
:ID: bbeeffc8-3767-440d-8d93-ec9124dd60ee
:END:
1. Create graph object.
2. 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.
- + 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.
+ declare at least some classes to be added to the graph by manually
+ adding individual classes to the graph. For every class added to
+ the graph, GraphViz will recursively inspect it and add all
+ referecned classes to the graph as well.
3. Graphs easilly get very big and complex so optionally we filter
- important code using classname wildcards patterns based blacklist
- and/or whitelist.
+ important code using classname [[https://en.wikipedia.org/wiki/Glob_(programming)][glob]] patterns based blacklist and/or
+ whitelist.
4. 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)
+ files. (Default is current directory)
+ Keep intermediate GraphViz dot file for later inspection.
5. Render graph.
-*** example 1: individually picked objects
+*** Example 1: individually picked objects
This example demonstrates generating of class graph from hand picked
classes and visualizing GraphViz itself.
- Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]]
- Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]]
-*** example 2: scan java code, apply filters
-#+BEGIN_SRC java
-// 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(".");
-
-// 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();
-
-// Produce bitmap image titled "JavaInspect full project.png" to the
-// user Desktop directory.
-graph.generateGraph("JavaInspect full project");
-#+END_SRC
-Result:
- - Generated PNG image: [[file:JavaInspect%20full%20project.png][JavaInspect full project.png]]
-
-*** example 3: GraphViz embedded in another project
-1. Download project Sixth [[http://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][code snapshot]].
+*** Example 2: GraphViz embedded in another project
+1. Download project Sixth [[https://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][code snapshot]].
2. Inspect and run *DataGraph.java*.
*** Embedding JavaInspect in your Maven project
<dependency>
<groupId>eu.svjatoslav</groupId>
<artifactId>javainspect</artifactId>
- <version>1.6</version>
+ <version>1.7</version>
</dependency>
...
</dependencies>
</repositories>
#+END_SRC
-* Requirements
-[[http://www.graphviz.org/][GraphViz]] - shall be installed on the computer.
-
-On Ubuntu/Debian use:
-#+BEGIN_SRC sh
-sudo apt-get install graphviz
-#+END_SRC
* TO DO
Note: Because this is side project (and I have many of them) I can
only contribute few hours per year at average. Any help is welcome. A
- PlantUML (TODO)
- Interactive 3D visualization (TODO)
-- FEATURE: Replace internal java parser in package
- eu.svjatoslav.inspector.java.methods with: https://javaparser.org/
+- FEATURE: Implement (or integrate existing java parser
+ https://javaparser.org/) to be able to produce code visualizations
+ based on source code (in addition to current reflection based
+ approach).
- FEATURE: Integarte with [[http://plantuml.com/class-diagram][PlantUML]].
- FEATURE: Possibility to attach to JVM using JVM agent.
-- FEATURE: Possibility to inspect graphs in 3D using [[http://www2.svjatoslav.eu/gitbrowse/sixth-3d/doc/index.html][Sixth 3D engine]].
+- FEATURE: Possibility to inspect graphs in 3D using [[https://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D engine]].
- FEATURE: Possibility to select classes/fields/values to be
visualized in some graph query language. For greater flexibility in
- FEATURE: Configurable maven plugin to generate graphs as part of the
project build/release process.
+* See also
+Similar or alternative solutions:
++ http://www.class-visualizer.net/
++ [[https://github.com/pahen/madge][Madge - similar tool for JavaScript]]
projects / javainspect.git / blobdiff