X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.org;h=be7db9b352f3fbb27de2a93a50284d56c36ef2c9;hb=4b0c5e8b5b50bb1b168308ccb9b06119c2326c3a;hp=4293347a099d84abaf18d7c0e26eec9137b11265;hpb=02756977e668ccfd20059b920bb9259f83847a4f;p=javainspect.git

diff --git a/doc/index.org b/doc/index.org
index 4293347..be7db9b 100644
--- a/doc/index.org
+++ b/doc/index.org
@@ -7,16 +7,20 @@
   it under the terms of version 3 of the [[https://www.gnu.org/licenses/lgpl.html][GNU Lesser General Public
   License]] or later as published by the Free Software Foundation.
 
-- Program author:
+- Program authors:
   - Svjatoslav Agejenko
-  - Homepage: http://svjatoslav.eu
-  - Email: mailto://svjatoslav@svjatoslav.eu
+    - Homepage: http://svjatoslav.eu
+    - Email: mailto://svjatoslav@svjatoslav.eu
+
+  - Tony Bargnesi
+    - GitHub fork for the project:
+      https://github.com/abargnesi/javainspect
 
 - [[http://www.svjatoslav.eu/programs.jsp][other applications hosted at svjatoslav.eu]]
 
 * (document settings) :noexport:
 ** use dark style for TWBS-HTML exporter
-#+HTML_HEAD: <link href="https://bootswatch.com/darkly/bootstrap.min.css" rel="stylesheet">
+#+HTML_HEAD: <link href="https://bootswatch.com/4/darkly/bootstrap.min.css" rel="stylesheet">
 #+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
 #+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.1/js/bootstrap.min.js"></script>"
 #+HTML_HEAD: <style type="text/css">
@@ -28,30 +32,28 @@
 Goal: simplify/speed up understanding the computer program code by
 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.
+[[http://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[http://www3.svjatoslav.eu/projects/sixth-3d/][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 [[id:acf1896a-74b4-4914-acf6-a77075e07f25][standalone commandline utility]] as well as
+[[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][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:
-
-1. Add JavaInspect library in your project as a dependency.
-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.
+JavaInspect currently has no GUI, configuration files, embedded
+scripting support, direct Maven or Ant integration. See [[id:2ad2889e-6c95-4662-b3f4-2c341fc74522][usage]] to learn
+how to instuct Javainspect what to do.
 
 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.
+Notes:
++ JavaInspect is developed and tested so far only on GNU/Linux.
++ See: [[https://github.com/pahen/madge][Madge - similar tool for JavaScript]]
 
 * Example graphs
 + A very simple example:
@@ -62,12 +64,73 @@ Note: GraphViz is developed and tested so far only on GNU/Linux.
 
     file:legend.png
 
-+ Example visualization of [[http://www2.svjatoslav.eu/gitbrowse/sixth-3d/doc/][Sixth 3D]] project: [[http://www2.svjatoslav.eu/gitbrowse/sixth-3d/doc/codeGraph/][architecture graphs]].
++ [[http://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[http://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]].
 
 * 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
+  :PROPERTIES:
+  :ID:       2ad2889e-6c95-4662-b3f4-2c341fc74522
+  :END:
+JavaInspect can be controlled in 2 different ways:
++ [[id:acf1896a-74b4-4914-acf6-a77075e07f25][as standalone commandline utility]]
++ [[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][as embedded Java library via Java API]]
+
+** usage as commandline utility
+   :PROPERTIES:
+   :ID:       acf1896a-74b4-4914-acf6-a77075e07f25
+   :END:
+To enable commandline support, (study and) execute script:
+: commandline launcher/install
+
+Warning: It was tested only on Debian Stretch linux.
+
+Available commandline arguments:
+#+BEGIN_VERSE
+-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.
+#+END_VERSE
+** usage via Java API
+   :PROPERTIES:
+   :ID:       bbeeffc8-3767-440d-8d93-ec9124dd60ee
+   :END:
+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. 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.
+
+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.
 
@@ -93,7 +156,7 @@ Control code in general does the following:
 5. Render graph.
 
 
-** example 1: individually picked objects
+*** example 1: individually picked objects
 This example demonstrates generating of class graph from hand picked
 classes and visualizing GraphViz itself.
 
@@ -129,7 +192,7 @@ Result:
     - Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]]
     - Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]]
 
-** example 2: scan java code, apply filters
+*** example 2: scan java code, apply filters
 #+BEGIN_SRC java
 // Create graph
 final ClassGraph graph = new ClassGraph();
@@ -151,11 +214,11 @@ graph.generateGraph("JavaInspect full project");
 Result:
     - Generated PNG image: [[file:JavaInspect%20full%20project.png][JavaInspect full project.png]]
 
-** example 3: GraphViz embedded in another project
+*** example 3: GraphViz embedded in another project
 1. Download project Sixth [[http://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][code snapshot]].
 2. Inspect and run *DataGraph.java*.
 
-* Embedding JavaInspect in your Maven project
+*** Embedding JavaInspect in your Maven project
 
 Declare JavaInspect as dependency:
 #+BEGIN_SRC xml
@@ -192,21 +255,74 @@ On Ubuntu/Debian use:
 sudo apt-get install graphviz
 #+END_SRC
 * TO DO
-- 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: integarte with [[http://plantuml.com/class-diagram][PlantUML]].
-- 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
+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:
+    - 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 [[http://plantuml.com/class-diagram][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 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
+
+- FEATURE: Possibility to attach to JVM using JVM agent.
+
+- FEATURE: Possibility to inspect graphs in 3D using [[http://www2.svjatoslav.eu/gitbrowse/sixth-3d/doc/index.html][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.