X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;ds=sidebyside;f=doc%2Findex.html;h=dfef6db750eca7a9e3eb2fe069b00d8f7aedb850;hb=89e8e57e91d905a5acfc3c92272bec0a179646b4;hp=4c426bfacab52fe8f2691b2112cfb65eb0777002;hpb=92e7df28bd9624ce5d35fac41e7f06f7d23d9217;p=javainspect.git diff --git a/doc/index.html b/doc/index.html index 4c426bf..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 primarily uses Java reflection to -discover and visualize any part of Java program provided that -classes to be visualised are available in the classpath. +See example produced graphs for Sixth 3D - 3D engine project.
-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. +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.
-To get JavaInspect into same classpath with your projecs I so far came -up with 2 solutions: +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.
-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 GraphViz to generate +bitmap graph in PNG or SVG format.
-Note: GraphViz is developed and tested so far only on GNU Linux. +Notes:
++A very simple example: +
-+
+GraphViz - shall be installed on the computer. +
+ ++On Ubuntu/Debian GraphViz can be installed using: +
+sudo apt-get install graphviz ++
+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 ++ + +
+After installation, new commandline tool should be available +
++javainspect ++ + +
+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: +
++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: +
+ +-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 +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.
@@ -276,55 +574,40 @@ 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 ++// Create graph final ClassGraph graph = new ClassGraph(); // Add some random object to the graph. GraphViz will detect Class from @@ -340,6 +623,7 @@ graph.setKeepDotFile(true); // Produce bitmap image titled "JavaInspect.png" to the user Desktop // directory graph.generateGraph("JavaInspect"); +
new ClassGraph().add(randomObject, RandomClass.class) .setKeepDotFile(true).generateGraph("JavaInspect");@@ -358,74 +641,35 @@ Note: if desired, more compact version of the above: Result:
// 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"); --
-Result: -
-Declare JavaInspect as dependency:
<dependencies> ... <dependency> <groupId>eu.svjatoslav</groupId> <artifactId>javainspect</artifactId> - <version>1.5-SNAPSHOT</version> + <version>1.7</version> </dependency> ... </dependencies> @@ -437,7 +681,6 @@ Declare JavaInspect as dependency: Add Maven repository to retrieve artifact from:-<repositories> ... <repository> @@ -451,65 +694,118 @@ Add Maven repository to retrieve artifact from:
-GraphViz - shall be installed on the computer. -
- +-On Ubuntu/Debian use: +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:
-sudo apt-get install graphviz --
+Similar or alternative solutions: +
+