X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.html;h=5a1a1665516a6d73f3e086a86db711155240fef4;hb=36834c35377485f04f22371d616f2d925bc9ccb1;hp=58364492dce277453099f39f1ac5f6215bd66435;hpb=827fc6629a9905006ebef0274d0271386e68d128;p=javainspect.git diff --git a/doc/index.html b/doc/index.html index 5836449..5a1a166 100644 --- a/doc/index.html +++ b/doc/index.html @@ -1,270 +1,423 @@ - - - + + - - - JavaInspect - Utility to visualize java software - - + + + + + + + + + - -
-

JavaInspect - Utility to visualize java software

-
-

Table of Contents

-
-
+
+

4.2 usage via Java API

+
+

+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: +

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

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

@@ -273,36 +426,47 @@ product or project artifact I'm just willing to visualize. Control code in general does the following:

    -
  1. Create graph object.
    2. +
  2. Create graph object. +
  3. 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.
      • +
    • 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.
      • +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.
      • -
    4. +inspect it and add all referecned classes to the graph as well. + + +
  4. Graphs easilly get very big and complex so optionally we filter important code using classname wildcards patterns based blacklist -and/or whitelist.
    5. +and/or whitelist. +
  5. Optionally we can tune some rendering parameters like:
    • Possibility to remove orphaned classes (classes with no -references) from the graph.
      • +references) from the graph. +
    • Specify target directory for generated visualization -files. (Default is user desktop directory)
      • -
    • Keep intermediate GraphViz dot file for later inspection.
      • -
    6. -
  6. Render graph.
    7. +files. (Default is user desktop directory) + +
  7. Keep intermediate GraphViz dot file for later inspection. +
    8. + + +
  8. Render graph. +
-
-

3.1 example 1: individually picked objects

-
+
+

4.2.1 example 1: individually picked objects

+

This example demonstrates generating of class graph from hand picked classes and visualizing GraphViz itself. @@ -310,22 +474,24 @@ classes and visualizing GraphViz itself.

-
// Create graph
-final ClassGraph graph = new ClassGraph();
+
+// 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 random object to the graph. GraphViz will detect Class from
-// the object.
-graph.add(graph);
+// Also add some random class to the graph.
+graph.add(Utils.class);
 
-// Also add some random class to the graph.
-graph.add(Utils.class);
+// Keep intermediary GraphViz DOT file for reference.
+graph.setKeepDotFile(true);
 
-// 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
-graph.generateGraph("JavaInspect");
@@ -334,8 +500,8 @@ Note: if desired, more compact version of the above:

-
new ClassGraph().add(randomObject, RandomClass.class)
-                .setKeepDotFile(true).generateGraph("JavaInspect");
+
new ClassGraph().add(randomObject, RandomClass.class)
+                .setKeepDotFile(true).generateGraph("JavaInspect");
@@ -344,72 +510,76 @@ Note: if desired, more compact version of the above: Result:

-
-

3.2 example 2: scan java code, apply filters

-
+
+

4.2.2 example 2: scan java code, apply filters

+
-
// Create graph
-final ClassGraph graph = new ClassGraph();
+
// 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(".");
+// 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.*");
+// 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");

Result:

-
-

3.3 example 3: GraphViz embedded in another project

-
+
+

4.2.3 example 3: GraphViz embedded in another project

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

4 Embedding JavaInspect in your Maven project

-
+
+

4.2.4 Embedding JavaInspect in your Maven project

+

Declare JavaInspect as dependency:

-
<dependencies>
+
<dependencies>
     ...
-    <dependency>
-        <groupId>eu.svjatoslav</groupId>
-        <artifactId>javainspect</artifactId>
-        <version>1.5</version>
-    </dependency>
+    <dependency>
+        <groupId>eu.svjatoslav</groupId>
+        <artifactId>javainspect</artifactId>
+        <version>1.6</version>
+    </dependency>
     ...
-</dependencies>
+</dependencies>
@@ -419,22 +589,24 @@ Add Maven repository to retrieve artifact from:

-
<repositories>
+
<repositories>
     ...
-    <repository>
-        <id>svjatoslav.eu</id>
-        <name>Svjatoslav repository</name>
-        <url>http://www2.svjatoslav.eu/maven/</url>
-    </repository>
+    <repository>
+        <id>svjatoslav.eu</id>
+        <name>Svjatoslav repository</name>
+        <url>http://www2.svjatoslav.eu/maven/</url>
+    </repository>
     ...
-</repositories>
+</repositories>
+
+
-
-

5 Requirements

+
+

5 Requirements

GraphViz - shall be installed on the computer. @@ -450,35 +622,152 @@ On Ubuntu/Debian use:

-
-

6 TO DO

+
+

6 TO DO

+

+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: +

+ +
    +
  • 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: Orphaned class removal does not work always. There are many +bugs and corner cases to find and fix still. +
    • + +
  • BUG: Code is not very readable. Document and refactor for better +maintainability. +
    • + +
  • FEATURE: Create installable DEB package. +
      +
    • Submit it to some Debian developer for integration or become +Debian package maintainer. +
      • +
    +
    • + +
  • FEATURE: Make it modular. That is: central part, an application +model could be standalone and serializable. + +
      +
    • There could be multiple ways to acquire model: +
        +
      • By introspecting application via Java reflections (current mode +of operation). +
        • +
      • By parsing java source. (unfinished) +
        • +
      +
      • + +
    • There could be ways to manipulate model: +
        +
      • Store/load/compare. +
        • +
      • Trim uninteresting parts. +
        • +
      • Highlight important parts. +
        • +
      +
      • + +
    • There could be multiple ways to render model:
        -
      • 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
        • +
      • PNG/SVG (currently implemented) +
        • +
      • PlantUML (TODO) +
        • +
      • Interactive 3D visualization (TODO) +
        • +
      +
      • +
    +
    • + +
  • FEATURE: Replace internal java parser in package +eu.svjatoslav.inspector.java.methods with: https://javaparser.org/ +
    • + +
  • FEATURE: Integarte with PlantUML. +
    • + +
  • FEATURE: Add dark theme for generated graphs. +
    • + +
  • FEATURE: Sort Class fields by alphabet. +
    • + +
  • FEATURE: Visualize also concrete field values so it could be used as +ultra cool runtime logging/debugging 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 inspect graphs in 3D using Sixth 3D engine. +
    • + +
  • FEATURE: Possibility to select classes/fields/values to be +visualized in some graph query language. For greater flexibility in +comparison to currently supported glob syntax. +
    • + +
  • FEATURE: Add option to control JavaInspect via JSON or XML config +file. For example different graphs for given project could be +defined once in plain text config, possibly with the aid of some +interactive utility. Then defined graphs could be updated as part of +project build or release process. +
    • + +
  • FEATURE: Configurable maven plugin to generate graphs as part of the +project build/release process. +
+
+
+