X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.html;h=4c426bfacab52fe8f2691b2112cfb65eb0777002;hb=6101cbd91218bce7cc2b00ddbfca329bf5cdaf31;hp=958f4ef77630346fb59a703a5cff1f163ab4c3ee;hpb=8b0301eb96609f08539f2f77a7a476f6b0bdd024;p=javainspect.git diff --git a/doc/index.html b/doc/index.html index 958f4ef..4c426bf 100644 --- a/doc/index.html +++ b/doc/index.html @@ -4,7 +4,7 @@ JavaInspect - Utility to visualize java software - + @@ -144,13 +144,17 @@ for the JavaScript code in this tag.
@@ -188,43 +192,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.

    @@ -258,22 +327,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");
+
    +

    @@ -288,21 +366,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();
@@ -322,9 +399,22 @@ Result:
    -
    -

    6 Embedding JavaInspect in your Maven project

    -
    +
    +

    3.3 example 3: GraphViz embedded in another project

    +
    +
      +
    1. Download project Sixth code snapshot. +
      2. +
    2. Inspect and run DataGraph.java. +
      3. +
    +
    +
    +
    + +
    +

    4 Embedding JavaInspect in your Maven project

    +

    Declare JavaInspect as dependency:

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

    7 Requirements

    -
    +
    +

    5 Requirements

    +

    GraphViz - shall be installed on the computer.

    @@ -372,24 +462,22 @@ Add Maven repository to retrieve artifact from:

    On Ubuntu/Debian use:

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

    8 TODO

    -
    +
    +
    +

    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.
      • -
    • BUG: Current code is quite messy (because of lack of time) things -were implemented ad-hoc. Needs cleanup/refactoring for better -readability. -
    • FEATURE: add dark theme
    • FEATURE: sort Class fields by alphabet @@ -419,7 +507,7 @@ project build/release process

    Author: Svjatoslav Agejenko

    -

    Created: 2015-02-03 Tue 20:39

    +

    Created: 2015-03-07 Sat 00:10

    Emacs 24.4.1 (Org mode 8.2.10)

    Validate