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 author:
  11   - Svjatoslav Agejenko
  12   - Homepage: http://svjatoslav.eu
  13   - Email: mailto://svjatoslav@svjatoslav.eu
  14
  15 - [[http://svjatoslav.eu/programs.jsp][other applications hosted at svjatoslav.eu]]
  16
  17 * General
  18 Goal: simplify/speed up understanding the computer program code by
  19 automatically visualizing its structure.
  20
  21 JavaInspect is a Java library that you can embed into your Java
  22 project with a few lines of Maven configuration and then visualize any
  23 part of your Java program structure with few simple JavaInspect API
  24 calls at application runtime.
  25
  26 JavaInspect uses Java reflection to discover class relations and
  27 structure and produces GraphViz dot file that describes your
  28 application. Then launches GraphViz to generate bitmap graph in PNG
  29 format on your Desktop directory.
  30
  31 * Current status
  32 This is simple utility, quickly written. Tested on GNU Linux (can be
  33 relatively simply ported to other operating systems too). So far I
  34 used it for my own needs. There might be bugs and missing
  35 features. Feedback and code contributions are welcome.
  36
  37 * Example graphs
  38 Example visualization of [[http://www2.svjatoslav.eu/gitbrowse/sixth/doc/][Sixth]] project: [[http://www2.svjatoslav.eu/projects/sixth/codegraphs/][architecture graphs]].
  39
  40 A very simple example:
  41
  42 [[file:example.png][file:example.resized.png]]
  43
  44
  45 Graph legend:
  46
  47 file:legend.png
  48
  49 * Usage example 1
  50 This example demonstrates generating of class graph from hand picked
  51 classes.
  52
  53 #+BEGIN_SRC java
  54   // Create graph
  55   final ClassGraph graph = new ClassGraph();
  56
  57   // While classes and objects can be immediately passed to ClassGraph
  58   // constructor as arguments, it is also possible to add them one by
  59   // one as in the following example.
  60
  61   // Add some object to the graph.
  62   graph.addObject(graph);
  63
  64   // Add some class to the graph.
  65   graph.addClass(Utils.class);
  66
  67   // Produce bitmap image titled "JavaInspect.png" to the user Desktop
  68   // directory and keep intermediary GraphViz DOT file for reference.
  69   graph.generateGraph("JavaInspect", true);
  70 #+END_SRC
  71
  72
  73
  74 Result:
  75     - Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]]
  76     - Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]]
  77
  78 * Usage example 2
  79 Recursively scan current directory for Java source code and attempt to
  80 detect class names from there to be added to the graph.
  81
  82 #+BEGIN_SRC java
  83   graph.addProject(".");
  84
  85   // Blacklist example classes from being shown on the graph
  86   graph.getFilter().blacklistClassPattern(
  87       "eu.svjatoslav.inspector.java.structure.example.*");
  88
  89   // do not show single classes with no relationships on the graph
  90   graph.hideOrphanedClasses();
  91
  92   // Produce bitmap image titled "JavaInspect full project.png" to the
  93   // user Desktop directory.
  94   graph.generateGraph("JavaInspect full project");
  95 #+END_SRC
  96 Result:
  97     - Generated PNG image: [[file:JavaInspect%20full%20project.png][JavaInspect full project.png]]
  98
  99 * Embedding JavaInspect in your Maven project
 100
 101 Declare JavaInspect as dependency:
 102 #+BEGIN_SRC xml
 103     <dependencies>
 104         ...
 105         <dependency>
 106             <groupId>eu.svjatoslav</groupId>
 107             <artifactId>javainspect</artifactId>
 108             <version>1.3</version>
 109         </dependency>
 110         ...
 111     </dependencies>
 112 #+END_SRC
 113
 114
 115 Add Maven repository to retrieve artifact from:
 116 #+BEGIN_SRC xml
 117     <repositories>
 118         ...
 119         <repository>
 120             <id>svjatoslav.eu</id>
 121             <name>Svjatoslav repository</name>
 122             <url>http://www2.svjatoslav.eu/maven/</url>
 123         </repository>
 124         ...
 125     </repositories>
 126 #+END_SRC
 127
 128 * Requirements
 129
 130 [[http://www.graphviz.org/][GraphViz]] - shall be installed on the computer.
 131
 132 On Ubuntu/Debian use:
 133 : sudo apt-get install graphviz
 134 * TODO
 135 - BUG: Should not hide references if there are too many of them to
 136   classes if referring classes are not visible anyway because of
 137   blacklist/whitelist rules. Basically reference counting should
 138   exclude not visible classes.
 139 - BUG: Current code is quite messy (because of lack of time) things
 140   were implemented ad-hoc. Needs cleanup/refactoring for better
 141   readability.
 142 - FEATURE: add dark theme
 143 - FEATURE: sort Class fields by alphabet
 144 - FEATURE: visualize also concrete field values so it could be used as
 145   ultra cool runtime logging framework
 146 - FEATURE: possibility to visualize structure and data from JVM
 147   snapshot
 148 - FEATURE: possibility to attach to remote process to visualize
 149   data/structure using JVM debug port and mechanism.
 150 - FEATURE: possibility to attach to JVM using JVM agent
 151 - FEATURE: possibility to script javainspect behavior
 152 - FEATURE: possibility to select classes/fields/values to be
 153   visualized in SQL like syntax
 154 - FEATURE: configurable maven plugin to generate graphs as part of the
 155   project build/release process