X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.html;h=710488f37df85056d07b2f625f84fa4d5303b3d3;hb=18154d6a35b1ddbaec5d7b9d14d04aaa172010c3;hp=f011ad86b9ade1cff8ed7a594eeae98dc03bd26b;hpb=0d0148104343e0c97852e493389268b7ddb99510;p=javainspect.git diff --git a/doc/index.html b/doc/index.html index f011ad8..710488f 100644 --- a/doc/index.html +++ b/doc/index.html @@ -2,7 +2,7 @@ JavaInspect - Utility to visualize java software - + @@ -206,10 +206,10 @@ it under the terms of version 3 of the
  • Svjatoslav Agejenko -
    • +     +
  • Tony Bargnesi + +
    • + + +
  • other applications hosted at svjatoslav.eu
    • @@ -230,38 +240,32 @@ 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 GUI, configuration files, embedded +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.

    @@ -293,19 +297,100 @@ Graph legend: -

  • Example visualization of Sixth 3D project: architecture graphs. +
  • See example produced graphs for Sixth 3D - 3D engine project.
    • -

    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.

    @@ -352,9 +437,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. @@ -404,9 +489,9 @@ Result:

    -
    -

    3.2 example 2: scan java code, apply filters

    -
    +
    +

    3.2.2 example 2: scan java code, apply filters

    +
    // Create graph
@@ -437,9 +522,9 @@ 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. @@ -448,11 +533,10 @@ Result:
    -
    -
    -

    4 Embedding JavaInspect in your Maven project

    -
    +
    +

    3.2.4 Embedding JavaInspect in your Maven project

    +

    Declare JavaInspect as dependency:

    @@ -489,10 +573,12 @@ Add Maven repository to retrieve artifact from:
    +
    +
    -
    -

    5 Requirements

    -
    +
    +

    4 Requirements

    +

    GraphViz - shall be installed on the computer.

    @@ -507,38 +593,121 @@ On Ubuntu/Debian use:
    -
    -

    6 TO DO

    -
    +
    +

    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. +
      • + +
    • 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. +
        -
      • 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. +
      • 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: +
          +
        • PNG/SVG (currently implemented) +
          • +
        • PlantUML (TODO) +
          • +
        • Interactive 3D visualization (TODO) +
          • +
        • -
      • FEATURE: integarte with PlantUML. +
      • -
    • FEATURE: add dark theme + +
    • FEATURE: Replace internal java parser in package +eu.svjatoslav.inspector.java.methods with: https://javaparser.org/
      • -
    • FEATURE: sort Class fields by alphabet + +
    • FEATURE: Integarte with PlantUML.
      • -
    • FEATURE: visualize also concrete field values so it could be used as -ultra cool runtime logging framework + +
    • FEATURE: Add dark theme for generated graphs.
      • -
    • FEATURE: possibility to visualize structure and data from JVM -snapshot + +
    • 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 attach to remote process to visualize + +
    • 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.
    @@ -550,21 +719,19 @@ project build/release process
  • 2. Example graphs
  • 3. Usage
    • -
  • 4. Embedding JavaInspect in your Maven project
    • -
  • 5. Requirements
    • -
  • 6. TO DO
    • +
  • 4. Requirements
    • +
  • 5. TO DO