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 <!-- 2022-07-13 Wed 04:26 -->
   7 <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
   8 <meta name="viewport" content="width=device-width, initial-scale=1" />
   9 <title>JavaInspect - Utility to visualize java software</title>
  10 <meta name="author" content="Svjatoslav Agejenko" />
  11 <meta name="generator" content="Org Mode" />
  12 <style>
  13   #content { max-width: 60em; margin: auto; }
  14   .title  { text-align: center;
  15              margin-bottom: .2em; }
  16   .subtitle { text-align: center;
  17               font-size: medium;
  18               font-weight: bold;
  19               margin-top:0; }
  20   .todo   { font-family: monospace; color: red; }
  21   .done   { font-family: monospace; color: green; }
  22   .priority { font-family: monospace; color: orange; }
  23   .tag    { background-color: #eee; font-family: monospace;
  24             padding: 2px; font-size: 80%; font-weight: normal; }
  25   .timestamp { color: #bebebe; }
  26   .timestamp-kwd { color: #5f9ea0; }
  27   .org-right  { margin-left: auto; margin-right: 0px;  text-align: right; }
  28   .org-left   { margin-left: 0px;  margin-right: auto; text-align: left; }
  29   .org-center { margin-left: auto; margin-right: auto; text-align: center; }
  30   .underline { text-decoration: underline; }
  31   #postamble p, #preamble p { font-size: 90%; margin: .2em; }
  32   p.verse { margin-left: 3%; }
  33   pre {
  34     border: 1px solid #e6e6e6;
  35     border-radius: 3px;
  36     background-color: #f2f2f2;
  37     padding: 8pt;
  38     font-family: monospace;
  39     overflow: auto;
  40     margin: 1.2em;
  41   }
  42   pre.src {
  43     position: relative;
  44     overflow: auto;
  45   }
  46   pre.src:before {
  47     display: none;
  48     position: absolute;
  49     top: -8px;
  50     right: 12px;
  51     padding: 3px;
  52     color: #555;
  53     background-color: #f2f2f299;
  54   }
  55   pre.src:hover:before { display: inline; margin-top: 14px;}
  56   /* Languages per Org manual */
  57   pre.src-asymptote:before { content: 'Asymptote'; }
  58   pre.src-awk:before { content: 'Awk'; }
  59   pre.src-authinfo::before { content: 'Authinfo'; }
  60   pre.src-C:before { content: 'C'; }
  61   /* pre.src-C++ doesn't work in CSS */
  62   pre.src-clojure:before { content: 'Clojure'; }
  63   pre.src-css:before { content: 'CSS'; }
  64   pre.src-D:before { content: 'D'; }
  65   pre.src-ditaa:before { content: 'ditaa'; }
  66   pre.src-dot:before { content: 'Graphviz'; }
  67   pre.src-calc:before { content: 'Emacs Calc'; }
  68   pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
  69   pre.src-fortran:before { content: 'Fortran'; }
  70   pre.src-gnuplot:before { content: 'gnuplot'; }
  71   pre.src-haskell:before { content: 'Haskell'; }
  72   pre.src-hledger:before { content: 'hledger'; }
  73   pre.src-java:before { content: 'Java'; }
  74   pre.src-js:before { content: 'Javascript'; }
  75   pre.src-latex:before { content: 'LaTeX'; }
  76   pre.src-ledger:before { content: 'Ledger'; }
  77   pre.src-lisp:before { content: 'Lisp'; }
  78   pre.src-lilypond:before { content: 'Lilypond'; }
  79   pre.src-lua:before { content: 'Lua'; }
  80   pre.src-matlab:before { content: 'MATLAB'; }
  81   pre.src-mscgen:before { content: 'Mscgen'; }
  82   pre.src-ocaml:before { content: 'Objective Caml'; }
  83   pre.src-octave:before { content: 'Octave'; }
  84   pre.src-org:before { content: 'Org mode'; }
  85   pre.src-oz:before { content: 'OZ'; }
  86   pre.src-plantuml:before { content: 'Plantuml'; }
  87   pre.src-processing:before { content: 'Processing.js'; }
  88   pre.src-python:before { content: 'Python'; }
  89   pre.src-R:before { content: 'R'; }
  90   pre.src-ruby:before { content: 'Ruby'; }
  91   pre.src-sass:before { content: 'Sass'; }
  92   pre.src-scheme:before { content: 'Scheme'; }
  93   pre.src-screen:before { content: 'Gnu Screen'; }
  94   pre.src-sed:before { content: 'Sed'; }
  95   pre.src-sh:before { content: 'shell'; }
  96   pre.src-sql:before { content: 'SQL'; }
  97   pre.src-sqlite:before { content: 'SQLite'; }
  98   /* additional languages in org.el's org-babel-load-languages alist */
  99   pre.src-forth:before { content: 'Forth'; }
 100   pre.src-io:before { content: 'IO'; }
 101   pre.src-J:before { content: 'J'; }
 102   pre.src-makefile:before { content: 'Makefile'; }
 103   pre.src-maxima:before { content: 'Maxima'; }
 104   pre.src-perl:before { content: 'Perl'; }
 105   pre.src-picolisp:before { content: 'Pico Lisp'; }
 106   pre.src-scala:before { content: 'Scala'; }
 107   pre.src-shell:before { content: 'Shell Script'; }
 108   pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
 109   /* additional language identifiers per "defun org-babel-execute"
 110        in ob-*.el */
 111   pre.src-cpp:before  { content: 'C++'; }
 112   pre.src-abc:before  { content: 'ABC'; }
 113   pre.src-coq:before  { content: 'Coq'; }
 114   pre.src-groovy:before  { content: 'Groovy'; }
 115   /* additional language identifiers from org-babel-shell-names in
 116      ob-shell.el: ob-shell is the only babel language using a lambda to put
 117      the execution function name together. */
 118   pre.src-bash:before  { content: 'bash'; }
 119   pre.src-csh:before  { content: 'csh'; }
 120   pre.src-ash:before  { content: 'ash'; }
 121   pre.src-dash:before  { content: 'dash'; }
 122   pre.src-ksh:before  { content: 'ksh'; }
 123   pre.src-mksh:before  { content: 'mksh'; }
 124   pre.src-posh:before  { content: 'posh'; }
 125   /* Additional Emacs modes also supported by the LaTeX listings package */
 126   pre.src-ada:before { content: 'Ada'; }
 127   pre.src-asm:before { content: 'Assembler'; }
 128   pre.src-caml:before { content: 'Caml'; }
 129   pre.src-delphi:before { content: 'Delphi'; }
 130   pre.src-html:before { content: 'HTML'; }
 131   pre.src-idl:before { content: 'IDL'; }
 132   pre.src-mercury:before { content: 'Mercury'; }
 133   pre.src-metapost:before { content: 'MetaPost'; }
 134   pre.src-modula-2:before { content: 'Modula-2'; }
 135   pre.src-pascal:before { content: 'Pascal'; }
 136   pre.src-ps:before { content: 'PostScript'; }
 137   pre.src-prolog:before { content: 'Prolog'; }
 138   pre.src-simula:before { content: 'Simula'; }
 139   pre.src-tcl:before { content: 'tcl'; }
 140   pre.src-tex:before { content: 'TeX'; }
 141   pre.src-plain-tex:before { content: 'Plain TeX'; }
 142   pre.src-verilog:before { content: 'Verilog'; }
 143   pre.src-vhdl:before { content: 'VHDL'; }
 144   pre.src-xml:before { content: 'XML'; }
 145   pre.src-nxml:before { content: 'XML'; }
 146   /* add a generic configuration mode; LaTeX export needs an additional
 147      (add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
 148   pre.src-conf:before { content: 'Configuration File'; }
 149
 150   table { border-collapse:collapse; }
 151   caption.t-above { caption-side: top; }
 152   caption.t-bottom { caption-side: bottom; }
 153   td, th { vertical-align:top;  }
 154   th.org-right  { text-align: center;  }
 155   th.org-left   { text-align: center;   }
 156   th.org-center { text-align: center; }
 157   td.org-right  { text-align: right;  }
 158   td.org-left   { text-align: left;   }
 159   td.org-center { text-align: center; }
 160   dt { font-weight: bold; }
 161   .footpara { display: inline; }
 162   .footdef  { margin-bottom: 1em; }
 163   .figure { padding: 1em; }
 164   .figure p { text-align: center; }
 165   .equation-container {
 166     display: table;
 167     text-align: center;
 168     width: 100%;
 169   }
 170   .equation {
 171     vertical-align: middle;
 172   }
 173   .equation-label {
 174     display: table-cell;
 175     text-align: right;
 176     vertical-align: middle;
 177   }
 178   .inlinetask {
 179     padding: 10px;
 180     border: 2px solid gray;
 181     margin: 10px;
 182     background: #ffffcc;
 183   }
 184   #org-div-home-and-up
 185    { text-align: right; font-size: 70%; white-space: nowrap; }
 186   textarea { overflow-x: auto; }
 187   .linenr { font-size: smaller }
 188   .code-highlighted { background-color: #ffff00; }
 189   .org-info-js_info-navigation { border-style: none; }
 190   #org-info-js_console-label
 191     { font-size: 10px; font-weight: bold; white-space: nowrap; }
 192   .org-info-js_search-highlight
 193     { background-color: #ffff00; color: #000000; font-weight: bold; }
 194   .org-svg { }
 195 </style>
 196 <link href="https://bootswatch.com/3/darkly/bootstrap.min.css" rel="stylesheet">
 197 <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
 198 <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.5/js/bootstrap.min.js"></script>
 199 <style type="text/css">
 200 footer {background-color: #111 !important;}
 201 pre {background-color: #111; color: #ccc;}
 202 </style>
 203 <link rel="stylesheet" type="text/css" href="https://thomasf.github.io/solarized-css/solarized-dark.min.css" />
 204 </head>
 205 <body>
 206 <div id="content" class="content">
 207 <h1 class="title">JavaInspect - Utility to visualize java software</h1>
 208 <div id="table-of-contents" role="doc-toc">
 209 <h2>Table of Contents</h2>
 210 <div id="text-table-of-contents" role="doc-toc">
 211 <ul>
 212 <li><a href="#org6c08335">1. General</a>
 213 <ul>
 214 <li><a href="#org1f40be1">1.1. Source code</a></li>
 215 </ul>
 216 </li>
 217 <li><a href="#org05e5b28">2. Goal and operating principle</a></li>
 218 <li><a href="#org3ca1849">3. Example graphs</a></li>
 219 <li><a href="#orga20e9d8">4. Installation</a></li>
 220 <li><a href="#orgf9f5b99">5. Usage</a>
 221 <ul>
 222 <li><a href="#org952985c">5.1. Usage as commandline utility</a>
 223 <ul>
 224 <li><a href="#org78673fb">5.1.1. Available commandline arguments</a></li>
 225 <li><a href="#orgbf7fb2b">5.1.2. Specifying classes to render</a></li>
 226 </ul>
 227 </li>
 228 <li><a href="#orgc792989">5.2. Usage via Java API</a>
 229 <ul>
 230 <li><a href="#org68fe457">5.2.1. Example 1: individually picked objects</a></li>
 231 <li><a href="#orge4c6237">5.2.2. Example 2: GraphViz embedded in another project</a></li>
 232 <li><a href="#org851b3a6">5.2.3. Embedding JavaInspect in your Maven project</a></li>
 233 </ul>
 234 </li>
 235 </ul>
 236 </li>
 237 <li><a href="#orgdb7d308">6. TO DO</a></li>
 238 <li><a href="#org30b046f">7. See also</a></li>
 239 </ul>
 240 </div>
 241 </div>
 242
 243 <div id="outline-container-org6c08335" class="outline-2">
 244 <h2 id="org6c08335"><span class="section-number-2">1.</span> General</h2>
 245 <div class="outline-text-2" id="text-1">
 246 <ul class="org-ul">
 247 <li>This program is free software: you can redistribute it and/or modify
 248 it under the terms of the <a href="https://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public License</a> as
 249 published by the Free Software Foundation, either version 3 of the
 250 License, or (at your option) any later version.</li>
 251
 252 <li>Program authors:
 253 <ul class="org-ul">
 254 <li>Svjatoslav Agejenko
 255 <ul class="org-ul">
 256 <li>Homepage: <a href="https://svjatoslav.eu">https://svjatoslav.eu</a></li>
 257 <li>Email: <a href="mailto://svjatoslav@svjatoslav.eu">mailto://svjatoslav@svjatoslav.eu</a></li>
 258 <li><a href="https://www.svjatoslav.eu/projects/">Other software projects hosted at svjatoslav.eu</a></li>
 259 </ul></li>
 260
 261 <li>Tony Bargnesi
 262 <ul class="org-ul">
 263 <li>GitHub fork for the project:
 264 <a href="https://github.com/abargnesi/javainspect">https://github.com/abargnesi/javainspect</a></li>
 265 </ul></li>
 266 </ul></li>
 267 </ul>
 268 </div>
 269
 270 <div id="outline-container-org1f40be1" class="outline-3">
 271 <h3 id="org1f40be1"><span class="section-number-3">1.1.</span> Source code</h3>
 272 <div class="outline-text-3" id="text-1-1">
 273 <ul class="org-ul">
 274 <li><a href="https://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz">Download latest snapshot in TAR GZ format</a></li>
 275
 276 <li><a href="https://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=summary">Browse Git repository online</a></li>
 277
 278 <li><p>
 279 Clone Git repository using command:
 280 </p>
 281 <pre class="example">
 282 git clone https://www2.svjatoslav.eu/git/javainspect.git
 283 </pre></li>
 284 </ul>
 285 </div>
 286 </div>
 287 </div>
 288
 289 <div id="outline-container-org05e5b28" class="outline-2">
 290 <h2 id="org05e5b28"><span class="section-number-2">2.</span> Goal and operating principle</h2>
 291 <div class="outline-text-2" id="text-2">
 292 <p>
 293 Goal: simplify/speed up understanding the computer program code by
 294 automatically visualizing its structure.
 295 </p>
 296
 297 <p>
 298 <a href="https://www3.svjatoslav.eu/projects/sixth-3d/graphs/">See example produced graphs</a> for <a href="https://www3.svjatoslav.eu/projects/sixth-3d/">Sixth 3D - 3D engine project</a>.
 299 </p>
 300
 301 <p>
 302 JavaInspect can be used as a <a href="#org952985c">standalone commandline utility</a> as well as
 303 <a href="#orgc792989">java library</a>. JavaInspect uses primarily Java built-in reflection to
 304 discover and visualize any part of Java program.
 305 </p>
 306
 307 <p>
 308 JavaInspect currently has no graphical user interface, configuration
 309 files, embedded scripting support, direct Maven, Gradle or Ant
 310 integration. See <a href="#orgf9f5b99">usage</a> to learn how to instuct Javainspect what to do.
 311 </p>
 312
 313 <p>
 314 After discovering application structure and optionally filtering out
 315 unimportant parts, JavaInspect produces GraphViz dot file that
 316 describes data to be visualized. Then launches <a href="https://graphviz.org/">GraphViz</a> to generate
 317 bitmap graph in PNG or SVG format.
 318 </p>
 319
 320 <p>
 321 Notes:
 322 </p>
 323 <ul class="org-ul">
 324 <li>JavaInspect is developed and tested so far only on GNU/Linux.</li>
 325 </ul>
 326 </div>
 327 </div>
 328
 329 <div id="outline-container-org3ca1849" class="outline-2">
 330 <h2 id="org3ca1849"><span class="section-number-2">3.</span> Example graphs</h2>
 331 <div class="outline-text-2" id="text-3">
 332 <ul class="org-ul">
 333 <li><p>
 334 A very simple example:
 335 </p>
 336
 337
 338 <div id="orgb13f634" class="figure">
 339 <p><a href="example.png"><img src="example-thumbnail.png" alt="example-thumbnail.png" /></a>
 340 </p>
 341 </div>
 342
 343 <p>
 344 Graph legend:
 345 </p>
 346
 347
 348 <div id="orgdad6849" class="figure">
 349 <p><img src="legend.png" alt="legend.png" />
 350 </p>
 351 </div></li>
 352 </ul>
 353
 354
 355 <ul class="org-ul">
 356 <li><a href="https://www3.svjatoslav.eu/projects/sixth-3d/graphs/">See example produced graphs</a> for <a href="https://www3.svjatoslav.eu/projects/sixth-3d/">Sixth 3D - 3D engine project</a>.</li>
 357 </ul>
 358 </div>
 359 </div>
 360
 361 <div id="outline-container-orga20e9d8" class="outline-2">
 362 <h2 id="orga20e9d8"><span class="section-number-2">4.</span> Installation</h2>
 363 <div class="outline-text-2" id="text-4">
 364 <p>
 365 <a href="http://www.graphviz.org/">GraphViz</a> - shall be installed on the computer.
 366 </p>
 367
 368 <p>
 369 On Ubuntu/Debian GraphViz can be installed using:
 370 </p>
 371 <div class="org-src-container">
 372 <pre class="src src-sh">sudo apt-get install graphviz
 373 </pre>
 374 </div>
 375
 376 <p>
 377 To use JavaInspect via Java API, no further installation is
 378 needed. JavaInspect will be embedded into your project as dependency.
 379 This is described in <a href="#orgc792989">usage via Java API</a>. It will expect GraphViz to be
 380 available in the system.
 381 </p>
 382
 383 <p>
 384 To use JavaInspect as a commandline tool, JavaInspect source
 385 repository has to be cloned locally: See <a href="#org1f40be1">Source code</a>.
 386 </p>
 387
 388 <p>
 389 Then study and execute installation script:
 390 </p>
 391 <pre class="example">
 392 commandline launcher/install
 393 </pre>
 394
 395
 396 <p>
 397 After installation, new commandline tool should be available
 398 </p>
 399 <pre class="example">
 400 javainspect
 401 </pre>
 402
 403
 404 <p>
 405 Quick commandline usage help can be viewed by issuing
 406 </p>
 407 <pre class="example">
 408 javainspect --help
 409 </pre>
 410 </div>
 411 </div>
 412
 413 <div id="outline-container-orgf9f5b99" class="outline-2">
 414 <h2 id="orgf9f5b99"><span class="section-number-2">5.</span> Usage</h2>
 415 <div class="outline-text-2" id="text-5">
 416 <p>
 417 JavaInspect can be controlled in 2 different ways:
 418 </p>
 419 <ul class="org-ul">
 420 <li><a href="#org952985c">as standalone commandline utility</a></li>
 421 <li><a href="#orgc792989">as embedded Java library via Java API</a></li>
 422 </ul>
 423 </div>
 424
 425 <div id="outline-container-org952985c" class="outline-3">
 426 <h3 id="org952985c"><span class="section-number-3">5.1.</span> Usage as commandline utility</h3>
 427 <div class="outline-text-3" id="text-5-1">
 428 </div>
 429 <div id="outline-container-org78673fb" class="outline-4">
 430 <h4 id="org78673fb"><span class="section-number-4">5.1.1.</span> Available commandline arguments</h4>
 431 <div class="outline-text-4" id="text-5-1-1">
 432 <p class="verse">
 433 -j (existing files)&#x2026;<br />
 434 &#xa0;&#xa0;&#xa0;&#xa0;JAR file(s) to render.<br />
 435 <br />
 436 -c (existing directories)&#x2026;<br />
 437 &#xa0;&#xa0;&#xa0;&#xa0;Classpath directories<br />
 438 <br />
 439 -n (string)<br />
 440 &#xa0;&#xa0;&#xa0;&#xa0;Graph name. (default: "graph")<br />
 441 <br />
 442 &#x2013;debug<br />
 443 &#xa0;&#xa0;&#xa0;&#xa0;Show debug info.<br />
 444 <br />
 445 -h, &#x2013;help<br />
 446 &#xa0;&#xa0;&#xa0;&#xa0;Show commandline usage help.<br />
 447 <br />
 448 -k<br />
 449 &#xa0;&#xa0;&#xa0;&#xa0;Keep dot file.<br />
 450 <br />
 451 -ho<br />
 452 &#xa0;&#xa0;&#xa0;&#xa0;Hide orphaned classes.<br />
 453 <br />
 454 -w (one to many strings)&#x2026;<br />
 455 &#xa0;&#xa0;&#xa0;&#xa0;Whitelist glob(s).<br />
 456 <br />
 457 -b (one to many strings)&#x2026;<br />
 458 &#xa0;&#xa0;&#xa0;&#xa0;Blacklist glob(s).<br />
 459 <br />
 460 -r (one to many strings)&#x2026;<br />
 461 &#xa0;&#xa0;&#xa0;&#xa0;root class(es).<br />
 462 <br />
 463 -d (existing directory)<br />
 464 &#xa0;&#xa0;&#xa0;&#xa0;Target directory. Default is current directory.<br />
 465 <br />
 466 -t (options: png, svg)<br />
 467 &#xa0;&#xa0;&#xa0;&#xa0;Target image type. Default is: svg.<br />
 468 </p>
 469 </div>
 470 </div>
 471 <div id="outline-container-orgbf7fb2b" class="outline-4">
 472 <h4 id="orgbf7fb2b"><span class="section-number-4">5.1.2.</span> Specifying classes to render</h4>
 473 <div class="outline-text-4" id="text-5-1-2">
 474 <p>
 475 Normal Java application has immense complexity. In addition to code
 476 that was directly written by particular project developers, lots of
 477 functionality is typically added as frameworks or libraries to the
 478 project. In addition there is significant Java standard library.
 479 </p>
 480
 481 <p>
 482 Because JavaInspect uses reflection, it does not easily distinguish
 483 between those. In normal situation you would rather want to visualize
 484 only code that was developed specifically for your project and leave
 485 frameworks like Spring etc. out. If you visualize all classes that are
 486 possibly reachable from you project, you will easily get huge and
 487 incomprehensible graph.
 488 </p>
 489
 490 <p>
 491 JavaInspect can digest compiled Java classes in 2 modes:
 492 </p>
 493 <ol class="org-ol">
 494 <li>Provide list of Jar files. Use <b>-j</b> option.</li>
 495 <li>Provide list of filesystem directories that can be used as
 496 classpath root. Use <b>-c</b> option.</li>
 497 </ol>
 498
 499 <p>
 500 Currently JavaInspect uses following algorithm to add classes to
 501 rendered graph:
 502 </p>
 503
 504 <ul class="org-ul">
 505 <li>All classes that were found in Jar files are added to graph by default.</li>
 506 <li>None of the classes that were found in filesystem directories are
 507 added to the graph by default (unless explicitly referenced). (TODO:
 508 for consistency it would be better to add them too by default)</li>
 509 <li>If whitelist is specified (<b>-w</b> option) everything that is not
 510 matched by whitelist pattern(s) will be removed from the graph.</li>
 511 <li>If blacklist is specified (<b>-b</b> option) everything that is matched
 512 by blacklist pattern(s) will be removed from the graph.</li>
 513 <li>Root classes can be specified using <b>-r</b> option. Root classes will
 514 be added to the graph. JavaInspect will then try to recursively
 515 discover all classes that were referenced by root class and add
 516 those also to the graph.</li>
 517 </ul>
 518 </div>
 519 </div>
 520 </div>
 521
 522 <div id="outline-container-orgc792989" class="outline-3">
 523 <h3 id="orgc792989"><span class="section-number-3">5.2.</span> Usage via Java API</h3>
 524 <div class="outline-text-3" id="text-5-2">
 525 <p>
 526 Requires that classes to be visualised are available in the classpath.
 527 </p>
 528
 529 <p>
 530 To get JavaInspect into same classpath with your projecs I so far came
 531 up with 2 solutions:
 532 </p>
 533
 534 <ol class="org-ol">
 535 <li>Add JavaInspect library in your project as a dependency.</li>
 536
 537 <li>Create new Java project for the purpose visualizing your other
 538 projects and include JavaInspect and your projecs binary artifacts
 539 (Jar's) into new project classpath. Built binary Jar's (with no
 540 source code) are sufficient because JavaInspect operates via
 541 reflection.</li>
 542 </ol>
 543
 544 <p>
 545 Simple Java based control/configuration code needs to be written for
 546 each project. I usually put such code into directories devoted for
 547 JUnit tests. Because it needs not to be compiled/embedded into final
 548 product or project artifact I'm just willing to visualize.
 549 </p>
 550
 551 <p>
 552 Control code in general does the following:
 553 </p>
 554 <ol class="org-ol">
 555 <li>Create graph object.</li>
 556 <li>Java reflection/classloaders does not provide mechanism for
 557 discovering all classes under given package. Therefore you need to
 558 declare at least some classes to be added to the graph by manually
 559 adding individual classes to the graph. For every class added to
 560 the graph, GraphViz will recursively inspect it and add all
 561 referecned classes to the graph as well.</li>
 562 <li>Graphs easilly get very big and complex so optionally we filter
 563 important code using classname <a href="https://en.wikipedia.org/wiki/Glob_(programming)">glob</a> patterns based blacklist and/or
 564 whitelist.</li>
 565 <li>Optionally we can tune some rendering parameters like:
 566 <ul class="org-ul">
 567 <li>Possibility to remove orphaned classes (classes with no
 568 references) from the graph.</li>
 569 <li>Specify target directory for generated visualization
 570 files. (Default is current directory)</li>
 571 <li>Keep intermediate GraphViz dot file for later inspection.</li>
 572 </ul></li>
 573 <li>Render graph.</li>
 574 </ol>
 575 </div>
 576
 577
 578 <div id="outline-container-org68fe457" class="outline-4">
 579 <h4 id="org68fe457"><span class="section-number-4">5.2.1.</span> Example 1: individually picked objects</h4>
 580 <div class="outline-text-4" id="text-5-2-1">
 581 <p>
 582 This example demonstrates generating of class graph from hand picked
 583 classes and visualizing GraphViz itself.
 584 </p>
 585
 586 <div class="org-src-container">
 587 <pre class="src src-java">
 588 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Create graph</span>
 589 <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>();
 590
 591 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Add some random object to the graph. GraphViz will detect Class from</span>
 592 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">the object.</span>
 593 graph.add(graph);
 594
 595 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Also add some random class to the graph.</span>
 596 graph.add(Utils.<span style="color: #F92672;">class</span>);
 597
 598 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Keep intermediary GraphViz DOT file for reference.</span>
 599 graph.setKeepDotFile(<span style="color: #FF80F4;">true</span>);
 600
 601 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Produce bitmap image titled "JavaInspect.png" to the user Desktop</span>
 602 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">directory</span>
 603 graph.generateGraph(<span style="color: #EEDC82;">"JavaInspect"</span>);
 604
 605 </pre>
 606 </div>
 607
 608 <p>
 609 Note: if desired, more compact version of the above:
 610 </p>
 611 <div class="org-src-container">
 612 <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>)
 613                 .setKeepDotFile(<span style="color: #FF80F4;">true</span>).generateGraph(<span style="color: #EEDC82;">"JavaInspect"</span>);
 614 </pre>
 615 </div>
 616
 617
 618 <p>
 619 Result:
 620 </p>
 621 <ul class="org-ul">
 622 <li>Generated DOT file: <a href="JavaInspect.dot">JavaInspect.dot</a></li>
 623 <li>Generated PNG image: <a href="JavaInspect.png">JavaInspect.png</a></li>
 624 </ul>
 625 </div>
 626 </div>
 627
 628 <div id="outline-container-orge4c6237" class="outline-4">
 629 <h4 id="orge4c6237"><span class="section-number-4">5.2.2.</span> Example 2: GraphViz embedded in another project</h4>
 630 <div class="outline-text-4" id="text-5-2-2">
 631 <ol class="org-ol">
 632 <li>Download project Sixth <a href="https://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz">code snapshot</a>.</li>
 633 <li>Inspect and run <b>DataGraph.java</b>.</li>
 634 </ol>
 635 </div>
 636 </div>
 637
 638 <div id="outline-container-org851b3a6" class="outline-4">
 639 <h4 id="org851b3a6"><span class="section-number-4">5.2.3.</span> Embedding JavaInspect in your Maven project</h4>
 640 <div class="outline-text-4" id="text-5-2-3">
 641 <p>
 642 Declare JavaInspect as dependency:
 643 </p>
 644 <div class="org-src-container">
 645 <pre class="src src-xml">&lt;<span style="color: #A6E22E;">dependencies</span>&gt;
 646     ...
 647     &lt;<span style="color: #A6E22E;">dependency</span>&gt;
 648         &lt;<span style="color: #A6E22E;">groupId</span>&gt;eu.svjatoslav&lt;/<span style="color: #A6E22E;">groupId</span>&gt;
 649         &lt;<span style="color: #A6E22E;">artifactId</span>&gt;javainspect&lt;/<span style="color: #A6E22E;">artifactId</span>&gt;
 650         &lt;<span style="color: #A6E22E;">version</span>&gt;1.7&lt;/<span style="color: #A6E22E;">version</span>&gt;
 651     &lt;/<span style="color: #A6E22E;">dependency</span>&gt;
 652     ...
 653 &lt;/<span style="color: #A6E22E;">dependencies</span>&gt;
 654 </pre>
 655 </div>
 656
 657
 658 <p>
 659 Add Maven repository to retrieve artifact from:
 660 </p>
 661 <div class="org-src-container">
 662 <pre class="src src-xml">&lt;<span style="color: #A6E22E;">repositories</span>&gt;
 663     ...
 664     &lt;<span style="color: #A6E22E;">repository</span>&gt;
 665         &lt;<span style="color: #A6E22E;">id</span>&gt;svjatoslav.eu&lt;/<span style="color: #A6E22E;">id</span>&gt;
 666         &lt;<span style="color: #A6E22E;">name</span>&gt;Svjatoslav repository&lt;/<span style="color: #A6E22E;">name</span>&gt;
 667         &lt;<span style="color: #A6E22E;">url</span>&gt;http://www3.svjatoslav.eu/maven/&lt;/<span style="color: #A6E22E;">url</span>&gt;
 668     &lt;/<span style="color: #A6E22E;">repository</span>&gt;
 669     ...
 670 &lt;/<span style="color: #A6E22E;">repositories</span>&gt;
 671 </pre>
 672 </div>
 673 </div>
 674 </div>
 675 </div>
 676 </div>
 677
 678 <div id="outline-container-orgdb7d308" class="outline-2">
 679 <h2 id="orgdb7d308"><span class="section-number-2">6.</span> TO DO</h2>
 680 <div class="outline-text-2" id="text-6">
 681 <p>
 682 Note: Because this is side project (and I have many of them) I can
 683 only contribute few hours per year at average. Any help is welcome.  A
 684 LOT of cool ideas could be implemented. For intstance:
 685 </p>
 686
 687 <ul class="org-ul">
 688 <li>BUG: Should not hide references if there are too many of them to
 689 classes if referring classes are not visible anyway because of
 690 blacklist/whitelist rules. Basically reference counting should
 691 exclude not visible classes.</li>
 692
 693 <li>BUG: Orphaned class removal does not work always. There are many
 694 bugs and corner cases to find and fix still.</li>
 695
 696 <li>BUG: Code is not very readable. Document and refactor for better
 697 maintainability.</li>
 698
 699 <li>FEATURE: Create installable DEB package.
 700 <ul class="org-ul">
 701 <li>Submit it to some Debian developer for integration or become
 702 Debian package maintainer.</li>
 703 </ul></li>
 704
 705 <li>FEATURE: Make it modular. That is: central part, an application
 706 model could be standalone and serializable.
 707
 708 <ul class="org-ul">
 709 <li>There could be multiple ways to acquire model:
 710 <ul class="org-ul">
 711 <li>By introspecting application via Java reflections (current mode
 712 of operation).</li>
 713 <li>By parsing java source. (unfinished)</li>
 714 </ul></li>
 715
 716 <li>There could be ways to manipulate model:
 717 <ul class="org-ul">
 718 <li>Store/load/compare.</li>
 719 <li>Trim uninteresting parts.</li>
 720 <li>Highlight important parts.</li>
 721 </ul></li>
 722
 723 <li>There could be multiple ways to render model:
 724 <ul class="org-ul">
 725 <li>PNG/SVG (currently implemented)</li>
 726 <li>PlantUML (TODO)</li>
 727 <li>Interactive 3D visualization (TODO)</li>
 728 </ul></li>
 729 </ul></li>
 730
 731 <li>FEATURE: Implement (or integrate existing java parser
 732 <a href="https://javaparser.org/">https://javaparser.org/</a>) to be able to produce code visualizations
 733 based on source code (in addition to current reflection based
 734 approach).</li>
 735
 736 <li>FEATURE: Integarte with <a href="http://plantuml.com/class-diagram">PlantUML</a>.</li>
 737
 738 <li>FEATURE: Add dark theme for generated graphs.</li>
 739
 740 <li>FEATURE: Sort Class fields by alphabet.</li>
 741
 742 <li>FEATURE: Visualize also concrete field values so it could be used as
 743 ultra cool runtime logging/debugging framework.</li>
 744
 745 <li>FEATURE: Possibility to visualize structure and data from JVM
 746 snapshot.</li>
 747
 748 <li>FEATURE: Possibility to attach to remote process to visualize
 749 data/structure using JVM debug port and mechanism.</li>
 750
 751 <li>FEATURE: Possibility to attach to JVM using JVM agent.</li>
 752
 753 <li>FEATURE: Possibility to inspect graphs in 3D using <a href="https://www3.svjatoslav.eu/projects/sixth-3d/">Sixth 3D engine</a>.</li>
 754
 755 <li>FEATURE: Possibility to select classes/fields/values to be
 756 visualized in some graph query language. For greater flexibility in
 757 comparison to currently supported glob syntax.</li>
 758
 759 <li>FEATURE: Add option to control JavaInspect via JSON or XML config
 760 file. For example different graphs for given project could be
 761 defined once in plain text config, possibly with the aid of some
 762 interactive utility. Then defined graphs could be updated as part of
 763 project build or release process.</li>
 764
 765 <li>FEATURE: Configurable maven plugin to generate graphs as part of the
 766 project build/release process.</li>
 767 </ul>
 768 </div>
 769 </div>
 770 <div id="outline-container-org30b046f" class="outline-2">
 771 <h2 id="org30b046f"><span class="section-number-2">7.</span> See also</h2>
 772 <div class="outline-text-2" id="text-7">
 773 <p>
 774 Similar or alternative solutions:
 775 </p>
 776 <ul class="org-ul">
 777 <li><a href="http://www.class-visualizer.net/">http://www.class-visualizer.net/</a></li>
 778 <li><a href="https://github.com/pahen/madge">Madge - similar tool for JavaScript</a></li>
 779 </ul>
 780 </div>
 781 </div>
 782 </div>
 783 <div id="postamble" class="status">
 784 <p class="author">Author: Svjatoslav Agejenko</p>
 785 <p class="date">Created: 2022-07-13 Wed 04:26</p>
 786 <p class="validation"><a href="https://validator.w3.org/check?uri=referer">Validate</a></p>
 787 </div>
 788 </body>
 789 </html>