X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.org;h=7c62a16aee305a58b234ad225f81560e38dc167b;hb=6df8ead7c2fdfe12e2b71d25edcab0abf4b93c89;hp=09f1266b64a0ffbf811c1b77625b67d5b568712a;hpb=52abcfeed07d308b2b377985b5cb8a776bb2e375;p=javainspect.git diff --git a/doc/index.org b/doc/index.org index 09f1266..7c62a16 100644 --- a/doc/index.org +++ b/doc/index.org @@ -1,77 +1,204 @@ #+TITLE: JavaInspect - Utility to visualize java software ------ -- [[http://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz][download latest snapshot]] +* (document settings) :noexport: +** use dark style for TWBS-HTML exporter +#+HTML_HEAD: +#+HTML_HEAD: +#+HTML_HEAD: +#+HTML_HEAD: -- This program is free software; you can redistribute it and/or modify - 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. +* General +- This program is free software: you can redistribute it and/or modify + it under the terms of the [[https://www.gnu.org/licenses/lgpl.html][GNU Lesser General Public License]] as + published by the Free Software Foundation, either version 3 of the + License, or (at your option) any later version. - Program authors: - Svjatoslav Agejenko - - Homepage: http://svjatoslav.eu + - Homepage: https://svjatoslav.eu - Email: mailto://svjatoslav@svjatoslav.eu + - [[https://www.svjatoslav.eu/projects/][Other software projects 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]] +** Source code +:PROPERTIES: +:ID: 032b7997-f582-4203-b31a-43ef7b654ed6 +:END: +- [[https://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]] -* (document settings) :noexport: -** use dark style for TWBS-HTML exporter -#+HTML_HEAD: -#+HTML_HEAD: -#+HTML_HEAD: " -#+HTML_HEAD: +- [[https://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=summary][Browse Git repository online]] -* General +- Clone Git repository using command: + : git clone https://www2.svjatoslav.eu/git/javainspect.git + +* Goal and operating principle 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 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. +[[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[https://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]]. -To get JavaInspect into same classpath with your projecs I so far came -up with 2 solutions: +JavaInspect can be used as a [[id:acf1896a-74b4-4914-acf6-a77075e07f25][standalone commandline utility]] as well as +[[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][java library]]. JavaInspect uses primarily Java built-in reflection to +discover and visualize any part of Java program. -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. +JavaInspect currently has no graphical user interface, configuration +files, embedded scripting support, direct Maven, Gradle 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. +describes data to be visualized. Then launches [[https://graphviz.org/][GraphViz]] to generate +bitmap graph in PNG or SVG format. -Note: GraphViz is developed and tested so far only on GNU/Linux. +Notes: ++ JavaInspect is developed and tested so far only on GNU/Linux. * Example graphs + A very simple example: - [[file:example.png][file:example.resized.png]] + [[file:example.png][file:example-thumbnail.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]]. + ++ [[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[https://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]]. + +* Installation +[[http://www.graphviz.org/][GraphViz]] - shall be installed on the computer. + +On Ubuntu/Debian GraphViz can be installed using: +#+BEGIN_SRC sh +sudo apt-get install graphviz +#+END_SRC + +To use JavaInspect via Java API, no further installation is +needed. JavaInspect will be embedded into your project as dependency. +This is described in [[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][usage via Java API]]. It will expect GraphViz to be +available in the system. + +To use JavaInspect as a commandline tool, JavaInspect source +repository has to be cloned locally: See [[id:032b7997-f582-4203-b31a-43ef7b654ed6][Source code]]. + +Then study and execute installation script: +: commandline launcher/install + +After installation, new commandline tool should be available +: javainspect + +Quick commandline usage help can be viewed by issuing +: javainspect --help * 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: +*** Available commandline arguments +#+BEGIN_VERSE +-j (existing files)... + JAR file(s) to render. + +-c (existing directories)... + Classpath directories + +-n (string) + Graph name. (default: "graph") + +--debug + Show debug info. + +-h, --help + Show commandline usage help. + +-k + Keep dot file. + +-ho + Hide orphaned classes. + +-w (one to many strings)... + Whitelist glob(s). + +-b (one to many strings)... + Blacklist glob(s). + +-r (one to many strings)... + root class(es). + +-d (existing directory) + Target directory. Default is current directory. + +-t (options: png, svg) + Target image type. Default is: svg. +#+END_VERSE +*** Specifying classes to render +Normal Java application has immense complexity. In addition to code +that was directly written by particular project developers, lots of +functionality is typically added as frameworks or libraries to the +project. In addition there is significant Java standard library. + +Because JavaInspect uses reflection, it does not easily distinguish +between those. In normal situation you would rather want to visualize +only code that was developed specifically for your project and leave +frameworks like Spring etc. out. If you visualize all classes that are +possibly reachable from you project, you will easily get huge and +incomprehensible graph. + +JavaInspect can digest compiled Java classes in 2 modes: +1. Provide list of Jar files. Use *-j* option. +2. Provide list of filesystem directories that can be used as + classpath root. Use *-c* option. + +Currently JavaInspect uses following algorithm to add classes to +rendered graph: + +- All classes that were found in Jar files are added to graph by default. +- None of the classes that were found in filesystem directories are + added to the graph by default (unless explicitly referenced). (TODO: + for consistency it would be better to add them too by default) +- If whitelist is specified (*-w* option) everything that is not + matched by whitelist pattern(s) will be removed from the graph. +- If blacklist is specified (*-b* option) everything that is matched + by blacklist pattern(s) will be removed from the graph. +- Root classes can be specified using *-r* option. Root classes will + be added to the graph. JavaInspect will then try to recursively + discover all classes that were referenced by root class and add + those also to the graph. + +** 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. @@ -79,25 +206,23 @@ 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. -** 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. @@ -133,33 +258,11 @@ 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 -1. Download project Sixth [[http://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][code snapshot]]. +*** 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*. -* Embedding JavaInspect in your Maven project +*** Embedding JavaInspect in your Maven project Declare JavaInspect as dependency: #+BEGIN_SRC xml @@ -168,7 +271,7 @@ Declare JavaInspect as dependency: eu.svjatoslav javainspect - 1.6 + 1.7 ... @@ -188,31 +291,81 @@ Add Maven repository to retrieve artifact from: #+END_SRC -* Requirements -[[http://www.graphviz.org/][GraphViz]] - shall be installed on the computer. - -On Ubuntu/Debian use: -#+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 - ultra cool runtime logging framework -- FEATURE: possibility to visualize structure and data from JVM - snapshot -- FEATURE: possibility to attach to remote process to visualize +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: 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]]. + +- 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 [[https://www3.svjatoslav.eu/projects/sixth-3d/][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. +* See also +Similar or alternative solutions: ++ http://www.class-visualizer.net/ ++ [[https://github.com/pahen/madge][Madge - similar tool for JavaScript]]