Goal: simplify/speed up understanding the computer program code by
automatically visualizing its structure.
-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.
+JavaInspect is a Java library/commandline utility that primarily uses
+Java reflection to discover and visualize any part of Java program.
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.
-
-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.
+scripting support, direct Maven or Ant integration. See [[id:2ad2889e-6c95-4662-b3f4-2c341fc74522][usage]] to learn
+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
-bitmap graph in PNG format. By default on your Desktop directory.
+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.
Note: GraphViz is developed and tested so far only on GNU/Linux.
+ 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
+ :PROPERTIES:
+ :ID: 2ad2889e-6c95-4662-b3f4-2c341fc74522
+ :END:
+JavaInspect can be controlled in 2 different ways:
++ [[id:acf1896a-74b4-4914-acf6-a77075e07f25][as standalone commandline utility]]
++ [[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][as embedded Java library via Java API]]
+
+** usage as commandline utility
+ :PROPERTIES:
+ :ID: acf1896a-74b4-4914-acf6-a77075e07f25
+ :END:
+To enable commandline support, (study and) execute script:
+: commandline launcher/install
+
+Warning: It was tested only on Debian Stretch linux.
+
+Available commandline arguments:
+#+BEGIN_VERSE
+-j (existing files)...
+ JAR file(s) to render.
+
+-n (mandatory, string)
+ Graph name.
+
+--debug
+ Show debug info.
+
+-k
+ Keep dot file.
+
+-h
+ Hide orphaned classes.
+
+-w (one to many strings)...
+ Whitelist glob(s).
+
+-b (one to many strings)...
+ Blacklist glob(s).
+
+-d (existingdirectory)
+ Target directory. Default is current directory.
+
+-t (options: png, svg)
+ Target image type. Default is: svg.
+#+END_VERSE
+** usage via Java API
+ :PROPERTIES:
+ :ID: bbeeffc8-3767-440d-8d93-ec9124dd60ee
+ :END:
+Requires that classes to be visualised are available in the classpath.
+
+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.
+
+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.
5. Render graph.
-** example 1: individually picked objects
+*** example 1: individually picked objects
This example demonstrates generating of class graph from hand picked
classes and visualizing GraphViz itself.
- Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]]
- Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]]
-** example 2: scan java code, apply filters
+*** example 2: scan java code, apply filters
#+BEGIN_SRC java
// Create graph
final ClassGraph graph = new ClassGraph();
Result:
- Generated PNG image: [[file:JavaInspect%20full%20project.png][JavaInspect full project.png]]
-** example 3: GraphViz embedded in another project
+*** 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
+*** Embedding JavaInspect in your Maven project
Declare JavaInspect as dependency:
#+BEGIN_SRC xml
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
+Note: Because this is side project (and I have many of them) I can
+only contribute few hours per year at average. Any help is welcome. A
+LOT of cool ideas could be implemented. For intstance:
+
+- 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: Orphaned class removal does not work always. There are many
+ bugs and corner cases to find and fix still.
+
+- BUG: Code is not very readable. Document and refactor for better
+ maintainability.
+
+- FEATURE: Create installable DEB package.
+ - Submit it to some Debian developer for integration or become
+ Debian package maintainer.
+
+- FEATURE: Make it modular. That is: central part, an application
+ model could be standalone and serializable.
+
+ - There could be multiple ways to acquire model:
+ - By introspecting application via Java reflections (current mode
+ of operation).
+ - By parsing java source. (unfinished)
+
+ - There could be ways to manipulate model:
+ - Store/load/compare.
+ - Trim uninteresting parts.
+ - Highlight important parts.
+
+ - There could be multiple ways to render model:
+ - PNG/SVG (currently implemented)
+ - PlantUML (TODO)
+ - Interactive 3D visualization (TODO)
+
+- 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
- ultra cool runtime logging framework
-- FEATURE: possibility to visualize structure and data from JVM
- snapshot
-- FEATURE: possibility to attach to remote process to visualize
+
+- FEATURE: Integarte with [[http://plantuml.com/class-diagram][PlantUML]].
+
+- FEATURE: Add dark theme for generated graphs.
+
+- FEATURE: Sort Class fields by alphabet.
+
+- FEATURE: Visualize also concrete field values so it could be used as
+ ultra cool runtime logging/debugging framework.
+
+- FEATURE: Possibility to visualize structure and data from JVM
+ snapshot.
+
+- FEATURE: Possibility to attach to remote process to visualize
data/structure using JVM debug port and mechanism.
-- FEATURE: possibility to attach to JVM using JVM agent
-- FEATURE: possibility to script javainspect behavior
-- FEATURE: possibility to select classes/fields/values to be
- visualized in SQL like syntax
-- FEATURE: configurable maven plugin to generate graphs as part of the
- project build/release process
+
+- FEATURE: Possibility to attach to JVM using JVM agent.
+
+- FEATURE: Possibility to inspect graphs in 3D using [[http://www2.svjatoslav.eu/gitbrowse/sixth-3d/doc/index.html][Sixth 3D engine]].
+
+- FEATURE: Possibility to select classes/fields/values to be
+ visualized in some graph query language. For greater flexibility in
+ comparison to currently supported glob syntax.
+
+- FEATURE: Add option to control JavaInspect via JSON or XML config
+ file. For example different graphs for given project could be
+ defined once in plain text config, possibly with the aid of some
+ interactive utility. Then defined graphs could be updated as part of
+ project build or release process.
+
+- FEATURE: Configurable maven plugin to generate graphs as part of the
+ project build/release process.
projects / javainspect.git / blobdiff