X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.org;h=7c62a16aee305a58b234ad225f81560e38dc167b;hb=6df8ead7c2fdfe12e2b71d25edcab0abf4b93c89;hp=6625395bc9c2ce53fb5c16024b55d6ef83fcb4f3;hpb=36834c35377485f04f22371d616f2d925bc9ccb1;p=javainspect.git diff --git a/doc/index.org b/doc/index.org index 6625395..7c62a16 100644 --- a/doc/index.org +++ b/doc/index.org @@ -27,9 +27,12 @@ https://github.com/abargnesi/javainspect ** Source code -- [[http://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]] +: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]] -- [[http://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=summary][Browse Git repository online]] +- [[https://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=summary][Browse Git repository online]] - Clone Git repository using command: : git clone https://www2.svjatoslav.eu/git/javainspect.git @@ -38,39 +41,60 @@ Goal: simplify/speed up understanding the computer program code by automatically visualizing its structure. -[[http://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[http://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]]. +[[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]]. 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. -JavaInspect currently has no GUI, configuration files, embedded -scripting support, direct Maven or Ant integration. See [[id:2ad2889e-6c95-4662-b3f4-2c341fc74522][usage]] to learn -how to instuct Javainspect what to do. +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 +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]] * 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 -+ [[http://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[http://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]]. + ++ [[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 :PROPERTIES: @@ -80,30 +104,31 @@ 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 +** 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: +*** Available commandline arguments #+BEGIN_VERSE -j (existing files)... JAR file(s) to render. --n (mandatory, string) - Graph name. +-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. --h +-ho Hide orphaned classes. -w (one to many strings)... @@ -112,13 +137,50 @@ Available commandline arguments: -b (one to many strings)... Blacklist glob(s). --d (existingdirectory) +-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 -** usage via Java API +*** 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: @@ -144,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. @@ -198,30 +258,8 @@ 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 @@ -233,7 +271,7 @@ Declare JavaInspect as dependency: eu.svjatoslav javainspect - 1.6 + 1.7 ... @@ -253,13 +291,6 @@ 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 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 @@ -298,8 +329,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]]. @@ -318,7 +351,7 @@ LOT of cool ideas could be implemented. For intstance: - 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 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 @@ -332,3 +365,7 @@ LOT of cool ideas could be implemented. For intstance: - 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]]