doc/index.org

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