X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.html;h=a9ae900ef7235a1a192e33339e6a919f85d70f14;hb=b5ce3bd895a6e6c2253e070cfce197a244c78c4c;hp=4c426bfacab52fe8f2691b2112cfb65eb0777002;hpb=92e7df28bd9624ce5d35fac41e7f06f7d23d9217;p=javainspect.git diff --git a/doc/index.html b/doc/index.html index 4c426bf..a9ae900 100644 --- a/doc/index.html +++ b/doc/index.html @@ -1,164 +1,202 @@ - - - + + JavaInspect - Utility to visualize java software - - - - + + + + + + + +" + - -
-

JavaInspect - Utility to visualize java software

-
-

Table of Contents

-
- -
-
-
+
+

JavaInspect - Utility to visualize java software

+
+ + +
  • other applications hosted at svjatoslav.eu
    • @@ -192,42 +240,31 @@ 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. +JavaInspect is a Java library/commandline utility that primarily uses +Java reflection to discover and visualize any part of Java program.

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

    - -

    -To get JavaInspect into same classpath with your projecs I so far came -up with 2 solutions: +scripting support, direct Maven or Ant integration. See usage to learn +how to instuct Javainspect what to do.

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

    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. +bitmap graph in PNG or SVG format. +

    + +

    +By default on your Desktop directory when operated in library mode or +current working directory when operated as standalone commandline +application.

    -Note: GraphViz is developed and tested so far only on GNU Linux. +Note: GraphViz is developed and tested so far only on GNU/Linux.

    @@ -239,35 +276,116 @@ Note: GraphViz is developed and tested so far only on GNU Linux.
  • A very simple example: -
    -

    example.resized.png +

    +

    example.resized.png

    -
    +

    Graph legend:

    -
    -

    legend.png +

    +

    legend.png

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

    3 Usage

    +

    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 +JavaInspect can be controlled in 2 different ways: +

    + +
    + +
    +

    3.1 usage as commandline utility

    +
    +

    +To enable commandline support, (study and) execute script: +

    +
    +commandline launcher/install
+
    + +

    +Warning: It was tested only on Debian Stretch linux. +

    + +

    +Available commandline arguments: +

    +

    +-j (existing files)…
    +    JAR file(s) to render.
    +
    +-n (mandatory, string)
    +    Graph name.
    +
    +–debug
    +    Show debug info.
    +
    +-k
    +    Keep dot file.
    +
    +-h
    +    Hide orphaned classes.
    +
    +-w (one to many strings)…
    +    Whitelist glob(s).
    +
    +-b (one to many strings)…
    +    Blacklist glob(s).
    +
    +-d (existingdirectory)
    +    Target directory. Default is current directory.
    +
    +-t (options: png, svg)
    +    Target image type. Default is: svg.
    +

    +
    +
    +
    +

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

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

    @@ -314,9 +432,9 @@ files. (Default is user desktop directory)
    -
    -

    3.1 example 1: individually picked objects

    -
    +
    +

    3.2.1 example 1: individually picked objects

    +

    This example demonstrates generating of class graph from hand picked classes and visualizing GraphViz itself. @@ -366,9 +484,9 @@ Result:

    -
    -

    3.2 example 2: scan java code, apply filters

    -
    +
    +

    3.2.2 example 2: scan java code, apply filters

    +
    // Create graph
@@ -399,22 +517,21 @@ Result:
    -
    -

    3.3 example 3: GraphViz embedded in another project

    -
    +
    +

    3.2.3 example 3: GraphViz embedded in another project

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

    4 Embedding JavaInspect in your Maven project

    -
    +
    +

    3.2.4 Embedding JavaInspect in your Maven project

    +

    Declare JavaInspect as dependency:

    @@ -425,7 +542,7 @@ Declare JavaInspect as dependency: <dependency> <groupId>eu.svjatoslav</groupId> <artifactId>javainspect</artifactId> - <version>1.5-SNAPSHOT</version> + <version>1.6</version> </dependency> ... </dependencies> @@ -451,10 +568,12 @@ Add Maven repository to retrieve artifact from:
    +
    +
    -
    -

    5 Requirements

    -
    +
    +

    4 Requirements

    +

    GraphViz - shall be installed on the computer.

    @@ -469,47 +588,147 @@ On Ubuntu/Debian use:
    -
    -

    6 TODO

    -
    +
    +

    5 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.
      • -
    • FEATURE: add dark theme + +
    • 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: sort Class fields by alphabet +
      +
      • + +
    • 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).
          • -
        • FEATURE: visualize also concrete field values so it could be used as -ultra cool runtime logging framework +
        • By parsing java source. (unfinished)
          • -
        • FEATURE: possibility to visualize structure and data from JVM -snapshot +
        • -
      • FEATURE: possibility to attach to remote process to visualize + +
      • There could be ways to manipulate model: +
          +
        • Store/load/compare. +
          • +
        • Trim uninteresting parts. +
          • +
        • Highlight important parts. +
          • +
        +
        • + +
      • There could be multiple ways to render model: +
          +
        • 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 attach to JVM using JVM agent. +
      • + +
    • FEATURE: Possibility to inspect graphs in 3D using Sixth 3D engine.
      • -
    • FEATURE: possibility to script javainspect behavior + +
    • 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: possibility to select classes/fields/values to be -visualized in SQL like 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 + +
    • FEATURE: Configurable maven plugin to generate graphs as part of the +project build/release process.
    +
    +
    +