it under the terms of version 3 of the [[https://www.gnu.org/licenses/lgpl.html][GNU Lesser General Public
License]] or later as published by the Free Software Foundation.
-- Program author:
+- Program authors:
- Svjatoslav Agejenko
- - Homepage: http://svjatoslav.eu
- - Email: mailto://svjatoslav@svjatoslav.eu
+ - Homepage: http://svjatoslav.eu
+ - Email: mailto://svjatoslav@svjatoslav.eu
-- [[http://svjatoslav.eu/programs.jsp][other applications hosted at svjatoslav.eu]]
+ - Tony Bargnesi
+ - GitHub fork for the project:
+ https://github.com/abargnesi/javainspect
+
+- [[http://www.svjatoslav.eu/programs.jsp][other applications hosted at svjatoslav.eu]]
+
+* (document settings) :noexport:
+** use dark style for TWBS-HTML exporter
+#+HTML_HEAD: <link href="https://bootswatch.com/4/darkly/bootstrap.min.css" rel="stylesheet">
+#+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
+#+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.1/js/bootstrap.min.js"></script>"
+#+HTML_HEAD: <style type="text/css">
+#+HTML_HEAD: footer {background-color: #111 !important;}
+#+HTML_HEAD: pre {background-color: #111; color: #ccc;}
+#+HTML_HEAD: </style>
* General
Goal: simplify/speed up understanding the computer program code by
automatically visualizing its structure.
-JavaInspect is a Java library that you can embed into your Java
-project with a few lines of Maven configuration and then visualize any
-part of your Java program structure with few simple JavaInspect API
-calls at application runtime.
-
-JavaInspect uses Java reflection to discover class relations and
-structure and produces GraphViz dot file that describes your
-application. Then launches GraphViz to generate bitmap graph in PNG
-format on your Desktop directory.
-
-* Current status
-This is simple utility, quickly written. Tested on GNU Linux (can be
-relatively simply ported to other operating systems too). So far I
-used it for my own needs. There might be bugs and missing
-features. Feedback and code contributions are welcome.
+JavaInspect is a Java library that primarily uses Java reflection to
+discover and visualize any part of Java program provided that
+classes to be visualised are available in the classpath.
-* Example graphs
-Example visualization of [[http://www2.svjatoslav.eu/gitbrowse/sixth/doc/][Sixth]] project: [[http://www2.svjatoslav.eu/projects/sixth/codegraphs/][architecture graphs]].
-
-A very simple example:
+JavaInspect currently has no GUI, configuration files, embedded
+scripting support, direct Maven or Ant integration. The only way to
+instuct Javainspect what to do is by using its Java API.
-[[file:example.png][file:example.resized.png]]
+To get JavaInspect into same classpath with your projecs I so far came
+up with 2 solutions:
+1. Add JavaInspect library in your project as a dependency.
+2. Create new Java project for the purpose visualizing your other
+ projects and include JavaInspect and your projecs binary artifacts
+ (Jar's) into new project classpath. Built binary Jar's (with no
+ source code) are sufficient because JavaInspect operates via
+ reflection.
-Graph legend:
+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
+bitmap graph in PNG format. By default on your Desktop directory.
-file:legend.png
+Note: GraphViz is developed and tested so far only on GNU/Linux.
-* Usage example 1
+* Example graphs
++ A very simple example:
+
+ [[file:example.png][file:example.resized.png]]
+
+ Graph legend:
+
+ file:legend.png
+
++ Example visualization of [[http://www2.svjatoslav.eu/gitbrowse/sixth-3d/doc/][Sixth 3D]] project: [[http://www2.svjatoslav.eu/gitbrowse/sixth-3d/doc/codeGraph/][architecture graphs]].
+
+* Usage
+Currently the only way to control JavaInspect is by using Java
+API. Simple Java based control/configuration code needs to be written
+for each project. I usually put such code into directories devoted for
+JUnit tests. Because it needs not to be compiled/embedded into final
+product or project artifact I'm just willing to visualize.
+
+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.
+3. Graphs easilly get very big and complex so optionally we filter
+ important code using classname wildcards 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)
+ + Keep intermediate GraphViz dot file for later inspection.
+5. Render graph.
+
+
+** example 1: individually picked objects
This example demonstrates generating of class graph from hand picked
-classes.
+classes and visualizing GraphViz itself.
#+BEGIN_SRC java
- // Create graph
- final ClassGraph graph = new ClassGraph();
- // While classes and objects can be immediately passed to ClassGraph
- // constructor as arguments, it is also possible to add them one by
- // one as in the following example.
+// Create graph
+final ClassGraph graph = new ClassGraph();
+
+// Add some random object to the graph. GraphViz will detect Class from
+// the object.
+graph.add(graph);
- // Add some object to the graph.
- graph.addObject(graph);
+// Also add some random class to the graph.
+graph.add(Utils.class);
- // Add some class to the graph.
- graph.addClass(Utils.class);
+// Keep intermediary GraphViz DOT file for reference.
+graph.setKeepDotFile(true);
+
+// Produce bitmap image titled "JavaInspect.png" to the user Desktop
+// directory
+graph.generateGraph("JavaInspect");
- // Produce bitmap image titled "JavaInspect.png" to the user Desktop
- // directory and keep intermediary GraphViz DOT file for reference.
- graph.generateGraph("JavaInspect", true);
#+END_SRC
+Note: if desired, more compact version of the above:
+#+BEGIN_SRC java
+new ClassGraph().add(randomObject, RandomClass.class)
+ .setKeepDotFile(true).generateGraph("JavaInspect");
+#+END_SRC
Result:
- Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]]
- Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]]
-* Usage example 2
-Recursively scan current directory for Java source code and attempt to
-detect class names from there to be added to the graph.
-
+** example 2: scan java code, apply filters
#+BEGIN_SRC java
- graph.addProject(".");
+// Create graph
+final ClassGraph graph = new ClassGraph();
- // Blacklist example classes from being shown on the graph
- graph.getFilter().blacklistClassPattern(
- "eu.svjatoslav.inspector.java.structure.example.*");
+// Recursively scan current directory for Java source code and attempt
+// to detect class names from there to be added to the graph.
+graph.addProject(".");
- // do not show single classes with no relationships on the graph
- graph.hideOrphanedClasses();
+// Blacklist example classes from being shown on the graph
+graph.blacklistClassPattern("eu.svjatoslav.inspector.java.structure.example.*");
- // Produce bitmap image titled "JavaInspect full project.png" to the
- // user Desktop directory.
- graph.generateGraph("JavaInspect full project");
+// 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
+1. Download project Sixth [[http://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][code snapshot]].
+2. Inspect and run *DataGraph.java*.
+
* Embedding JavaInspect in your Maven project
Declare JavaInspect as dependency:
#+BEGIN_SRC xml
- <dependencies>
- ...
- <dependency>
- <groupId>eu.svjatoslav</groupId>
-
<artifactId>javainspect</artifactId>
- <version>1.3</version>
- </dependency>
- ...
- </dependencies>
+<dependencies>
+ ...
+ <dependency>
+ <groupId>eu.svjatoslav</groupId>
+ <artifactId>javainspect</artifactId>
+ <version>1.6</version>
+ </dependency>
+ ...
+</dependencies>
#+END_SRC
Add Maven repository to retrieve artifact from:
#+BEGIN_SRC xml
- <repositories>
- ...
- <repository>
- <id>svjatoslav.eu</id>
- <name>Svjatoslav repository</name>
- <url>http://www2.svjatoslav.eu/maven/</url>
- </repository>
- ...
- </repositories>
+<repositories>
+ ...
+ <repository>
+ <id>svjatoslav.eu</id>
+ <name>Svjatoslav repository</name>
+ <url>http://www2.svjatoslav.eu/maven/</url>
+ </repository>
+ ...
+</repositories>
#+END_SRC
* Requirements
-
[[http://www.graphviz.org/][GraphViz]] - shall be installed on the computer.
On Ubuntu/Debian use:
-: sudo apt-get install graphviz
-* TODO
-- BUG: Should not hide references if there are too many of them to
- classes if referring classes are not visible anyway because of
- blacklist/whitelist rules. Basically reference counting should
- exclude not visible classes.
-- BUG: Current code is quite messy (because of lack of time) things
- were implemented ad-hoc. Needs cleanup/refactoring for better
- readability.
+#+BEGIN_SRC sh
+sudo apt-get install graphviz
+#+END_SRC
+* TO DO
+- BUG: Should not hide references if there are too many of them to classes if
+ referring classes are not visible anyway because of blacklist/whitelist rules.
+ Basically reference counting should exclude not visible classes.
+- FEATURE: replace internal java parser in package
+ eu.svjatoslav.inspector.java.methods with: https://javaparser.org/
+- FEATURE: integarte with [[http://plantuml.com/class-diagram][PlantUML]].
- FEATURE: add dark theme
- FEATURE: sort Class fields by alphabet
- FEATURE: visualize also concrete field values so it could be used as
projects / javainspect.git / blobdiff