X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.html;h=dfef6db750eca7a9e3eb2fe069b00d8f7aedb850;hb=6df8ead7c2fdfe12e2b71d25edcab0abf4b93c89;hp=958f4ef77630346fb59a703a5cff1f163ab4c3ee;hpb=8b0301eb96609f08539f2f77a7a476f6b0bdd024;p=javainspect.git diff --git a/doc/index.html b/doc/index.html index 958f4ef..dfef6db 100644 --- a/doc/index.html +++ b/doc/index.html @@ -3,23 +3,30 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+ + ++Clone Git repository using command: +
++git clone https://www2.svjatoslav.eu/git/javainspect.git +
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. +See example produced graphs for Sixth 3D - 3D engine project.
-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. +JavaInspect can be used as a standalone commandline utility as well as +java library. JavaInspect uses primarily Java built-in reflection to +discover and visualize any part of Java program.
--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 currently has no graphical user interface, configuration +files, embedded scripting support, direct Maven, Gradle or Ant +integration. See usage to learn how to instuct Javainspect what to do.
--Example visualization of Sixth project: architecture graphs. +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 or SVG format.
+Notes: +
+A very simple example:
-Graph legend:
--
-This example demonstrates generating of class graph from hand picked -classes. +GraphViz - shall be installed on the computer.
++On Ubuntu/Debian GraphViz can be installed using: +
sudo apt-get install graphviz ++
// Create graph -final ClassGraph graph = new ClassGraph(); ++To use JavaInspect via Java API, no further installation is +needed. JavaInspect will be embedded into your project as dependency. +This is described in 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 Source code. +
+ ++Then study and execute installation script: +
++commandline launcher/install +-// 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. -// Add some object to the graph. -graph.addObject(graph); ++After installation, new commandline tool should be available +
++javainspect +-// Add some class to the graph. -graph.addClass(Utils.class); -// Produce bitmap image titled "JavaInspect.png" to the user Desktop -// directory and keep intermediary GraphViz DOT file for reference. -graph.generateGraph("JavaInspect", true); ++Quick commandline usage help can be viewed by issuing +
++javainspect --help
+JavaInspect can be controlled in 2 different ways: +
+ +
+-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.
+
+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: +
+-Result: +Currently JavaInspect uses following algorithm to add classes to +rendered graph:
++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: +
+ +-Recursively scan current directory for Java source code and attempt to -detect class names from there to be added to the graph. +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: +
++This example demonstrates generating of class graph from hand picked +classes and visualizing GraphViz itself.
+// Create graph +final ClassGraph graph = new ClassGraph(); + +// Add some random object to the graph. GraphViz will detect Class from +// the object. +graph.add(graph); -graph.addProject("."); +// Also add some random class to the graph. +graph.add(Utils.class); -// Blacklist example classes from being shown on the graph -graph.getFilter().blacklistClassPattern( - "eu.svjatoslav.inspector.java.structure.example.*"); +// Keep intermediary GraphViz DOT file for reference. +graph.setKeepDotFile(true); -// do not show single classes with no relationships on the graph -graph.hideOrphanedClasses(); +// Produce bitmap image titled "JavaInspect.png" to the user Desktop +// directory +graph.generateGraph("JavaInspect"); -// Produce bitmap image titled "JavaInspect full project.png" to the -// user Desktop directory. -graph.generateGraph("JavaInspect full project");
+Note: if desired, more compact version of the above: +
+new ClassGraph().add(randomObject, RandomClass.class) + .setKeepDotFile(true).generateGraph("JavaInspect"); ++
Result:
Declare JavaInspect as dependency:
<dependencies> ... <dependency> <groupId>eu.svjatoslav</groupId> <artifactId>javainspect</artifactId> - <version>1.3</version> + <version>1.7</version> </dependency> ... </dependencies> @@ -347,7 +681,6 @@ Declare JavaInspect as dependency: Add Maven repository to retrieve artifact from:-<repositories> ... <repository> @@ -361,67 +694,118 @@ Add Maven repository to retrieve artifact from:
-GraphViz - shall be installed on the computer. +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:
--On Ubuntu/Debian use: -
--sudo apt-get install graphviz --
+Similar or alternative solutions: +
+