X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.org;h=09f1266b64a0ffbf811c1b77625b67d5b568712a;hb=52abcfeed07d308b2b377985b5cb8a776bb2e375;hp=1751f8d386e558c4ea6bf66bbf02a46773172d05;hpb=8b0301eb96609f08539f2f77a7a476f6b0bdd024;p=javainspect.git diff --git a/doc/index.org b/doc/index.org index 1751f8d..09f1266 100644 --- a/doc/index.org +++ b/doc/index.org @@ -7,138 +7,201 @@ 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: +#+HTML_HEAD: +#+HTML_HEAD: " +#+HTML_HEAD: * 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 - - ... - - eu.svjatoslav - javainspect - 1.3 - - ... - + + ... + + eu.svjatoslav + javainspect + 1.6 + + ... + #+END_SRC Add Maven repository to retrieve artifact from: #+BEGIN_SRC xml - - ... - - svjatoslav.eu - Svjatoslav repository - http://www2.svjatoslav.eu/maven/ - - ... - + + ... + + svjatoslav.eu + Svjatoslav repository + http://www2.svjatoslav.eu/maven/ + + ... + #+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