updated project documentation
authorSvjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Sat, 9 Jan 2021 22:38:45 +0000 (00:38 +0200)
committerSvjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Sat, 9 Jan 2021 22:38:45 +0000 (00:38 +0200)
doc/index.html
doc/index.org
usage examples/demo project/.gitignore

index 9bbe3f6..0a0c3ca 100644 (file)
@@ -2,7 +2,7 @@
 <html lang="en">
 <head>
 <title>JavaInspect - Utility to visualize java software</title>
-<!-- 2019-01-19 Sat 00:47 -->
+<!-- 2021-01-10 P 00:37 -->
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="generator" content="Org-mode">
@@ -280,16 +280,10 @@ how to instuct Javainspect what to do.
 <p>
 After discovering application structure and optionally filtering out
 unimportant parts, JavaInspect produces GraphViz dot file that
-describes data to be visualized. Then launches GraphViz to generate
+describes data to be visualized. Then launches <a href="https://graphviz.org/">GraphViz</a> to generate
 bitmap graph in PNG or SVG format.
 </p>
 
-<p>
-By default on your Desktop directory when operated in library mode or
-current working directory when operated as standalone commandline
-application.
-</p>
-
 <p>
 Notes:
 </p>
@@ -435,21 +429,14 @@ Control code in general does the following:
 </li>
 <li>Java reflection/classloaders does not provide mechanism for
 discovering all classes under given package. Therefore you need to
-declare at least some classes to be added to the graph by:
-<ul class="org-ul">
-<li>Manually adding individual classes to the graph.
-</li>
-<li>and/or: Let GraphViz recursively scan and parse specified
-directories with Java source code files to discover class names.
-</li>
-<li>For every class added to the graph, GraphViz will recursively
-inspect it and add all referecned classes to the graph as well.
-</li>
-</ul>
+declare at least some classes to be added to the graph by manually
+adding individual classes to the graph. For every class added to
+the graph, GraphViz will recursively inspect it and add all
+referecned classes to the graph as well.
 </li>
 <li>Graphs easilly get very big and complex so optionally we filter
-important code using classname wildcards patterns based blacklist
-and/or whitelist.
+important code using classname <a href="https://en.wikipedia.org/wiki/Glob_(programming)">glob</a> patterns based blacklist and/or
+whitelist.
 </li>
 <li>Optionally we can tune some rendering parameters like:
 <ul class="org-ul">
@@ -457,7 +444,7 @@ and/or whitelist.
 references) from the graph.
 </li>
 <li>Specify target directory for generated visualization
-files. (Default is user desktop directory)
+files. (Default is current directory)
 </li>
 <li>Keep intermediate GraphViz dot file for later inspection.
 </li>
@@ -479,23 +466,22 @@ classes and visualizing GraphViz itself.
 
 <div class="org-src-container">
 
-<pre class="src src-java">
-// Create graph
-final ClassGraph graph = new ClassGraph();
+<pre class="src src-java"><span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Create graph</span>
+<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>();
 
-// Add some random object to the graph. GraphViz will detect Class from
-// the object.
+<span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Add some random object to the graph. GraphViz will detect Class from</span>
+<span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">the object.</span>
 graph.add(graph);
 
-// Also add some random class to the graph.
-graph.add(Utils.class);
+<span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Also add some random class to the graph.</span>
+graph.add(Utils.<span style="color: #F92672;">class</span>);
 
-// Keep intermediary GraphViz DOT file for reference.
-graph.setKeepDotFile(true);
+<span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Keep intermediary GraphViz DOT file for reference.</span>
+graph.setKeepDotFile(<span style="color: #FF80F4;">true</span>);
 
-// Produce bitmap image titled "JavaInspect.png" to the user Desktop
-// directory
-graph.generateGraph("JavaInspect");
+<span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">Produce bitmap image titled "JavaInspect.png" to the user Desktop</span>
+<span style="color: #8C8C8C;">// </span><span style="color: #8C8C8C;">directory</span>
+graph.generateGraph(<span style="color: #EEDC82;">"JavaInspect"</span>);
 
 </pre>
 </div>
@@ -505,8 +491,8 @@ Note: if desired, more compact version of the above:
 </p>
 <div class="org-src-container">
 
-<pre class="src src-java">new ClassGraph().add(randomObject, RandomClass.class)
-                .setKeepDotFile(true).generateGraph("JavaInspect");
+<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>)
+                .setKeepDotFile(<span style="color: #FF80F4;">true</span>).generateGraph(<span style="color: #EEDC82;">"JavaInspect"</span>);
 </pre>
 </div>
 
@@ -524,67 +510,34 @@ Result:
 </div>
 
 <div id="outline-container-sec-4-2-2" class="outline-4">
-<h4 id="sec-4-2-2"><span class="section-number-4">4.2.2</span> example 2: scan java code, apply filters</h4>
+<h4 id="sec-4-2-2"><span class="section-number-4">4.2.2</span> example 2: GraphViz embedded in another project</h4>
 <div class="outline-text-4" id="text-4-2-2">
-<div class="org-src-container">
-
-<pre class="src src-java">// Create graph
-final ClassGraph graph = new ClassGraph();
-
-// Recursively scan current directory for Java source code and attempt
-// to detect class names from there to be added to the graph.
-graph.addProject(".");
-
-// Blacklist example classes from being shown on the graph
-graph.blacklistClassPattern("eu.svjatoslav.inspector.java.structure.example.*");
-
-// do not show single classes with no relationships on the graph
-graph.hideOrphanedClasses();
-
-// Produce bitmap image titled "JavaInspect full project.png" to the
-// user Desktop directory.
-graph.generateGraph("JavaInspect full project");
-</pre>
-</div>
-<p>
-Result:
-</p>
-<ul class="org-ul">
-<li>Generated PNG image: <a href="JavaInspect%20full%20project.png">JavaInspect full project.png</a>
-</li>
-</ul>
-</div>
-</div>
-
-<div id="outline-container-sec-4-2-3" class="outline-4">
-<h4 id="sec-4-2-3"><span class="section-number-4">4.2.3</span> example 3: GraphViz embedded in another project</h4>
-<div class="outline-text-4" id="text-4-2-3">
 <ol class="org-ol">
 <li>Download project Sixth <a href="https://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz">code snapshot</a>.
 </li>
-<li>Inspect and run *DataGraph.java*.
+<li>Inspect and run <b>DataGraph.java</b>.
 </li>
 </ol>
 </div>
 </div>
 
-<div id="outline-container-sec-4-2-4" class="outline-4">
-<h4 id="sec-4-2-4"><span class="section-number-4">4.2.4</span> Embedding JavaInspect in your Maven project</h4>
-<div class="outline-text-4" id="text-4-2-4">
+<div id="outline-container-sec-4-2-3" class="outline-4">
+<h4 id="sec-4-2-3"><span class="section-number-4">4.2.3</span> Embedding JavaInspect in your Maven project</h4>
+<div class="outline-text-4" id="text-4-2-3">
 <p>
 Declare JavaInspect as dependency:
 </p>
 <div class="org-src-container">
 
-<pre class="src src-xml">&lt;dependencies&gt;
+<pre class="src src-xml">&lt;<span style="color: #A6E22E;">dependencies</span>&gt;
     ...
-    &lt;dependency&gt;
-        &lt;groupId&gt;eu.svjatoslav&lt;/groupId&gt;
-        &lt;artifactId&gt;javainspect&lt;/artifactId&gt;
-        &lt;version&gt;1.6&lt;/version&gt;
-    &lt;/dependency&gt;
+    &lt;<span style="color: #A6E22E;">dependency</span>&gt;
+        &lt;<span style="color: #A6E22E;">groupId</span>&gt;eu.svjatoslav&lt;/<span style="color: #A6E22E;">groupId</span>&gt;
+        &lt;<span style="color: #A6E22E;">artifactId</span>&gt;javainspect&lt;/<span style="color: #A6E22E;">artifactId</span>&gt;
+        &lt;<span style="color: #A6E22E;">version</span>&gt;1.7&lt;/<span style="color: #A6E22E;">version</span>&gt;
+    &lt;/<span style="color: #A6E22E;">dependency</span>&gt;
     ...
-&lt;/dependencies&gt;
+&lt;/<span style="color: #A6E22E;">dependencies</span>&gt;
 </pre>
 </div>
 
@@ -594,15 +547,15 @@ Add Maven repository to retrieve artifact from:
 </p>
 <div class="org-src-container">
 
-<pre class="src src-xml">&lt;repositories&gt;
+<pre class="src src-xml">&lt;<span style="color: #A6E22E;">repositories</span>&gt;
     ...
-    &lt;repository&gt;
-        &lt;id&gt;svjatoslav.eu&lt;/id&gt;
-        &lt;name&gt;Svjatoslav repository&lt;/name&gt;
-        &lt;url&gt;http://www2.svjatoslav.eu/maven/&lt;/url&gt;
-    &lt;/repository&gt;
+    &lt;<span style="color: #A6E22E;">repository</span>&gt;
+        &lt;<span style="color: #A6E22E;">id</span>&gt;svjatoslav.eu&lt;/<span style="color: #A6E22E;">id</span>&gt;
+        &lt;<span style="color: #A6E22E;">name</span>&gt;Svjatoslav repository&lt;/<span style="color: #A6E22E;">name</span>&gt;
+        &lt;<span style="color: #A6E22E;">url</span>&gt;http://www2.svjatoslav.eu/maven/&lt;/<span style="color: #A6E22E;">url</span>&gt;
+    &lt;/<span style="color: #A6E22E;">repository</span>&gt;
     ...
-&lt;/repositories&gt;
+&lt;/<span style="color: #A6E22E;">repositories</span>&gt;
 </pre>
 </div>
 </div>
@@ -697,8 +650,10 @@ of operation).
 </ul>
 </li>
 
-<li>FEATURE: Replace internal java parser in package
-eu.svjatoslav.inspector.java.methods with: <a href="https://javaparser.org/">https://javaparser.org/</a>
+<li>FEATURE: Implement (or integrate existing java parser
+<a href="https://javaparser.org/">https://javaparser.org/</a>) to be able to produce code visualizations
+based on source code (in addition to current reflection based
+approach).
 </li>
 
 <li>FEATURE: Integarte with <a href="http://plantuml.com/class-diagram">PlantUML</a>.
@@ -746,6 +701,18 @@ project build/release process.
 </ul>
 </div>
 </div>
+<div id="outline-container-sec-7" class="outline-2">
+<h2 id="sec-7"><span class="section-number-2">7</span> See also</h2>
+<div class="outline-text-2" id="text-7">
+<p>
+Similar or alternative solutions:
+</p>
+<ul class="org-ul">
+<li><a href="http://www.class-visualizer.net/">http://www.class-visualizer.net/</a>
+</li>
+</ul>
+</div>
+</div>
 </div><div class="col-md-3"><nav id="table-of-contents">
 <div id="text-table-of-contents" class="bs-docs-sidebar">
 <ul class="nav">
@@ -764,13 +731,14 @@ project build/release process.
 </li>
 <li><a href="#sec-5">5. Requirements</a></li>
 <li><a href="#sec-6">6. TO DO</a></li>
+<li><a href="#sec-7">7. See also</a></li>
 </ul>
 </div>
 </nav>
 </div></div></div>
 <footer id="postamble" class="">
 <div><p class="author">Author: Svjatoslav Agejenko</p>
-<p class="date">Created: 2019-01-19 Sat 00:47</p>
+<p class="date">Created: 2021-01-10 P 00:37</p>
 <p class="creator"><a href="http://www.gnu.org/software/emacs/">Emacs</a> 26.1 (<a href="http://orgmode.org">Org-mode</a> 9.1.9)</p>
 </div>
 </footer>
index e2a4f89..b831a37 100644 (file)
@@ -50,13 +50,9 @@ how to instuct Javainspect what to do.
 
 After discovering application structure and optionally filtering out
 unimportant parts, JavaInspect produces GraphViz dot file that
-describes data to be visualized. Then launches GraphViz to generate
+describes data to be visualized. Then launches [[https://graphviz.org/][GraphViz]] to generate
 bitmap graph in PNG or SVG format.
 
-By default on your Desktop directory when operated in library mode or
-current working directory when operated as standalone commandline
-application.
-
 Notes:
 + JavaInspect is developed and tested so far only on GNU/Linux.
 + See: [[https://github.com/pahen/madge][Madge - similar tool for JavaScript]]
@@ -145,20 +141,18 @@ Control code in general does the following:
 1. Create graph object.
 2. Java reflection/classloaders does not provide mechanism for
    discovering all classes under given package. Therefore you need to
-   declare at least some classes to be added to the graph by:
-   + Manually adding individual classes to the graph.
-   + and/or: Let GraphViz recursively scan and parse specified
-     directories with Java source code files to discover class names.
-   + For every class added to the graph, GraphViz will recursively
-     inspect it and add all referecned classes to the graph as well.
+   declare at least some classes to be added to the graph by manually
+   adding individual classes to the graph. For every class added to
+   the graph, GraphViz will recursively inspect it and add all
+   referecned classes to the graph as well.
 3. Graphs easilly get very big and complex so optionally we filter
-   important code using classname wildcards patterns based blacklist
-   and/or whitelist.
+   important code using classname [[https://en.wikipedia.org/wiki/Glob_(programming)][glob]] patterns based blacklist and/or
+   whitelist.
 4. Optionally we can tune some rendering parameters like:
    + Possibility to remove orphaned classes (classes with no
      references) from the graph.
    + Specify target directory for generated visualization
-     files. (Default is user desktop directory)
+     files. (Default is current directory)
    + Keep intermediate GraphViz dot file for later inspection.
 5. Render graph.
 
@@ -199,29 +193,7 @@ Result:
     - Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]]
     - Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]]
 
-*** example 2: scan java code, apply filters
-#+BEGIN_SRC java
-// Create graph
-final ClassGraph graph = new ClassGraph();
-
-// Recursively scan current directory for Java source code and attempt
-// to detect class names from there to be added to the graph.
-graph.addProject(".");
-
-// Blacklist example classes from being shown on the graph
-graph.blacklistClassPattern("eu.svjatoslav.inspector.java.structure.example.*");
-
-// do not show single classes with no relationships on the graph
-graph.hideOrphanedClasses();
-
-// Produce bitmap image titled "JavaInspect full project.png" to the
-// user Desktop directory.
-graph.generateGraph("JavaInspect full project");
-#+END_SRC
-Result:
-    - Generated PNG image: [[file:JavaInspect%20full%20project.png][JavaInspect full project.png]]
-
-*** example 3: GraphViz embedded in another project
+*** example 2: GraphViz embedded in another project
 1. Download project Sixth [[https://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][code snapshot]].
 2. Inspect and run *DataGraph.java*.
 
@@ -234,7 +206,7 @@ Declare JavaInspect as dependency:
     <dependency>
         <groupId>eu.svjatoslav</groupId>
         <artifactId>javainspect</artifactId>
-        <version>1.6</version>
+        <version>1.7</version>
     </dependency>
     ...
 </dependencies>
@@ -299,8 +271,10 @@ LOT of cool ideas could be implemented. For intstance:
     - PlantUML (TODO)
     - Interactive 3D visualization (TODO)
 
-- FEATURE: Replace internal java parser in package
-  eu.svjatoslav.inspector.java.methods with: https://javaparser.org/
+- FEATURE: Implement (or integrate existing java parser
+  https://javaparser.org/) to be able to produce code visualizations
+  based on source code (in addition to current reflection based
+  approach).
 
 - FEATURE: Integarte with [[http://plantuml.com/class-diagram][PlantUML]].
 
index 44bfb57..49ea519 100644 (file)
@@ -1,3 +1,4 @@
 /.idea/
 /target/
-/example.svg
\ No newline at end of file
+/example.svg
+/*.iml
\ No newline at end of file