doc/index.org

   1 #+TITLE: JavaInspect - Utility to visualize java software
   2
   3 -----
   4
   5 - [[http://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz][download]]
   6 - [[http://svjatoslav.eu/programs.jsp][other applications hosted at svjatoslav.eu]]
   7 - Program author:
   8     - Svjatoslav Agejenko
   9     - Homepage: http://svjatoslav.eu
  10     - Email: mailto://svjatoslav@svjatoslav.eu
  11
  12 * General
  13 Goal: simplify/speed up understanding the computer program code by
  14 automatically visualizing its structure.
  15
  16 JavaInspect is a Java library that you can embed into your Java
  17 project with a few lines of Maven configuration and then visualize any
  18 part of your Java program structure with few simple JavaInspect API
  19 calls at application runtime.
  20
  21 JavaInspect uses Java reflection to discover class relations and
  22 structure and produces GraphViz dot file that describes your
  23 application. Then launches GraphViz to generate bitmap graph in PNG
  24 format on your Desktop directory.
  25
  26 * Current status
  27 This is simple utility, quickly written. Tested on GNU Linux (can be
  28 relatively simply ported to other operating systems too). So far I
  29 used it for my own needs. There might be bugs and missing
  30 features. Feedback and code contributions are welcome.
  31
  32 * Example graphs
  33 Example visualization of [[http://www2.svjatoslav.eu/gitbrowse/sixth/doc/][Sixth]] project: [[http://www2.svjatoslav.eu/projects/sixth/codegraphs/][architecture graphs]].
  34
  35 A very simple example:
  36
  37 [[file:example.png][file:example.resized.png]]
  38
  39
  40 Graph legend:
  41
  42 file:legend.png
  43
  44 * Usage example 1
  45 This example demonstrates generating of class graph from hand picked
  46 classes.
  47
  48 #+BEGIN_SRC java
  49   // Create graph
  50   final ClassGraph graph = new ClassGraph();
  51
  52   // While classes and objects can be immediately passed to ClassGraph
  53   // constructor as arguments, it is also possible to add them one by
  54   // one as in the following example.
  55
  56   // Add some object to the graph.
  57   graph.addObject(graph);
  58
  59   // Add some class to the graph.
  60   graph.addClass(Utils.class);
  61
  62   // Produce bitmap image titled "JavaInspect.png" to the user Desktop
  63   // directory and keep intermediary GraphViz DOT file for reference.
  64   graph.generateGraph("JavaInspect", true);
  65 #+END_SRC
  66
  67
  68
  69 Result:
  70     - Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]]
  71     - Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]]
  72
  73 * Usage example 2
  74 Recursively scan current directory for Java source code and attempt to
  75 detect class names from there to be added to the graph.
  76
  77 #+BEGIN_SRC java
  78   graph.addProject(".");
  79
  80   // Blacklist example classes from being shown on the graph
  81   graph.getFilter().blacklistClassPattern(
  82       "eu.svjatoslav.inspector.java.structure.example.*");
  83
  84   // do not show single classes with no relationships on the graph
  85   graph.hideOrphanedClasses();
  86
  87   // Produce bitmap image titled "JavaInspect full project.png" to the
  88   // user Desktop directory.
  89   graph.generateGraph("JavaInspect full project");
  90 #+END_SRC
  91 Result:
  92     - Generated PNG image: [[file:JavaInspect%20full%20project.png][JavaInspect full project.png]]
  93
  94 * Embedding JavaInspect in your Maven project
  95
  96 Declare JavaInspect as dependency:
  97 #+BEGIN_SRC xml
  98     <dependencies>
  99         ...
 100         <dependency>
 101             <groupId>eu.svjatoslav</groupId>
 102             <artifactId>javainspect</artifactId>
 103             <version>1.3</version>
 104         </dependency>
 105         ...
 106     </dependencies>
 107 #+END_SRC
 108
 109
 110 Add Maven repository to retrieve artifact from:
 111 #+BEGIN_SRC xml
 112     <repositories>
 113         ...
 114         <repository>
 115             <id>svjatoslav.eu</id>
 116             <name>Svjatoslav repository</name>
 117             <url>http://www2.svjatoslav.eu/maven/</url>
 118         </repository>
 119         ...
 120     </repositories>
 121 #+END_SRC
 122
 123 * Requirements
 124
 125 [[http://www.graphviz.org/][GraphViz]] - shall be installed on the computer.
 126
 127 On Ubuntu/Debian use:
 128 : sudo apt-get install graphviz