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-02 Mon 19:49 -->
   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 </ul>
 154 </div>
 155 </div>
 156 <hr  />
 157
 158 <ul class="org-ul">
 159 <li><a href="http://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz">download</a>
 160 </li>
 161 <li><a href="http://svjatoslav.eu/programs.jsp">other applications hosted at svjatoslav.eu</a>
 162 </li>
 163 <li>Program author:
 164 <ul class="org-ul">
 165 <li>Svjatoslav Agejenko
 166 </li>
 167 <li>Homepage: <a href="http://svjatoslav.eu">http://svjatoslav.eu</a>
 168 </li>
 169 <li>Email: <a href="mailto://svjatoslav@svjatoslav.eu">mailto://svjatoslav@svjatoslav.eu</a>
 170 </li>
 171 </ul>
 172 </li>
 173 </ul>
 174
 175 <div id="outline-container-sec-1" class="outline-2">
 176 <h2 id="sec-1"><span class="section-number-2">1</span> General</h2>
 177 <div class="outline-text-2" id="text-1">
 178 <p>
 179 Goal: simplify/speed up understanding the computer program code by
 180 automatically visualizing its structure.
 181 </p>
 182
 183 <p>
 184 JavaInspect is a Java library that you can embed into your Java
 185 project with a few lines of Maven configuration and then visualize any
 186 part of your Java program structure with few simple JavaInspect API
 187 calls at application runtime.
 188 </p>
 189
 190 <p>
 191 JavaInspect uses Java reflection to discover class relations and
 192 structure and produces GraphViz dot file that describes your
 193 application. Then launches GraphViz to generate bitmap graph in PNG
 194 format on your Desktop directory.
 195 </p>
 196 </div>
 197 </div>
 198
 199 <div id="outline-container-sec-2" class="outline-2">
 200 <h2 id="sec-2"><span class="section-number-2">2</span> Current status</h2>
 201 <div class="outline-text-2" id="text-2">
 202 <p>
 203 This is simple utility, quickly written. Tested on GNU Linux (can be
 204 relatively simply ported to other operating systems too). So far I
 205 used it for my own needs. There might be bugs and missing
 206 features. Feedback and code contributions are welcome.
 207 </p>
 208 </div>
 209 </div>
 210
 211 <div id="outline-container-sec-3" class="outline-2">
 212 <h2 id="sec-3"><span class="section-number-2">3</span> Example graphs</h2>
 213 <div class="outline-text-2" id="text-3">
 214 <p>
 215 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>.
 216 </p>
 217
 218 <p>
 219 A very simple example:
 220 </p>
 221
 222
 223 <div class="figure">
 224 <p><a href="example.png"><img src="example.resized.png" alt="example.resized.png" /></a>
 225 </p>
 226 </div>
 227
 228
 229 <p>
 230 Graph legend:
 231 </p>
 232
 233
 234 <div class="figure">
 235 <p><img src="legend.png" alt="legend.png" />
 236 </p>
 237 </div>
 238 </div>
 239 </div>
 240
 241 <div id="outline-container-sec-4" class="outline-2">
 242 <h2 id="sec-4"><span class="section-number-2">4</span> Usage example 1</h2>
 243 <div class="outline-text-2" id="text-4">
 244 <p>
 245 This example demonstrates generating of class graph from hand picked
 246 classes.
 247 </p>
 248
 249 <div class="org-src-container">
 250
 251 <pre class="src src-java"><span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Create graph</span>
 252 <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>();
 253
 254 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">While classes and objects can be immediately passed to ClassGraph</span>
 255 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">constructor as arguments, it is also possible to add them one by</span>
 256 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">one as in the following example.</span>
 257
 258 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Add some object to the graph.</span>
 259 graph.addObject(graph);
 260
 261 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Add some class to the graph.</span>
 262 graph.addClass(Utils.<span style="color: #F92672;">class</span>);
 263
 264 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Produce bitmap image titled "JavaInspect.png" to the user Desktop</span>
 265 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">directory and keep intermediary GraphViz DOT file for reference.</span>
 266 graph.generateGraph(<span style="color: #EEDC82;">"JavaInspect"</span>, <span style="color: #FF80F4;">true</span>);
 267 </pre>
 268 </div>
 269
 270
 271
 272 <p>
 273 Result:
 274 </p>
 275 <ul class="org-ul">
 276 <li>Generated DOT file: <a href="JavaInspect.dot">JavaInspect.dot</a>
 277 </li>
 278 <li>Generated PNG image: <a href="JavaInspect.png">JavaInspect.png</a>
 279 </li>
 280 </ul>
 281 </div>
 282 </div>
 283
 284 <div id="outline-container-sec-5" class="outline-2">
 285 <h2 id="sec-5"><span class="section-number-2">5</span> Usage example 2</h2>
 286 <div class="outline-text-2" id="text-5">
 287 <p>
 288 Recursively scan current directory for Java source code and attempt to
 289 detect class names from there to be added to the graph.
 290 </p>
 291
 292 <div class="org-src-container">
 293
 294 <pre class="src src-java">graph.addProject(<span style="color: #EEDC82;">"."</span>);
 295
 296 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Blacklist example classes from being shown on the graph</span>
 297 graph.getFilter().blacklistClassPattern(
 298     <span style="color: #EEDC82;">"eu.svjatoslav.inspector.java.structure.example.*"</span>);
 299
 300 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">do not show single classes with no relationships on the graph</span>
 301 graph.hideOrphanedClasses();
 302
 303 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Produce bitmap image titled "JavaInspect full project.png" to the</span>
 304 <span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">user Desktop directory.</span>
 305 graph.generateGraph(<span style="color: #EEDC82;">"JavaInspect full project"</span>);
 306 </pre>
 307 </div>
 308 <p>
 309 Result:
 310 </p>
 311 <ul class="org-ul">
 312 <li>Generated PNG image: <a href="JavaInspect%20full%20project.png">JavaInspect full project.png</a>
 313 </li>
 314 </ul>
 315 </div>
 316 </div>
 317
 318 <div id="outline-container-sec-6" class="outline-2">
 319 <h2 id="sec-6"><span class="section-number-2">6</span> Embedding JavaInspect in your Maven project</h2>
 320 <div class="outline-text-2" id="text-6">
 321 <p>
 322 Declare JavaInspect as dependency:
 323 </p>
 324 <div class="org-src-container">
 325
 326 <pre class="src src-xml">&lt;<span style="color: #A6E22E;">dependencies</span>&gt;
 327     ...
 328     &lt;<span style="color: #A6E22E;">dependency</span>&gt;
 329         &lt;<span style="color: #A6E22E;">groupId</span>&gt;eu.svjatoslav&lt;/<span style="color: #A6E22E;">groupId</span>&gt;
 330         &lt;<span style="color: #A6E22E;">artifactId</span>&gt;javainspect&lt;/<span style="color: #A6E22E;">artifactId</span>&gt;
 331         &lt;<span style="color: #A6E22E;">version</span>&gt;1.3&lt;/<span style="color: #A6E22E;">version</span>&gt;
 332     &lt;/<span style="color: #A6E22E;">dependency</span>&gt;
 333     ...
 334 &lt;/<span style="color: #A6E22E;">dependencies</span>&gt;
 335 </pre>
 336 </div>
 337
 338
 339 <p>
 340 Add Maven repository to retrieve artifact from:
 341 </p>
 342 <div class="org-src-container">
 343
 344 <pre class="src src-xml">&lt;<span style="color: #A6E22E;">repositories</span>&gt;
 345     ...
 346     &lt;<span style="color: #A6E22E;">repository</span>&gt;
 347         &lt;<span style="color: #A6E22E;">id</span>&gt;svjatoslav.eu&lt;/<span style="color: #A6E22E;">id</span>&gt;
 348         &lt;<span style="color: #A6E22E;">name</span>&gt;Svjatoslav repository&lt;/<span style="color: #A6E22E;">name</span>&gt;
 349         &lt;<span style="color: #A6E22E;">url</span>&gt;http://www2.svjatoslav.eu/maven/&lt;/<span style="color: #A6E22E;">url</span>&gt;
 350     &lt;/<span style="color: #A6E22E;">repository</span>&gt;
 351     ...
 352 &lt;/<span style="color: #A6E22E;">repositories</span>&gt;
 353 </pre>
 354 </div>
 355 </div>
 356 </div>
 357
 358 <div id="outline-container-sec-7" class="outline-2">
 359 <h2 id="sec-7"><span class="section-number-2">7</span> Requirements</h2>
 360 <div class="outline-text-2" id="text-7">
 361 <p>
 362 <a href="http://www.graphviz.org/">GraphViz</a> - shall be installed on the computer.
 363 </p>
 364
 365 <p>
 366 On Ubuntu/Debian use:
 367 </p>
 368 <pre class="example">
 369 sudo apt-get install graphviz
 370 </pre>
 371 </div>
 372 </div>
 373 </div>
 374 <div id="postamble" class="status">
 375 <p class="author">Author: Svjatoslav Agejenko</p>
 376 <p class="date">Created: 2015-02-02 Mon 19:49</p>
 377 <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>
 378 <p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
 379 </div>
 380 </body>
 381 </html>