#!/bin/bash
-cd "${0%/*}"; if [ "$1" != "T" ]; then gnome-terminal -- "$0" T; exit; fi;
+cd "${0%/*}"; if [ "$1" != "T" ]; then gnome-terminal -e "'$0' T"; exit; fi;
cd ..
}
build_visualization_graphs() {
- echo "🎨 Generating class visualization graphs..."
- echo "======================================="
-
rm -rf doc/graphs/
mkdir -p doc/graphs/
- # JavaInspect analyzing itself - meta visualization!
- javainspect -j target/javainspect.jar -d doc/graphs/ -n "All classes" -t png
- javainspect -j target/javainspect.jar -d doc/graphs/ -n "Inspector" -t png -w "eu.svjatoslav.inspector.*"
- javainspect -j target/javainspect.jar -d doc/graphs/ -n "Java parser" -t png -w "eu.svjatoslav.inspector.java.*"
+ # Generate self-visualization of JavaInspect
+ javainspect -j target/javainspect.jar -d doc/graphs/ -n "All classes" -t png -w "eu.svjatoslav.inspector.java.*" -ho
- # Generate index page for graphs
meviz index -w doc/graphs/ -t "JavaInspect classes"
-
- echo "✓ Visualization graphs generated"
- echo ""
}
# Build project jar file and JavaDocs
-echo "🔨 Building project..."
-echo "======================================="
mvn clean package
-if [ $? -ne 0 ]; then
- echo "✗ Maven build failed!"
- echo ""
- echo "Press ENTER to close this window."
- read
- exit 1
-fi
-
-echo "✓ Maven build completed"
-echo ""
-
# Put generated JavaDoc HTML files to documentation directory
-echo "📚 Copying JavaDocs..."
-echo "======================================="
rm -rf doc/apidocs/
cp -r target/apidocs/ doc/
-echo "✓ JavaDocs copied to doc/apidocs/"
-echo ""
-
# Publish Emacs org-mode files into HTML format
export_org_files_to_html
# Generate nice looking code visualization diagrams
build_visualization_graphs
+
## Upload assembled documentation to server
echo "📤 Uploading to server..."
-echo "======================================="
rsync -avz --delete -e 'ssh -p 10006' doc/ \
n0@www3.svjatoslav.eu:/mnt/big/projects/javainspect/
echo ""
echo "Press ENTER to close this window."
-read
\ No newline at end of file
+read
--- /dev/null
+:PROPERTIES:
+:CUSTOM_ID: usage-from-cli
+:END:
+#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme
+#+TITLE: JavaInspect - usage from commandline
+#+LANGUAGE: en
+#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry}
+#+LATEX_HEADER: \usepackage{parskip}
+#+LATEX_HEADER: \usepackage[none]{hyphenat}
+
+#+OPTIONS: H:20 num:20
+#+OPTIONS: author:nil
+
+[[file:../index.org][Back to main documentation]]
+
+* Commandline arguments
+:PROPERTIES:
+:CUSTOM_ID: available-commandline-arguments
+:END:
+
+
+- -j (existing files)... :: JAR file(s) to render.
+
+- -c (existing directories)... :: Classpath directories
+
+- -n (string) :: Graph name. (default: "graph")
+
+- --debug :: Show debug info.
+
+- -h, --help :: Show commandline usage help.
+
+- -k :: Keep dot file.
+
+- -ho ::
+ Hide orphaned classes.
+
+- -w (one to many strings)... :: Whitelist glob(s).
+
+- -b (one to many strings)... :: Blacklist glob(s).
+
+- -r (one to many strings)... :: root class(es).
+
+- -d (existing directory) :: Target directory. Default is current directory.
+
+- -t (options: png, svg) :: Target image type. Default is: svg.
+
+* Specifying classes to render
+:PROPERTIES:
+:CUSTOM_ID: specifying-classes-to-render
+:END:
+
+A typical Java application has immense complexity. Beyond code written
+by the project's developers, there are typically many frameworks,
+libraries, and the Java standard library.
+
+Since JavaInspect uses reflection, it cannot easily distinguish between
+these sources. Usually you want to visualize only the code developed
+for your project, excluding frameworks like Spring. If you visualize
+all classes reachable from your project, the graph becomes huge and
+incomprehensible.
+
+JavaInspect can analyze compiled Java classes in two modes:
+1. Provide JAR files using the *-j* option.
+2. Provide filesystem directories as classpath roots using the *-c* option.
+
+JavaInspect uses the following algorithm to add classes to the graph:
+
+- All classes found in JAR files are added to the graph by default.
+- Classes found in filesystem directories are not added by default
+ unless explicitly referenced. (TODO: for consistency, these should
+ also be added by default)
+- If a whitelist is specified (*-w* option), classes not matching the
+ whitelist patterns are removed from the graph.
+- If a blacklist is specified (*-b* option), classes matching the
+ blacklist patterns are removed from the graph.
+- Root classes can be specified using the *-r* option. JavaInspect
+ recursively discovers all classes referenced by root classes and
+ adds them to the graph.
+
+* Examples
+:PROPERTIES:
+:CUSTOM_ID: examples
+:END:
+
+Visualize a Java JAR file with all classes, hiding orphaned classes:
+
+#+begin_src sh
+ javainspect \
+ -j target/sixth-3d-*-SNAPSHOT.jar \
+ -d doc/graphs/ \
+ -n "All classes" \
+ -t png -ho
+#+end_src
+
+Visualize a Java JAR file with a whitelist filter, hiding orphaned classes:
+
+#+begin_src sh
+ javainspect \
+ -j target/sixth-3d-*-SNAPSHOT.jar \
+ -d doc/graphs/ \
+ -n "GUI" \
+ -t png \
+ -w "eu.svjatoslav.sixth.e3d.gui.*" \
+ -ho
+#+end_src
--- /dev/null
+:PROPERTIES:
+:CUSTOM_ID: usage-via-java-api
+:END:
+#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme
+#+TITLE: JavaInspect - Usage via Java API
+#+LANGUAGE: en
+#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry}
+#+LATEX_HEADER: \usepackage{parskip}
+#+LATEX_HEADER: \usepackage[none]{hyphenat}
+
+#+OPTIONS: H:20 num:20
+#+OPTIONS: author:nil
+
+[[file:../index.org][Back to main documentation]]
+
+* Overview
+:PROPERTIES:
+:CUSTOM_ID: overview
+:END:
+Classes to be visualized must be available in the classpath.
+
+To include JavaInspect in the same classpath as your projects, there are
+two approaches:
+
+1. Add JavaInspect as a dependency in your project.
+
+2. Create a new Java project specifically for visualizing other
+ projects, and include both JavaInspect and your project's binary
+ artifacts (JARs) in the classpath. Binary JARs (without source code)
+ are sufficient since JavaInspect operates via reflection.
+
+Write simple control/configuration code for each project. I typically
+place this code in JUnit test directories since it doesn't need to be
+compiled into the final product or artifact.
+
+The control code generally does the following:
+1. Create a graph object.
+2. Java reflection/classloaders do not provide a mechanism to discover
+ all classes under a package. Therefore, manually add at least some
+ classes to the graph. For each class added, JavaInspect recursively
+ inspects it and adds all referenced classes.
+3. Graphs can easily become very large and complex, so optionally filter
+ important code using classname [[https://en.wikipedia.org/wiki/Glob_(programming)][glob]] pattern blacklists and/or
+ whitelists.
+4. Optionally tune rendering parameters:
+ + Remove orphaned classes (classes with no references) from the graph.
+ + Specify target directory for generated files (default: current directory).
+ + Keep intermediate GraphViz DOT file for later inspection.
+5. Render the graph.
+
+* Examples
+** Example 1: Hand-picked objects
+:PROPERTIES:
+:CUSTOM_ID: example-1-individually-picked-objects
+:END:
+This example generates a class graph from hand-picked classes, visualizing
+JavaInspect itself.
+
+#+BEGIN_SRC java
+
+// Create graph
+final ClassGraph graph = new ClassGraph();
+
+// Add an object to the graph. JavaInspect detects the class from the object.
+graph.add(graph);
+
+// Also add a class directly.
+graph.add(Utils.class);
+
+// Keep the intermediate GraphViz DOT file for reference.
+graph.setKeepDotFile(true);
+
+// Generate an image named "JavaInspect.png" in the current directory
+graph.generateGraph("JavaInspect");
+
+#+END_SRC
+
+Compact version:
+#+BEGIN_SRC java
+new ClassGraph().add(randomObject, RandomClass.class)
+ .setKeepDotFile(true).generateGraph("JavaInspect");
+#+END_SRC
+
+Result:
+- Generated DOT file: [[file:../JavaInspect.dot][JavaInspect.dot]]
+- Generated PNG image: [[file:../JavaInspect.png][JavaInspect.png]]
+
+** Example 2: Embedded in another project
+:PROPERTIES:
+:CUSTOM_ID: example-2-graphviz-embedded-in-another-project
+:END:
+
+1. Download a [[https://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][Sixth project snapshot]].
+2. Inspect and run *DataGraph.java*.
+
+* Embedding JavaInspect in your Maven project
+:PROPERTIES:
+:CUSTOM_ID: embedding-javainspect-in-your-maven-project
+:END:
+
+Declare JavaInspect as dependency:
+#+BEGIN_SRC xml
+<dependencies>
+ ...
+ <dependency>
+ <groupId>eu.svjatoslav</groupId>
+ <artifactId>javainspect</artifactId>
+ <version>1.8</version>
+ </dependency>
+ ...
+</dependencies>
+#+END_SRC
+
+
+Add Maven repository to retrieve artifact from:
+#+BEGIN_SRC xml
+<repositories>
+ ...
+ <repository>
+ <id>svjatoslav.eu</id>
+ <name>Svjatoslav repository</name>
+ <url>https://www3.svjatoslav.eu/maven/</url>
+ </repository>
+ ...
+</repositories>
+#+END_SRC
:CUSTOM_ID: overview
:END:
-*JavaInspect* utility simplifies understanding the computer program
-code by automatically visualizing its structure.
-
-[[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[https://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]].
-
-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.
-
-JavaInspect currently has no graphical user interface, configuration
-files, embedded scripting support, direct Maven, Gradle 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 [[https://graphviz.org/][GraphViz]] to generate
-bitmap graph in PNG or SVG format.
-
-Notes:
-+ JavaInspect is developed and tested so far only on GNU/Linux.
+*JavaInspect* simplifies understanding source code by automatically
+visualizing program structure. See example graphs:
+- [[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][Diagrams]] for [[https://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D engine project]].
++ [[file:graphs/][Diagrams for JavaInspect project itself]].
*A very simple example:*
-
[[file:example.png][file:example-thumbnail.png]]
Graph legend:
file:legend.png
+JavaInspect can be used as a [[file:Usage from CLI/][standalone commandline utility]] or as a
+[[file:Usage via Java API/][Java library]]. It uses Java's built-in reflection to discover and
+visualize any part of a Java program.
-+ [[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[https://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]].
+See [[#usage][usage]] to learn how to use JavaInspect.
+
+After discovering application structure and optionally filtering out
+unimportant parts, JavaInspect produces a GraphViz DOT file describing
+the data to visualize. It then launches [[https://graphviz.org/][GraphViz]] to generate the
+graph image in PNG or SVG format.
** See also
:PROPERTIES:
:PROPERTIES:
:CUSTOM_ID: installation
:END:
-[[http://www.graphviz.org/][GraphViz]] - shall be installed on the computer.
+[[http://www.graphviz.org/][GraphViz]] must be installed on your system.
-On Ubuntu/Debian GraphViz can be installed using:
+On Ubuntu/Debian, install GraphViz using:
#+BEGIN_SRC sh
sudo apt-get install graphviz
#+END_SRC
To use JavaInspect via Java API, no further installation is
needed. JavaInspect will be embedded into your project as dependency.
-This is described in [[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][usage via Java API]]. It will expect GraphViz to be
+This is described in [[file:Usage via Java API/][usage via Java API]]. It will expect GraphViz to be
available in the system.
To use JavaInspect as a commandline tool, JavaInspect source
-repository has to be cloned locally. See: [[id:c47ff9a6-d737-4b73-9393-1c63d2ca1101][Getting the source code]].
+repository has to be cloned locally. See: [[#getting-the-source-code][Getting the source code]].
Then study and execute installation script:
#+begin_src sh
* Usage
:PROPERTIES:
-:ID: 2ad2889e-6c95-4662-b3f4-2c341fc74522
:CUSTOM_ID: usage
:END:
-JavaInspect utility can be used 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 via Java API
-:PROPERTIES:
-:ID: bbeeffc8-3767-440d-8d93-ec9124dd60ee
-:CUSTOM_ID: usage-via-java-api
-: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.
-
-Control code in general does the following:
-1. Create graph object.
-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. For every class added to
- the graph, GraphViz will recursively inspect it and add all
- referecned classes to the graph as well.
-3. Graphs easilly get very big and complex so optionally we filter
- important code using classname [[https://en.wikipedia.org/wiki/Glob_(programming)][glob]] patterns based blacklist and/or
- whitelist.
-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 current directory)
- + Keep intermediate GraphViz dot file for later inspection.
-5. Render graph.
-
-
-*** Example 1: individually picked objects
-:PROPERTIES:
-:CUSTOM_ID: example-1-individually-picked-objects
-:END:
-This example demonstrates generating of class graph from hand picked
-classes and visualizing GraphViz itself.
-
-#+BEGIN_SRC java
-
-// Create graph
-final ClassGraph graph = new ClassGraph();
-
-// 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);
-
-// Keep intermediary GraphViz DOT file for reference.
-graph.setKeepDotFile(true);
-
-// Produce bitmap image titled "JavaInspect.png" to the user Desktop
-// directory
-graph.generateGraph("JavaInspect");
-
-#+END_SRC
-
-Note: if desired, more compact version of the above:
-#+BEGIN_SRC java
-new ClassGraph().add(randomObject, RandomClass.class)
- .setKeepDotFile(true).generateGraph("JavaInspect");
-#+END_SRC
-
-
-Result:
- - Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]]
- - Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]]
-
-*** Example 2: GraphViz embedded in another project
-:PROPERTIES:
-:CUSTOM_ID: example-2-graphviz-embedded-in-another-project
-:END:
-1. Download project Sixth [[https://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
-:PROPERTIES:
-:CUSTOM_ID: embedding-javainspect-in-your-maven-project
-:END:
-
-Declare JavaInspect as dependency:
-#+BEGIN_SRC xml
-<dependencies>
- ...
- <dependency>
- <groupId>eu.svjatoslav</groupId>
- <artifactId>javainspect</artifactId>
- <version>1.7</version>
- </dependency>
- ...
-</dependencies>
-#+END_SRC
-
-
-Add Maven repository to retrieve artifact from:
-#+BEGIN_SRC xml
-<repositories>
- ...
- <repository>
- <id>svjatoslav.eu</id>
- <name>Svjatoslav repository</name>
- <url>https://www3.svjatoslav.eu/maven/</url>
- </repository>
- ...
-</repositories>
-#+END_SRC
+JavaInspect can be used in two ways:
++ [[file:Usage from CLI/][As a standalone commandline utility]]
++ [[file:Usage via Java API/][As a Java library embedded in your project]]
* Source code
:PROPERTIES:
-:ID: c47ff9a6-d737-4b73-9393-1c63d2ca1101
:CUSTOM_ID: getting-the-source-code
:END:
+++ /dev/null
-:PROPERTIES:
-:ID: acf1896a-74b4-4914-acf6-a77075e07f25
-:END:
-#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme
-#+TITLE: JavaInspect - usage from commandline
-#+LANGUAGE: en
-#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry}
-#+LATEX_HEADER: \usepackage{parskip}
-#+LATEX_HEADER: \usepackage[none]{hyphenat}
-
-#+OPTIONS: H:20 num:20
-#+OPTIONS: author:nil
-
-[[file:../index.org][Back to main documentation]]
-
-* Commandline arguments
-:PROPERTIES:
-:CUSTOM_ID: available-commandline-arguments
-:END:
-
-
-- -j (existing files)... :: JAR file(s) to render.
-
-- -c (existing directories)... :: Classpath directories
-
-- -n (string) :: Graph name. (default: "graph")
-
-- --debug :: Show debug info.
-
-- -h, --help :: Show commandline usage help.
-
-- -k :: Keep dot file.
-
-- -ho ::
- Hide orphaned classes.
-
-- -w (one to many strings)... :: Whitelist glob(s).
-
-- -b (one to many strings)... :: Blacklist glob(s).
-
-- -r (one to many strings)... :: root class(es).
-
-- -d (existing directory) :: Target directory. Default is current directory.
-
-- -t (options: png, svg) :: Target image type. Default is: svg.
-
-* Specifying classes to render
-:PROPERTIES:
-:CUSTOM_ID: specifying-classes-to-render
-:END:
-
-Normal Java application has immense complexity. In addition to code
-that was directly written by particular project developers, lots of
-functionality is typically added as frameworks or libraries to the
-project. In addition there is significant Java standard library.
-
-Because JavaInspect uses reflection, it does not easily distinguish
-between those. In normal situation you would rather want to visualize
-only code that was developed specifically for your project and leave
-frameworks like Spring etc. out. If you visualize all classes that are
-possibly reachable from you project, you will easily get huge and
-incomprehensible graph.
-
-JavaInspect can digest compiled Java classes in 2 modes:
-1. Provide list of Jar files. Use *-j* option.
-2. Provide list of filesystem directories that can be used as
- classpath root. Use *-c* option.
-
-Currently JavaInspect uses following algorithm to add classes to
-rendered graph:
-
-- All classes that were found in Jar files are added to graph by default.
-- None of the classes that were found in filesystem directories are
- added to the graph by default (unless explicitly referenced). (TODO:
- for consistency it would be better to add them too by default)
-- If whitelist is specified (*-w* option) everything that is not
- matched by whitelist pattern(s) will be removed from the graph.
-- If blacklist is specified (*-b* option) everything that is matched
- by blacklist pattern(s) will be removed from the graph.
-- Root classes can be specified using *-r* option. Root classes will
- be added to the graph. JavaInspect will then try to recursively
- discover all classes that were referenced by root class and add
- those also to the graph.
-
-* Examples
-:PROPERTIES:
-:CUSTOM_ID: examples
-:END:
-
-Visualize java Jar file. All classes. Hide orphaned classes:
-
-#+begin_src sh
- javainspect \
- -j target/sixth-3d-*-SNAPSHOT.jar \
- -d doc/graphs/ \
- -n "all classes" \
- -t png -ho
-#+end_src
-
-
-Visualize java Jar file. All classes. Hide orphaned classes. Apply
-whitelist:
-
-#+begin_src sh
- javainspect \
- -j target/sixth-3d-*-SNAPSHOT.jar \
- -d doc/graphs/ \
- -n "GUI" \
- -t png \
- -w "eu.svjatoslav.sixth.e3d.gui.*" \
- -ho
-#+end_src
projects / javainspect.git / commitdiff