X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.org;h=09f1266b64a0ffbf811c1b77625b67d5b568712a;hb=52abcfeed07d308b2b377985b5cb8a776bb2e375;hp=873b0ddfc11983d3f6e0031fb8e38fcc6d16c922;hpb=c508bf97e017675b49df989b7f5a64cbd31d9aa3;p=javainspect.git diff --git a/doc/index.org b/doc/index.org index 873b0dd..09f1266 100644 --- a/doc/index.org +++ b/doc/index.org @@ -7,12 +7,26 @@ 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 @@ -41,7 +55,7 @@ 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. -Note: GraphViz is developed and tested so far only on GNU Linux. +Note: GraphViz is developed and tested so far only on GNU/Linux. * Example graphs + A very simple example: @@ -52,7 +66,7 @@ Note: GraphViz is developed and tested so far only on GNU Linux. file:legend.png -+ Example visualization of [[http://www2.svjatoslav.eu/gitbrowse/sixth/doc/][Sixth]] project: [[http://www2.svjatoslav.eu/projects/sixth/codegraphs/][architecture graphs]]. ++ 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 @@ -83,99 +97,111 @@ Control code in general does the following: 5. Render graph. -** example 1 +** 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]] -** 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(); + +// 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.getFilter().blacklistClassPattern( - "eu.svjatoslav.inspector.java.structure.example.*"); +// 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(); +// 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"); +// 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