X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.html;h=767065edb03c336eec292e3b1b523c75d85d1130;hb=dda66ce5668b5e27e696759ef5c895d044a572bc;hp=33fb1cd8d569dd3639bbd80533db4a0ba8b9efe1;hpb=8886bb51f2caf11b8e778bacb4c8ea18ac7f1027;p=javainspect.git diff --git a/doc/index.html b/doc/index.html index 33fb1cd..767065e 100644 --- a/doc/index.html +++ b/doc/index.html @@ -4,7 +4,7 @@ JavaInspect - Utility to visualize java software - + @@ -144,22 +144,29 @@ for the JavaScript code in this tag.
-
@@ -181,43 +191,51 @@ 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 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.

-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 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.

-
- -
-

2 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. +To get JavaInspect into same classpath with your projecs I so far came +up with 2 solutions:

-
-
-
-

3 Example graphs

-
+
    +
  1. Add JavaInspect library in your project as a dependency. +
    2. +
  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. +
    3. +
+

-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 format. By default on your Desktop directory.

-A very simple example: +Note: GraphViz is developed and tested so far only on GNU Linux.

+
+
+ +
+

2 Example graphs

+
+
+ + +
  • Example visualization of Sixth project: architecture graphs. +
    • +
    -
    -

    4 Usage example 1

    -
    +
    +

    3 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. +
    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. +
    3. Graphs easilly get very big and complex so optionally we filter +important code using classname wildcards patterns based blacklist +and/or whitelist. +
      4. +
    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. +
    5. Render graph. +
      6. +
    +
    + + +
    +

    3.1 example 1: individually picked objects

    +

    This example demonstrates generating of class graph from hand picked -classes. +classes and visualizing GraphViz itself.

    @@ -251,22 +326,31 @@ classes. 
    // 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.
+// 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 and keep intermediary GraphViz DOT file for reference.
-graph.generateGraph("JavaInspect", true);
+// directory
+graph.generateGraph("JavaInspect");
    +

    +Note: if desired, more compact version of the above: +

    +
    + +
    new ClassGraph().add(randomObject, RandomClass.class)
+                .setKeepDotFile(true).generateGraph("JavaInspect");
+
    +

    @@ -281,21 +365,20 @@ Result:

    -
    -

    5 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. -

    - +
    +

    3.2 example 2: scan java code, apply filters

    +
    -
    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.*");
+graph.blacklistClassPattern("eu.svjatoslav.inspector.java.structure.example.*");
 
 // do not show single classes with no relationships on the graph
 graph.hideOrphanedClasses();
@@ -314,10 +397,11 @@ Result:
    +
    -
    -

    6 Embedding JavaInspect in your Maven project

    -
    +
    +

    4 Embedding JavaInspect in your Maven project

    +

    Declare JavaInspect as dependency:

    @@ -328,7 +412,7 @@ Declare JavaInspect as dependency: <dependency> <groupId>eu.svjatoslav</groupId> <artifactId>javainspect</artifactId> - <version>1.3</version> + <version>1.5-SNAPSHOT</version> </dependency> ... </dependencies> @@ -355,9 +439,9 @@ Add Maven repository to retrieve artifact from:
    -
    -

    7 Requirements

    -
    +
    +

    5 Requirements

    +

    GraphViz - shall be installed on the computer.

    @@ -365,15 +449,52 @@ Add Maven repository to retrieve artifact from:

    On Ubuntu/Debian use:

    -
    -sudo apt-get install graphviz
+
    
+
+
    sudo apt-get install graphviz
    +
    +

    6 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. +
      • +
    • FEATURE: add dark theme +
      • +
    • FEATURE: sort Class fields by alphabet +
      • +
    • FEATURE: visualize also concrete field values so it could be used as +ultra cool runtime logging framework +
      • +
    • FEATURE: possibility to visualize structure and data from JVM +snapshot +
      • +
    • FEATURE: possibility to attach to remote process to visualize +data/structure using JVM debug port and mechanism. +
      • +
    • FEATURE: possibility to attach to JVM using JVM agent +
      • +
    • FEATURE: possibility to script javainspect behavior +
      • +
    • FEATURE: possibility to select classes/fields/values to be +visualized in SQL like syntax +
      • +
    • FEATURE: configurable maven plugin to generate graphs as part of the +project build/release process +
      • +
    +
    +
    +

    Author: Svjatoslav Agejenko

    -

    Created: 2015-02-02 Mon 19:49

    +

    Created: 2015-03-03 Tue 22:38

    Emacs 24.4.1 (Org mode 8.2.10)

    Validate