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 JavaInspect is a Java library that primarily uses Java reflection to
  36 discover and visualize any part of Java program provided that
  37 classes to be visualised are available in the classpath.
  38
  39 JavaInspect currently has no GUI, configuration files, embedded
  40 scripting support, direct Maven or Ant integration. The only way to
  41 instuct Javainspect what to do is by using its Java API.
  42
  43 To get JavaInspect into same classpath with your projecs I so far came
  44 up with 2 solutions:
  45
  46 1. Add JavaInspect library in your project as a dependency.
  47 2. Create new Java project for the purpose visualizing your other
  48    projects and include JavaInspect and your projecs binary artifacts
  49    (Jar's) into new project classpath. Built binary Jar's (with no
  50    source code) are sufficient because JavaInspect operates via
  51    reflection.
  52
  53 After discovering application structure and optionally filtering out
  54 unimportant parts, JavaInspect produces GraphViz dot file that
  55 describes data to be visualized. Then launches GraphViz to generate
  56 bitmap graph in PNG format. By default on your Desktop directory.
  57
  58 Note: GraphViz is developed and tested so far only on GNU/Linux.
  59
  60 * Example graphs
  61 + A very simple example:
  62
  63     [[file:example.png][file:example.resized.png]]
  64
  65     Graph legend:
  66
  67     file:legend.png
  68
  69 + 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]].
  70
  71 * Usage
  72 Currently the only way to control JavaInspect is by using Java
  73 API. Simple Java based control/configuration code needs to be written
  74 for each project. I usually put such code into directories devoted for
  75 JUnit tests. Because it needs not to be compiled/embedded into final
  76 product or project artifact I'm just willing to visualize.
  77
  78 Control code in general does the following:
  79 1. Create graph object.
  80 2. Java reflection/classloaders does not provide mechanism for
  81    discovering all classes under given package. Therefore you need to
  82    declare at least some classes to be added to the graph by:
  83    + Manually adding individual classes to the graph.
  84    + and/or: Let GraphViz recursively scan and parse specified
  85      directories with Java source code files to discover class names.
  86    + For every class added to the graph, GraphViz will recursively
  87      inspect it and add all referecned classes to the graph as well.
  88 3. Graphs easilly get very big and complex so optionally we filter
  89    important code using classname wildcards patterns based blacklist
  90    and/or whitelist.
  91 4. Optionally we can tune some rendering parameters like:
  92    + Possibility to remove orphaned classes (classes with no
  93      references) from the graph.
  94    + Specify target directory for generated visualization
  95      files. (Default is user desktop directory)
  96    + Keep intermediate GraphViz dot file for later inspection.
  97 5. Render graph.
  98
  99
 100 ** example 1: individually picked objects
 101 This example demonstrates generating of class graph from hand picked
 102 classes and visualizing GraphViz itself.
 103
 104 #+BEGIN_SRC java
 105
 106 // Create graph
 107 final ClassGraph graph = new ClassGraph();
 108
 109 // Add some random object to the graph. GraphViz will detect Class from
 110 // the object.
 111 graph.add(graph);
 112
 113 // Also add some random class to the graph.
 114 graph.add(Utils.class);
 115
 116 // Keep intermediary GraphViz DOT file for reference.
 117 graph.setKeepDotFile(true);
 118
 119 // Produce bitmap image titled "JavaInspect.png" to the user Desktop
 120 // directory
 121 graph.generateGraph("JavaInspect");
 122
 123 #+END_SRC
 124
 125 Note: if desired, more compact version of the above:
 126 #+BEGIN_SRC java
 127 new ClassGraph().add(randomObject, RandomClass.class)
 128                 .setKeepDotFile(true).generateGraph("JavaInspect");
 129 #+END_SRC
 130
 131
 132 Result:
 133     - Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]]
 134     - Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]]
 135
 136 ** example 2: scan java code, apply filters
 137 #+BEGIN_SRC java
 138 // Create graph
 139 final ClassGraph graph = new ClassGraph();
 140
 141 // Recursively scan current directory for Java source code and attempt
 142 // to detect class names from there to be added to the graph.
 143 graph.addProject(".");
 144
 145 // Blacklist example classes from being shown on the graph
 146 graph.blacklistClassPattern("eu.svjatoslav.inspector.java.structure.example.*");
 147
 148 // do not show single classes with no relationships on the graph
 149 graph.hideOrphanedClasses();
 150
 151 // Produce bitmap image titled "JavaInspect full project.png" to the
 152 // user Desktop directory.
 153 graph.generateGraph("JavaInspect full project");
 154 #+END_SRC
 155 Result:
 156     - Generated PNG image: [[file:JavaInspect%20full%20project.png][JavaInspect full project.png]]
 157
 158 ** example 3: GraphViz embedded in another project
 159 1. Download project Sixth [[http://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][code snapshot]].
 160 2. Inspect and run *DataGraph.java*.
 161
 162 * Embedding JavaInspect in your Maven project
 163
 164 Declare JavaInspect as dependency:
 165 #+BEGIN_SRC xml
 166 <dependencies>
 167     ...
 168     <dependency>
 169         <groupId>eu.svjatoslav</groupId>
 170         <artifactId>javainspect</artifactId>
 171         <version>1.6</version>
 172     </dependency>
 173     ...
 174 </dependencies>
 175 #+END_SRC
 176
 177
 178 Add Maven repository to retrieve artifact from:
 179 #+BEGIN_SRC xml
 180 <repositories>
 181     ...
 182     <repository>
 183         <id>svjatoslav.eu</id>
 184         <name>Svjatoslav repository</name>
 185         <url>http://www2.svjatoslav.eu/maven/</url>
 186     </repository>
 187     ...
 188 </repositories>
 189 #+END_SRC
 190
 191 * Requirements
 192 [[http://www.graphviz.org/][GraphViz]] - shall be installed on the computer.
 193
 194 On Ubuntu/Debian use:
 195 #+BEGIN_SRC sh
 196 sudo apt-get install graphviz
 197 #+END_SRC
 198 * TO DO
 199 - BUG: Should not hide references if there are too many of them to classes if
 200   referring classes are not visible anyway because of blacklist/whitelist rules.
 201   Basically reference counting should exclude not visible classes.
 202 - FEATURE: replace internal java parser in package
 203   eu.svjatoslav.inspector.java.methods with: https://javaparser.org/
 204 - FEATURE: integarte with [[http://plantuml.com/class-diagram][PlantUML]].
 205 - FEATURE: add dark theme
 206 - FEATURE: sort Class fields by alphabet
 207 - FEATURE: visualize also concrete field values so it could be used as
 208   ultra cool runtime logging framework
 209 - FEATURE: possibility to visualize structure and data from JVM
 210   snapshot
 211 - FEATURE: possibility to attach to remote process to visualize
 212   data/structure using JVM debug port and mechanism.
 213 - FEATURE: possibility to attach to JVM using JVM agent
 214 - FEATURE: possibility to script javainspect behavior
 215 - FEATURE: possibility to select classes/fields/values to be
 216   visualized in SQL like syntax
 217 - FEATURE: configurable maven plugin to generate graphs as part of the
 218   project build/release process