doc/index.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
   5 <head>
   6 <title>JavaInspect - Utility to visualize java software</title>
   7 <!-- 2015-03-03 Tue 22:38 -->
   8 <meta  http-equiv="Content-Type" content="text/html;charset=utf-8" />
   9 <meta  name="generator" content="Org-mode" />
  10 <meta  name="author" content="Svjatoslav Agejenko" />
  11 <style type="text/css">
  12  <!--/*--><![CDATA[/*><!--*/
  13   .title  { text-align: center; }
  14   .todo   { font-family: monospace; color: red; }
  15   .done   { color: green; }
  16   .tag    { background-color: #eee; font-family: monospace;
  17             padding: 2px; font-size: 80%; font-weight: normal; }
  18   .timestamp { color: #bebebe; }
  19   .timestamp-kwd { color: #5f9ea0; }
  20   .right  { margin-left: auto; margin-right: 0px;  text-align: right; }
  21   .left   { margin-left: 0px;  margin-right: auto; text-align: left; }
  22   .center { margin-left: auto; margin-right: auto; text-align: center; }
  23   .underline { text-decoration: underline; }
  24   #postamble p, #preamble p { font-size: 90%; margin: .2em; }
  25   p.verse { margin-left: 3%; }
  26   pre {
  27     border: 1px solid #ccc;
  28     box-shadow: 3px 3px 3px #eee;
  29     padding: 8pt;
  30     font-family: monospace;
  31     overflow: auto;
  32     margin: 1.2em;
  33   }
  34   pre.src {
  35     position: relative;
  36     overflow: visible;
  37     padding-top: 1.2em;
  38   }
  39   pre.src:before {
  40     display: none;
  41     position: absolute;
  42     background-color: white;
  43     top: -10px;
  44     right: 10px;
  45     padding: 3px;
  46     border: 1px solid black;
  47   }
  48   pre.src:hover:before { display: inline;}
  49   pre.src-sh:before    { content: 'sh'; }
  50   pre.src-bash:before  { content: 'sh'; }
  51   pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
  52   pre.src-R:before     { content: 'R'; }
  53   pre.src-perl:before  { content: 'Perl'; }
  54   pre.src-java:before  { content: 'Java'; }
  55   pre.src-sql:before   { content: 'SQL'; }
  56
  57   table { border-collapse:collapse; }
  58   caption.t-above { caption-side: top; }
  59   caption.t-bottom { caption-side: bottom; }
  60   td, th { vertical-align:top;  }
  61   th.right  { text-align: center;  }
  62   th.left   { text-align: center;   }
  63   th.center { text-align: center; }
  64   td.right  { text-align: right;  }
  65   td.left   { text-align: left;   }
  66   td.center { text-align: center; }
  67   dt { font-weight: bold; }
  68   .footpara:nth-child(2) { display: inline; }
  69   .footpara { display: block; }
  70   .footdef  { margin-bottom: 1em; }
  71   .figure { padding: 1em; }
  72   .figure p { text-align: center; }
  73   .inlinetask {
  74     padding: 10px;
  75     border: 2px solid gray;
  76     margin: 10px;
  77     background: #ffffcc;
  78   }
  79   #org-div-home-and-up
  80    { text-align: right; font-size: 70%; white-space: nowrap; }
  81   textarea { overflow-x: auto; }
  82   .linenr { font-size: smaller }
  83   .code-highlighted { background-color: #ffff00; }
  84   .org-info-js_info-navigation { border-style: none; }
  85   #org-info-js_console-label
  86     { font-size: 10px; font-weight: bold; white-space: nowrap; }
  87   .org-info-js_search-highlight
  88     { background-color: #ffff00; color: #000000; font-weight: bold; }
  89   /*]]>*/-->
  90 </style>
  91 <link rel="stylesheet" type="text/css" href="http://thomasf.github.io/solarized-css/solarized-dark.min.css" />
  92 <script type="text/javascript">
  93 /*
  94 @licstart  The following is the entire license notice for the
  95 JavaScript code in this tag.
  96
  97 Copyright (C) 2012-2013 Free Software Foundation, Inc.
  98
  99 The JavaScript code in this tag is free software: you can
 100 redistribute it and/or modify it under the terms of the GNU
 101 General Public License (GNU GPL) as published by the Free Software
 102 Foundation, either version 3 of the License, or (at your option)
 103 any later version.  The code is distributed WITHOUT ANY WARRANTY;
 104 without even the implied warranty of MERCHANTABILITY or FITNESS
 105 FOR A PARTICULAR PURPOSE.  See the GNU GPL for more details.
 106
 107 As additional permission under GNU GPL version 3 section 7, you
 108 may distribute non-source (e.g., minimized or compacted) forms of
 109 that code without the copy of the GNU GPL normally required by
 110 section 4, provided you include this license notice and a URL
 111 through which recipients can access the Corresponding Source.
 112
 113
 114 @licend  The above is the entire license notice
 115 for the JavaScript code in this tag.
 116 */
 117 <!--/*--><![CDATA[/*><!--*/
 118  function CodeHighlightOn(elem, id)
 119  {
 120    var target = document.getElementById(id);
 121    if(null != target) {
 122      elem.cacheClassElem = elem.className;
 123      elem.cacheClassTarget = target.className;
 124      target.className = "code-highlighted";
 125      elem.className   = "code-highlighted";
 126    }
 127  }
 128  function CodeHighlightOff(elem, id)
 129  {
 130    var target = document.getElementById(id);
 131    if(elem.cacheClassElem)
 132      elem.className = elem.cacheClassElem;
 133    if(elem.cacheClassTarget)
 134      target.className = elem.cacheClassTarget;
 135  }
 136 /*]]>*///-->
 137 </script>
 138 </head>
 139 <body>
 140 <div id="content">
 141 <h1 class="title">JavaInspect - Utility to visualize java software</h1>
 142 <div id="table-of-contents">
 143 <h2>Table of Contents</h2>
 144 <div id="text-table-of-contents">
 145 <ul>
 146 <li><a href="#sec-1">1. General</a></li>
 147 <li><a href="#sec-2">2. Example graphs</a></li>
 148 <li><a href="#sec-3">3. Usage</a>
 149 <ul>
 150 <li><a href="#sec-3-1">3.1. example 1: individually picked objects</a></li>
 151 <li><a href="#sec-3-2">3.2. example 2: scan java code, apply filters</a></li>
 152 </ul>
 153 </li>
 154 <li><a href="#sec-4">4. Embedding JavaInspect in your Maven project</a></li>
 155 <li><a href="#sec-5">5. Requirements</a></li>
 156 <li><a href="#sec-6">6. <span class="todo TODO">TODO</span> </a></li>
 157 </ul>
 158 </div>
 159 </div>
 160 <hr  />
 161 <ul class="org-ul">
 162 <li><a href="http://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz">download latest snapshot</a>
 163 </li>
 164
 165 <li>This program is free software; you can redistribute it and/or modify
 166 it under the terms of version 3 of the <a href="https://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public
 167 License</a> or later as published by the Free Software Foundation.
 168 </li>
 169
 170 <li>Program author:
 171 <ul class="org-ul">
 172 <li>Svjatoslav Agejenko
 173 </li>
 174 <li>Homepage: <a href="http://svjatoslav.eu">http://svjatoslav.eu</a>
 175 </li>
 176 <li>Email: <a href="mailto://svjatoslav@svjatoslav.eu">mailto://svjatoslav@svjatoslav.eu</a>
 177 </li>
 178 </ul>
 179 </li>
 180
 181 <li><a href="http://svjatoslav.eu/programs.jsp">other applications hosted at svjatoslav.eu</a>
 182 </li>
 183 </ul>
 184
 185 <div id="outline-container-sec-1" class="outline-2">
 186 <h2 id="sec-1"><span class="section-number-2">1</span> General</h2>
 187 <div class="outline-text-2" id="text-1">
 188 <p>
 189 Goal: simplify/speed up understanding the computer program code by
 190 automatically visualizing its structure.
 191 </p>
 192
 193 <p>
 194 JavaInspect is a Java library that primarily uses Java reflection to
 195 discover and visualize any part of Java program provided that
 196 classes to be visualised are available in the classpath.
 197 </p>
 198
 199 <p>
 200 JavaInspect currently has no GUI, configuration files, embedded
 201 scripting support, direct Maven or Ant integration. The only way to
 202 instuct Javainspect what to do is by using its Java API.
 203 </p>
 204
 205 <p>
 206 To get JavaInspect into same classpath with your projecs I so far came
 207 up with 2 solutions:
 208 </p>
 209
 210 <ol class="org-ol">
 211 <li>Add JavaInspect library in your project as a dependency.
 212 </li>
 213 <li>Create new Java project for the purpose visualizing your other
 214 projects and include JavaInspect and your projecs binary artifacts
 215 (Jar's) into new project classpath. Built binary Jar's (with no
 216 source code) are sufficient because JavaInspect operates via
 217 reflection.
 218 </li>
 219 </ol>
 220
 221 <p>
 222 After discovering application structure and optionally filtering out
 223 unimportant parts, JavaInspect produces GraphViz dot file that
 224 describes data to be visualized. Then launches GraphViz to generate
 225 bitmap graph in PNG format. By default on your Desktop directory.
 226 </p>
 227
 228 <p>
 229 Note: GraphViz is developed and tested so far only on GNU Linux.
 230 </p>
 231 </div>
 232 </div>
 233
 234 <div id="outline-container-sec-2" class="outline-2">
 235 <h2 id="sec-2"><span class="section-number-2">2</span> Example graphs</h2>
 236 <div class="outline-text-2" id="text-2">
 237 <ul class="org-ul">
 238 <li>A very simple example:
 239
 240
 241 <div class="figure">
 242 <p><a href="example.png"><img src="example.resized.png" alt="example.resized.png" /></a>
 243 </p>
 244 </div>
 245
 246 <p>
 247 Graph legend:
 248 </p>
 249
 250
 251 <div class="figure">
 252 <p><img src="legend.png" alt="legend.png" />
 253 </p>
 254 </div>
 255 </li>
 256
 257 <li>Example visualization of <a href="http://www2.svjatoslav.eu/gitbrowse/sixth/doc/">Sixth</a> project: <a href="http://www2.svjatoslav.eu/projects/sixth/codegraphs/">architecture graphs</a>.
 258 </li>
 259 </ul>
 260 </div>
 261 </div>
 262
 263 <div id="outline-container-sec-3" class="outline-2">
 264 <h2 id="sec-3"><span class="section-number-2">3</span> Usage</h2>
 265 <div class="outline-text-2" id="text-3">
 266 <p>
 267 Currently the only way to control JavaInspect is by using Java
 268 API. Simple Java based control/configuration code needs to be written
 269 for each project. I usually put such code into directories devoted for
 270 JUnit tests. Because it needs not to be compiled/embedded into final
 271 product or project artifact I'm just willing to visualize.
 272 </p>
 273
 274 <p>
 275 Control code in general does the following:
 276 </p>
 277 <ol class="org-ol">
 278 <li>Create graph object.
 279 </li>
 280 <li>Java reflection/classloaders does not provide mechanism for
 281 discovering all classes under given package. Therefore you need to
 282 declare at least some classes to be added to the graph by:
 283 <ul class="org-ul">
 284 <li>Manually adding individual classes to the graph.
 285 </li>
 286 <li>and/or: Let GraphViz recursively scan and parse specified
 287 directories with Java source code files to discover class names.
 288 </li>
 289 <li>For every class added to the graph, GraphViz will recursively
 290 inspect it and add all referecned classes to the graph as well.
 291 </li>
 292 </ul>
 293 </li>
 294 <li>Graphs easilly get very big and complex so optionally we filter
 295 important code using classname wildcards patterns based blacklist
 296 and/or whitelist.
 297 </li>
 298 <li>Optionally we can tune some rendering parameters like:
 299 <ul class="org-ul">
 300 <li>Possibility to remove orphaned classes (classes with no
 301 references) from the graph.
 302 </li>
 303 <li>Specify target directory for generated visualization
 304 files. (Default is user desktop directory)
 305 </li>
 306 <li>Keep intermediate GraphViz dot file for later inspection.
 307 </li>
 308 </ul>
 309 </li>
 310 <li>Render graph.
 311 </li>
 312 </ol>
 313 </div>
 314
 315
 316 <div id="outline-container-sec-3-1" class="outline-3">
 317 <h3 id="sec-3-1"><span class="section-number-3">3.1</span> example 1: individually picked objects</h3>
 318 <div class="outline-text-3" id="text-3-1">
 319 <p>
 320 This example demonstrates generating of class graph from hand picked
 321 classes and visualizing GraphViz itself.
 322 </p>
 323
 324 <div class="org-src-container">
 325
 326 <pre class="src src-java"><span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Create graph</span>
 327 <span style="color: #F92672;">final</span> <span style="color: #66D9EF;">ClassGraph</span> <span style="color: #FD971F;">graph</span> = <span style="color: #F92672;">new</span> <span style="color: #66D9EF;">ClassGraph</span>();
 328
 329 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Add some random object to the graph. GraphViz will detect Class from</span>
 330 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">the object.</span>
 331 graph.add(graph);
 332
 333 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Also add some random class to the graph.</span>
 334 graph.add(Utils.<span style="color: #F92672;">class</span>);
 335
 336 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Keep intermediary GraphViz DOT file for reference.</span>
 337 graph.setKeepDotFile(<span style="color: #FF80F4;">true</span>);
 338
 339 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Produce bitmap image titled "JavaInspect.png" to the user Desktop</span>
 340 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">directory</span>
 341 graph.generateGraph(<span style="color: #EEDC82;">"JavaInspect"</span>);
 342 </pre>
 343 </div>
 344
 345 <p>
 346 Note: if desired, more compact version of the above:
 347 </p>
 348 <div class="org-src-container">
 349
 350 <pre class="src src-java"><span style="color: #F92672;">new</span> <span style="color: #66D9EF;">ClassGraph</span>().add(randomObject, RandomClass.<span style="color: #F92672;">class</span>)
 351                 .setKeepDotFile(<span style="color: #FF80F4;">true</span>).generateGraph(<span style="color: #EEDC82;">"JavaInspect"</span>);
 352 </pre>
 353 </div>
 354
 355
 356 <p>
 357 Result:
 358 </p>
 359 <ul class="org-ul">
 360 <li>Generated DOT file: <a href="JavaInspect.dot">JavaInspect.dot</a>
 361 </li>
 362 <li>Generated PNG image: <a href="JavaInspect.png">JavaInspect.png</a>
 363 </li>
 364 </ul>
 365 </div>
 366 </div>
 367
 368 <div id="outline-container-sec-3-2" class="outline-3">
 369 <h3 id="sec-3-2"><span class="section-number-3">3.2</span> example 2: scan java code, apply filters</h3>
 370 <div class="outline-text-3" id="text-3-2">
 371 <div class="org-src-container">
 372
 373 <pre class="src src-java"><span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Create graph</span>
 374 <span style="color: #F92672;">final</span> <span style="color: #66D9EF;">ClassGraph</span> <span style="color: #FD971F;">graph</span> = <span style="color: #F92672;">new</span> <span style="color: #66D9EF;">ClassGraph</span>();
 375
 376 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Recursively scan current directory for Java source code and attempt</span>
 377 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">to detect class names from there to be added to the graph.</span>
 378 graph.addProject(<span style="color: #EEDC82;">"."</span>);
 379
 380 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Blacklist example classes from being shown on the graph</span>
 381 graph.blacklistClassPattern(<span style="color: #EEDC82;">"eu.svjatoslav.inspector.java.structure.example.*"</span>);
 382
 383 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">do not show single classes with no relationships on the graph</span>
 384 graph.hideOrphanedClasses();
 385
 386 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Produce bitmap image titled "JavaInspect full project.png" to the</span>
 387 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">user Desktop directory.</span>
 388 graph.generateGraph(<span style="color: #EEDC82;">"JavaInspect full project"</span>);
 389 </pre>
 390 </div>
 391 <p>
 392 Result:
 393 </p>
 394 <ul class="org-ul">
 395 <li>Generated PNG image: <a href="JavaInspect%20full%20project.png">JavaInspect full project.png</a>
 396 </li>
 397 </ul>
 398 </div>
 399 </div>
 400 </div>
 401
 402 <div id="outline-container-sec-4" class="outline-2">
 403 <h2 id="sec-4"><span class="section-number-2">4</span> Embedding JavaInspect in your Maven project</h2>
 404 <div class="outline-text-2" id="text-4">
 405 <p>
 406 Declare JavaInspect as dependency:
 407 </p>
 408 <div class="org-src-container">
 409
 410 <pre class="src src-xml">&lt;<span style="color: #A6E22E;">dependencies</span>&gt;
 411     ...
 412     &lt;<span style="color: #A6E22E;">dependency</span>&gt;
 413         &lt;<span style="color: #A6E22E;">groupId</span>&gt;eu.svjatoslav&lt;/<span style="color: #A6E22E;">groupId</span>&gt;
 414         &lt;<span style="color: #A6E22E;">artifactId</span>&gt;javainspect&lt;/<span style="color: #A6E22E;">artifactId</span>&gt;
 415         &lt;<span style="color: #A6E22E;">version</span>&gt;1.5-SNAPSHOT&lt;/<span style="color: #A6E22E;">version</span>&gt;
 416     &lt;/<span style="color: #A6E22E;">dependency</span>&gt;
 417     ...
 418 &lt;/<span style="color: #A6E22E;">dependencies</span>&gt;
 419 </pre>
 420 </div>
 421
 422
 423 <p>
 424 Add Maven repository to retrieve artifact from:
 425 </p>
 426 <div class="org-src-container">
 427
 428 <pre class="src src-xml">&lt;<span style="color: #A6E22E;">repositories</span>&gt;
 429     ...
 430     &lt;<span style="color: #A6E22E;">repository</span>&gt;
 431         &lt;<span style="color: #A6E22E;">id</span>&gt;svjatoslav.eu&lt;/<span style="color: #A6E22E;">id</span>&gt;
 432         &lt;<span style="color: #A6E22E;">name</span>&gt;Svjatoslav repository&lt;/<span style="color: #A6E22E;">name</span>&gt;
 433         &lt;<span style="color: #A6E22E;">url</span>&gt;http://www2.svjatoslav.eu/maven/&lt;/<span style="color: #A6E22E;">url</span>&gt;
 434     &lt;/<span style="color: #A6E22E;">repository</span>&gt;
 435     ...
 436 &lt;/<span style="color: #A6E22E;">repositories</span>&gt;
 437 </pre>
 438 </div>
 439 </div>
 440 </div>
 441
 442 <div id="outline-container-sec-5" class="outline-2">
 443 <h2 id="sec-5"><span class="section-number-2">5</span> Requirements</h2>
 444 <div class="outline-text-2" id="text-5">
 445 <p>
 446 <a href="http://www.graphviz.org/">GraphViz</a> - shall be installed on the computer.
 447 </p>
 448
 449 <p>
 450 On Ubuntu/Debian use:
 451 </p>
 452 <div class="org-src-container">
 453
 454 <pre class="src src-sh">sudo apt-get install graphviz
 455 </pre>
 456 </div>
 457 </div>
 458 </div>
 459 <div id="outline-container-sec-6" class="outline-2">
 460 <h2 id="sec-6"><span class="section-number-2">6</span> <span class="todo TODO">TODO</span> </h2>
 461 <div class="outline-text-2" id="text-6">
 462 <ul class="org-ul">
 463 <li>BUG: Should not hide references if there are too many of them to
 464 classes if referring classes are not visible anyway because of
 465 blacklist/whitelist rules. Basically reference counting should
 466 exclude not visible classes.
 467 </li>
 468 <li>FEATURE: add dark theme
 469 </li>
 470 <li>FEATURE: sort Class fields by alphabet
 471 </li>
 472 <li>FEATURE: visualize also concrete field values so it could be used as
 473 ultra cool runtime logging framework
 474 </li>
 475 <li>FEATURE: possibility to visualize structure and data from JVM
 476 snapshot
 477 </li>
 478 <li>FEATURE: possibility to attach to remote process to visualize
 479 data/structure using JVM debug port and mechanism.
 480 </li>
 481 <li>FEATURE: possibility to attach to JVM using JVM agent
 482 </li>
 483 <li>FEATURE: possibility to script javainspect behavior
 484 </li>
 485 <li>FEATURE: possibility to select classes/fields/values to be
 486 visualized in SQL like syntax
 487 </li>
 488 <li>FEATURE: configurable maven plugin to generate graphs as part of the
 489 project build/release process
 490 </li>
 491 </ul>
 492 </div>
 493 </div>
 494 </div>
 495 <div id="postamble" class="status">
 496 <p class="author">Author: Svjatoslav Agejenko</p>
 497 <p class="date">Created: 2015-03-03 Tue 22:38</p>
 498 <p class="creator"><a href="http://www.gnu.org/software/emacs/">Emacs</a> 24.4.1 (<a href="http://orgmode.org">Org</a> mode 8.2.10)</p>
 499 <p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
 500 </div>
 501 </body>
 502 </html>