doc/index.org

   1 #+TITLE: JavaInspect - Utility to visualize java software
   2
   3 * (document settings) :noexport:
   4 ** use dark style for TWBS-HTML exporter
   5 #+HTML_HEAD: <link href="https://bootswatch.com/3/darkly/bootstrap.min.css" rel="stylesheet">
   6 #+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
   7 #+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.5/js/bootstrap.min.js"></script>
   8 #+HTML_HEAD: <style type="text/css">
   9 #+HTML_HEAD:   footer {background-color: #111 !important;}
  10 #+HTML_HEAD:   pre {background-color: #111; color: #ccc;}
  11 #+HTML_HEAD: </style>
  12
  13 * General
  14 - This program is free software: you can redistribute it and/or modify
  15   it under the terms of the [[https://www.gnu.org/licenses/lgpl.html][GNU Lesser General Public License]] as
  16   published by the Free Software Foundation, either version 3 of the
  17   License, or (at your option) any later version.
  18
  19 - Program authors:
  20   - Svjatoslav Agejenko
  21     - Homepage: http://svjatoslav.eu
  22     - Email: mailto://svjatoslav@svjatoslav.eu
  23     - [[http://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]
  24
  25   - Tony Bargnesi
  26     - GitHub fork for the project:
  27       https://github.com/abargnesi/javainspect
  28
  29 ** Source code
  30 - [[http://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]]
  31
  32 - [[http://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=summary][Browse Git repository online]]
  33
  34 - Clone Git repository using command:
  35   : git clone http://www2.svjatoslav.eu/git/javainspect.git
  36
  37 * Goal and operating principle
  38 Goal: simplify/speed up understanding the computer program code by
  39 automatically visualizing its structure.
  40
  41 [[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]].
  42
  43 JavaInspect can be used as a [[id:acf1896a-74b4-4914-acf6-a77075e07f25][standalone commandline utility]] as well as
  44 [[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][java library]]. JavaInspect uses primarily Java built-in reflection to
  45 discover and visualize any part of Java program.
  46
  47 JavaInspect currently has no GUI, configuration files, embedded
  48 scripting support, direct Maven or Ant integration. See [[id:2ad2889e-6c95-4662-b3f4-2c341fc74522][usage]] to learn
  49 how to instuct Javainspect what to do.
  50
  51 After discovering application structure and optionally filtering out
  52 unimportant parts, JavaInspect produces GraphViz dot file that
  53 describes data to be visualized. Then launches GraphViz to generate
  54 bitmap graph in PNG or SVG format.
  55
  56 By default on your Desktop directory when operated in library mode or
  57 current working directory when operated as standalone commandline
  58 application.
  59
  60 Notes:
  61 + JavaInspect is developed and tested so far only on GNU/Linux.
  62 + See: [[https://github.com/pahen/madge][Madge - similar tool for JavaScript]]
  63
  64 * Example graphs
  65 + A very simple example:
  66
  67     [[file:example.png][file:example.resized.png]]
  68
  69     Graph legend:
  70
  71     file:legend.png
  72
  73 + [[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]].
  74
  75 * Usage
  76   :PROPERTIES:
  77   :ID:       2ad2889e-6c95-4662-b3f4-2c341fc74522
  78   :END:
  79 JavaInspect can be controlled in 2 different ways:
  80 + [[id:acf1896a-74b4-4914-acf6-a77075e07f25][as standalone commandline utility]]
  81 + [[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][as embedded Java library via Java API]]
  82
  83 ** usage as commandline utility
  84    :PROPERTIES:
  85    :ID:       acf1896a-74b4-4914-acf6-a77075e07f25
  86    :END:
  87 To enable commandline support, (study and) execute script:
  88 : commandline launcher/install
  89
  90 Warning: It was tested only on Debian Stretch linux.
  91
  92 Available commandline arguments:
  93 #+BEGIN_VERSE
  94 -j (existing files)...
  95     JAR file(s) to render.
  96
  97 -n (mandatory, string)
  98     Graph name.
  99
 100 --debug
 101     Show debug info.
 102
 103 -k
 104     Keep dot file.
 105
 106 -h
 107     Hide orphaned classes.
 108
 109 -w (one to many strings)...
 110     Whitelist glob(s).
 111
 112 -b (one to many strings)...
 113     Blacklist glob(s).
 114
 115 -d (existingdirectory)
 116     Target directory. Default is current directory.
 117
 118 -t (options: png, svg)
 119     Target image type. Default is: svg.
 120 #+END_VERSE
 121 ** usage via Java API
 122    :PROPERTIES:
 123    :ID:       bbeeffc8-3767-440d-8d93-ec9124dd60ee
 124    :END:
 125 Requires that classes to be visualised are available in the classpath.
 126
 127 To get JavaInspect into same classpath with your projecs I so far came
 128 up with 2 solutions:
 129
 130 1. Add JavaInspect library in your project as a dependency.
 131
 132 2. Create new Java project for the purpose visualizing your other
 133    projects and include JavaInspect and your projecs binary artifacts
 134    (Jar's) into new project classpath. Built binary Jar's (with no
 135    source code) are sufficient because JavaInspect operates via
 136    reflection.
 137
 138 Simple Java based control/configuration code needs to be written for
 139 each project. I usually put such code into directories devoted for
 140 JUnit tests. Because it needs not to be compiled/embedded into final
 141 product or project artifact I'm just willing to visualize.
 142
 143 Control code in general does the following:
 144 1. Create graph object.
 145 2. Java reflection/classloaders does not provide mechanism for
 146    discovering all classes under given package. Therefore you need to
 147    declare at least some classes to be added to the graph by:
 148    + Manually adding individual classes to the graph.
 149    + and/or: Let GraphViz recursively scan and parse specified
 150      directories with Java source code files to discover class names.
 151    + For every class added to the graph, GraphViz will recursively
 152      inspect it and add all referecned classes to the graph as well.
 153 3. Graphs easilly get very big and complex so optionally we filter
 154    important code using classname wildcards patterns based blacklist
 155    and/or whitelist.
 156 4. Optionally we can tune some rendering parameters like:
 157    + Possibility to remove orphaned classes (classes with no
 158      references) from the graph.
 159    + Specify target directory for generated visualization
 160      files. (Default is user desktop directory)
 161    + Keep intermediate GraphViz dot file for later inspection.
 162 5. Render graph.
 163
 164
 165 *** example 1: individually picked objects
 166 This example demonstrates generating of class graph from hand picked
 167 classes and visualizing GraphViz itself.
 168
 169 #+BEGIN_SRC java
 170
 171 // Create graph
 172 final ClassGraph graph = new ClassGraph();
 173
 174 // Add some random object to the graph. GraphViz will detect Class from
 175 // the object.
 176 graph.add(graph);
 177
 178 // Also add some random class to the graph.
 179 graph.add(Utils.class);
 180
 181 // Keep intermediary GraphViz DOT file for reference.
 182 graph.setKeepDotFile(true);
 183
 184 // Produce bitmap image titled "JavaInspect.png" to the user Desktop
 185 // directory
 186 graph.generateGraph("JavaInspect");
 187
 188 #+END_SRC
 189
 190 Note: if desired, more compact version of the above:
 191 #+BEGIN_SRC java
 192 new ClassGraph().add(randomObject, RandomClass.class)
 193                 .setKeepDotFile(true).generateGraph("JavaInspect");
 194 #+END_SRC
 195
 196
 197 Result:
 198     - Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]]
 199     - Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]]
 200
 201 *** example 2: scan java code, apply filters
 202 #+BEGIN_SRC java
 203 // Create graph
 204 final ClassGraph graph = new ClassGraph();
 205
 206 // Recursively scan current directory for Java source code and attempt
 207 // to detect class names from there to be added to the graph.
 208 graph.addProject(".");
 209
 210 // Blacklist example classes from being shown on the graph
 211 graph.blacklistClassPattern("eu.svjatoslav.inspector.java.structure.example.*");
 212
 213 // do not show single classes with no relationships on the graph
 214 graph.hideOrphanedClasses();
 215
 216 // Produce bitmap image titled "JavaInspect full project.png" to the
 217 // user Desktop directory.
 218 graph.generateGraph("JavaInspect full project");
 219 #+END_SRC
 220 Result:
 221     - Generated PNG image: [[file:JavaInspect%20full%20project.png][JavaInspect full project.png]]
 222
 223 *** example 3: GraphViz embedded in another project
 224 1. Download project Sixth [[http://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][code snapshot]].
 225 2. Inspect and run *DataGraph.java*.
 226
 227 *** Embedding JavaInspect in your Maven project
 228
 229 Declare JavaInspect as dependency:
 230 #+BEGIN_SRC xml
 231 <dependencies>
 232     ...
 233     <dependency>
 234         <groupId>eu.svjatoslav</groupId>
 235         <artifactId>javainspect</artifactId>
 236         <version>1.6</version>
 237     </dependency>
 238     ...
 239 </dependencies>
 240 #+END_SRC
 241
 242
 243 Add Maven repository to retrieve artifact from:
 244 #+BEGIN_SRC xml
 245 <repositories>
 246     ...
 247     <repository>
 248         <id>svjatoslav.eu</id>
 249         <name>Svjatoslav repository</name>
 250         <url>http://www2.svjatoslav.eu/maven/</url>
 251     </repository>
 252     ...
 253 </repositories>
 254 #+END_SRC
 255
 256 * Requirements
 257 [[http://www.graphviz.org/][GraphViz]] - shall be installed on the computer.
 258
 259 On Ubuntu/Debian use:
 260 #+BEGIN_SRC sh
 261 sudo apt-get install graphviz
 262 #+END_SRC
 263 * TO DO
 264 Note: Because this is side project (and I have many of them) I can
 265 only contribute few hours per year at average. Any help is welcome.  A
 266 LOT of cool ideas could be implemented. For intstance:
 267
 268 - BUG: Should not hide references if there are too many of them to
 269   classes if referring classes are not visible anyway because of
 270   blacklist/whitelist rules. Basically reference counting should
 271   exclude not visible classes.
 272
 273 - BUG: Orphaned class removal does not work always. There are many
 274   bugs and corner cases to find and fix still.
 275
 276 - BUG: Code is not very readable. Document and refactor for better
 277   maintainability.
 278
 279 - FEATURE: Create installable DEB package.
 280   - Submit it to some Debian developer for integration or become
 281     Debian package maintainer.
 282
 283 - FEATURE: Make it modular. That is: central part, an application
 284   model could be standalone and serializable.
 285
 286   - There could be multiple ways to acquire model:
 287     - By introspecting application via Java reflections (current mode
 288       of operation).
 289     - By parsing java source. (unfinished)
 290
 291   - There could be ways to manipulate model:
 292     - Store/load/compare.
 293     - Trim uninteresting parts.
 294     - Highlight important parts.
 295
 296   - There could be multiple ways to render model:
 297     - PNG/SVG (currently implemented)
 298     - PlantUML (TODO)
 299     - Interactive 3D visualization (TODO)
 300
 301 - FEATURE: Replace internal java parser in package
 302   eu.svjatoslav.inspector.java.methods with: https://javaparser.org/
 303
 304 - FEATURE: Integarte with [[http://plantuml.com/class-diagram][PlantUML]].
 305
 306 - FEATURE: Add dark theme for generated graphs.
 307
 308 - FEATURE: Sort Class fields by alphabet.
 309
 310 - FEATURE: Visualize also concrete field values so it could be used as
 311   ultra cool runtime logging/debugging framework.
 312
 313 - FEATURE: Possibility to visualize structure and data from JVM
 314   snapshot.
 315
 316 - FEATURE: Possibility to attach to remote process to visualize
 317   data/structure using JVM debug port and mechanism.
 318
 319 - FEATURE: Possibility to attach to JVM using JVM agent.
 320
 321 - FEATURE: Possibility to inspect graphs in 3D using [[http://www2.svjatoslav.eu/gitbrowse/sixth-3d/doc/index.html][Sixth 3D engine]].
 322
 323 - FEATURE: Possibility to select classes/fields/values to be
 324   visualized in some graph query language. For greater flexibility in
 325   comparison to currently supported glob syntax.
 326
 327 - FEATURE: Add option to control JavaInspect via JSON or XML config
 328   file. For example different graphs for given project could be
 329   defined once in plain text config, possibly with the aid of some
 330   interactive utility. Then defined graphs could be updated as part of
 331   project build or release process.
 332
 333 - FEATURE: Configurable maven plugin to generate graphs as part of the
 334   project build/release process.