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-02-03 Tue 20:39 -->
   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. Current status</a></li>
 148 <li><a href="#sec-3">3. Example graphs</a></li>
 149 <li><a href="#sec-4">4. Usage example 1</a></li>
 150 <li><a href="#sec-5">5. Usage example 2</a></li>
 151 <li><a href="#sec-6">6. Embedding JavaInspect in your Maven project</a></li>
 152 <li><a href="#sec-7">7. Requirements</a></li>
 153 <li><a href="#sec-8">8. <span class="todo TODO">TODO</span> </a></li>
 154 </ul>
 155 </div>
 156 </div>
 157 <hr  />
 158 <ul class="org-ul">
 159 <li><a href="http://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz">download latest snapshot</a>
 160 </li>
 161
 162 <li>This program is free software; you can redistribute it and/or modify
 163 it under the terms of version 3 of the <a href="https://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public
 164 License</a> or later as published by the Free Software Foundation.
 165 </li>
 166
 167 <li>Program author:
 168 <ul class="org-ul">
 169 <li>Svjatoslav Agejenko
 170 </li>
 171 <li>Homepage: <a href="http://svjatoslav.eu">http://svjatoslav.eu</a>
 172 </li>
 173 <li>Email: <a href="mailto://svjatoslav@svjatoslav.eu">mailto://svjatoslav@svjatoslav.eu</a>
 174 </li>
 175 </ul>
 176 </li>
 177
 178 <li><a href="http://svjatoslav.eu/programs.jsp">other applications hosted at svjatoslav.eu</a>
 179 </li>
 180 </ul>
 181
 182 <div id="outline-container-sec-1" class="outline-2">
 183 <h2 id="sec-1"><span class="section-number-2">1</span> General</h2>
 184 <div class="outline-text-2" id="text-1">
 185 <p>
 186 Goal: simplify/speed up understanding the computer program code by
 187 automatically visualizing its structure.
 188 </p>
 189
 190 <p>
 191 JavaInspect is a Java library that you can embed into your Java
 192 project with a few lines of Maven configuration and then visualize any
 193 part of your Java program structure with few simple JavaInspect API
 194 calls at application runtime.
 195 </p>
 196
 197 <p>
 198 JavaInspect uses Java reflection to discover class relations and
 199 structure and produces GraphViz dot file that describes your
 200 application. Then launches GraphViz to generate bitmap graph in PNG
 201 format on your Desktop directory.
 202 </p>
 203 </div>
 204 </div>
 205
 206 <div id="outline-container-sec-2" class="outline-2">
 207 <h2 id="sec-2"><span class="section-number-2">2</span> Current status</h2>
 208 <div class="outline-text-2" id="text-2">
 209 <p>
 210 This is simple utility, quickly written. Tested on GNU Linux (can be
 211 relatively simply ported to other operating systems too). So far I
 212 used it for my own needs. There might be bugs and missing
 213 features. Feedback and code contributions are welcome.
 214 </p>
 215 </div>
 216 </div>
 217
 218 <div id="outline-container-sec-3" class="outline-2">
 219 <h2 id="sec-3"><span class="section-number-2">3</span> Example graphs</h2>
 220 <div class="outline-text-2" id="text-3">
 221 <p>
 222 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>.
 223 </p>
 224
 225 <p>
 226 A very simple example:
 227 </p>
 228
 229
 230 <div class="figure">
 231 <p><a href="example.png"><img src="example.resized.png" alt="example.resized.png" /></a>
 232 </p>
 233 </div>
 234
 235
 236 <p>
 237 Graph legend:
 238 </p>
 239
 240
 241 <div class="figure">
 242 <p><img src="legend.png" alt="legend.png" />
 243 </p>
 244 </div>
 245 </div>
 246 </div>
 247
 248 <div id="outline-container-sec-4" class="outline-2">
 249 <h2 id="sec-4"><span class="section-number-2">4</span> Usage example 1</h2>
 250 <div class="outline-text-2" id="text-4">
 251 <p>
 252 This example demonstrates generating of class graph from hand picked
 253 classes.
 254 </p>
 255
 256 <div class="org-src-container">
 257
 258 <pre class="src src-java"><span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Create graph</span>
 259 <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>();
 260
 261 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">While classes and objects can be immediately passed to ClassGraph</span>
 262 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">constructor as arguments, it is also possible to add them one by</span>
 263 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">one as in the following example.</span>
 264
 265 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Add some object to the graph.</span>
 266 graph.addObject(graph);
 267
 268 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Add some class to the graph.</span>
 269 graph.addClass(Utils.<span style="color: #F92672;">class</span>);
 270
 271 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Produce bitmap image titled "JavaInspect.png" to the user Desktop</span>
 272 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">directory and keep intermediary GraphViz DOT file for reference.</span>
 273 graph.generateGraph(<span style="color: #EEDC82;">"JavaInspect"</span>, <span style="color: #FF80F4;">true</span>);
 274 </pre>
 275 </div>
 276
 277
 278
 279 <p>
 280 Result:
 281 </p>
 282 <ul class="org-ul">
 283 <li>Generated DOT file: <a href="JavaInspect.dot">JavaInspect.dot</a>
 284 </li>
 285 <li>Generated PNG image: <a href="JavaInspect.png">JavaInspect.png</a>
 286 </li>
 287 </ul>
 288 </div>
 289 </div>
 290
 291 <div id="outline-container-sec-5" class="outline-2">
 292 <h2 id="sec-5"><span class="section-number-2">5</span> Usage example 2</h2>
 293 <div class="outline-text-2" id="text-5">
 294 <p>
 295 Recursively scan current directory for Java source code and attempt to
 296 detect class names from there to be added to the graph.
 297 </p>
 298
 299 <div class="org-src-container">
 300
 301 <pre class="src src-java">graph.addProject(<span style="color: #EEDC82;">"."</span>);
 302
 303 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Blacklist example classes from being shown on the graph</span>
 304 graph.getFilter().blacklistClassPattern(
 305     <span style="color: #EEDC82;">"eu.svjatoslav.inspector.java.structure.example.*"</span>);
 306
 307 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">do not show single classes with no relationships on the graph</span>
 308 graph.hideOrphanedClasses();
 309
 310 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Produce bitmap image titled "JavaInspect full project.png" to the</span>
 311 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">user Desktop directory.</span>
 312 graph.generateGraph(<span style="color: #EEDC82;">"JavaInspect full project"</span>);
 313 </pre>
 314 </div>
 315 <p>
 316 Result:
 317 </p>
 318 <ul class="org-ul">
 319 <li>Generated PNG image: <a href="JavaInspect%20full%20project.png">JavaInspect full project.png</a>
 320 </li>
 321 </ul>
 322 </div>
 323 </div>
 324
 325 <div id="outline-container-sec-6" class="outline-2">
 326 <h2 id="sec-6"><span class="section-number-2">6</span> Embedding JavaInspect in your Maven project</h2>
 327 <div class="outline-text-2" id="text-6">
 328 <p>
 329 Declare JavaInspect as dependency:
 330 </p>
 331 <div class="org-src-container">
 332
 333 <pre class="src src-xml">&lt;<span style="color: #A6E22E;">dependencies</span>&gt;
 334     ...
 335     &lt;<span style="color: #A6E22E;">dependency</span>&gt;
 336         &lt;<span style="color: #A6E22E;">groupId</span>&gt;eu.svjatoslav&lt;/<span style="color: #A6E22E;">groupId</span>&gt;
 337         &lt;<span style="color: #A6E22E;">artifactId</span>&gt;javainspect&lt;/<span style="color: #A6E22E;">artifactId</span>&gt;
 338         &lt;<span style="color: #A6E22E;">version</span>&gt;1.3&lt;/<span style="color: #A6E22E;">version</span>&gt;
 339     &lt;/<span style="color: #A6E22E;">dependency</span>&gt;
 340     ...
 341 &lt;/<span style="color: #A6E22E;">dependencies</span>&gt;
 342 </pre>
 343 </div>
 344
 345
 346 <p>
 347 Add Maven repository to retrieve artifact from:
 348 </p>
 349 <div class="org-src-container">
 350
 351 <pre class="src src-xml">&lt;<span style="color: #A6E22E;">repositories</span>&gt;
 352     ...
 353     &lt;<span style="color: #A6E22E;">repository</span>&gt;
 354         &lt;<span style="color: #A6E22E;">id</span>&gt;svjatoslav.eu&lt;/<span style="color: #A6E22E;">id</span>&gt;
 355         &lt;<span style="color: #A6E22E;">name</span>&gt;Svjatoslav repository&lt;/<span style="color: #A6E22E;">name</span>&gt;
 356         &lt;<span style="color: #A6E22E;">url</span>&gt;http://www2.svjatoslav.eu/maven/&lt;/<span style="color: #A6E22E;">url</span>&gt;
 357     &lt;/<span style="color: #A6E22E;">repository</span>&gt;
 358     ...
 359 &lt;/<span style="color: #A6E22E;">repositories</span>&gt;
 360 </pre>
 361 </div>
 362 </div>
 363 </div>
 364
 365 <div id="outline-container-sec-7" class="outline-2">
 366 <h2 id="sec-7"><span class="section-number-2">7</span> Requirements</h2>
 367 <div class="outline-text-2" id="text-7">
 368 <p>
 369 <a href="http://www.graphviz.org/">GraphViz</a> - shall be installed on the computer.
 370 </p>
 371
 372 <p>
 373 On Ubuntu/Debian use:
 374 </p>
 375 <pre class="example">
 376 sudo apt-get install graphviz
 377 </pre>
 378 </div>
 379 </div>
 380 <div id="outline-container-sec-8" class="outline-2">
 381 <h2 id="sec-8"><span class="section-number-2">8</span> <span class="todo TODO">TODO</span> </h2>
 382 <div class="outline-text-2" id="text-8">
 383 <ul class="org-ul">
 384 <li>BUG: Should not hide references if there are too many of them to
 385 classes if referring classes are not visible anyway because of
 386 blacklist/whitelist rules. Basically reference counting should
 387 exclude not visible classes.
 388 </li>
 389 <li>BUG: Current code is quite messy (because of lack of time) things
 390 were implemented ad-hoc. Needs cleanup/refactoring for better
 391 readability.
 392 </li>
 393 <li>FEATURE: add dark theme
 394 </li>
 395 <li>FEATURE: sort Class fields by alphabet
 396 </li>
 397 <li>FEATURE: visualize also concrete field values so it could be used as
 398 ultra cool runtime logging framework
 399 </li>
 400 <li>FEATURE: possibility to visualize structure and data from JVM
 401 snapshot
 402 </li>
 403 <li>FEATURE: possibility to attach to remote process to visualize
 404 data/structure using JVM debug port and mechanism.
 405 </li>
 406 <li>FEATURE: possibility to attach to JVM using JVM agent
 407 </li>
 408 <li>FEATURE: possibility to script javainspect behavior
 409 </li>
 410 <li>FEATURE: possibility to select classes/fields/values to be
 411 visualized in SQL like syntax
 412 </li>
 413 <li>FEATURE: configurable maven plugin to generate graphs as part of the
 414 project build/release process
 415 </li>
 416 </ul>
 417 </div>
 418 </div>
 419 </div>
 420 <div id="postamble" class="status">
 421 <p class="author">Author: Svjatoslav Agejenko</p>
 422 <p class="date">Created: 2015-02-03 Tue 20:39</p>
 423 <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>
 424 <p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
 425 </div>
 426 </body>
 427 </html>