Running GSD

Running GSD currently requires Java 1.5.

Unzip gsd-X.X.X.zip and run with the following command:

java -jar gsd.jar [-(VvshmfoSb)] [-t <threshold>] <classes dir/jar> <output file> [<package>] -V - Print version and exit -v - Enable verbose mode -s - Hide singletons -h - Hide hingletons -m - Hide mingletons -f - Hide fingletons -o - Hide others -S - Print statistics upon completion -b - Add stats banner to the graph -t <val> - Threshold (minimum edges required to draw a node)

The most important options here are probably s, h, m and f, which when included prevent the program from finding certain types of _ingletons.

The parameter is the directory or jar which contains the classes you wish to analyze. The should be a .graphml file to allow your graph viewer to recognize the format. The

<package>

parameter may be included to limit the analyzed classes to a certain package and can be either one of two formats: org/apache/commons or org.apache.commons.

Example:

java -jar gsd.jar -mfbS foo.jar foo.graphml

• Charts Singletons and Hingletons (but not Fingetons and Mingletons) for foo.jar, with a stats printout on completion, and a banner in the chart.

Running GSD

Running GSD currently requires Java 1.5 or above.

Unzip gsd-X.X.X.zip and run with the following command:

Viewing the Graph

GraphML

Once you have a GraphML file, you'll need yEd to view it (we use yWorks to specify node color and shape, which can be read by yEd). yEd is a graph viewer and editor which can handle large graphs and provide custom layouts quickly, and can be found here. Since the GraphML files produced by this program don't define the size of nodes or the overall layout, you'll have to do a few things to make it readable.

First, you need to resize the nodes (Tools -> Fit Node to Label).

Then apply some type of layout; we've found smart organic to be particularly useful (Layout -> Organic -> Smart), but circular and hierarchical can be very effective depending on your graph.

Understanding the Graph

Once you have a graph open and have applied a layout, you'll see a collection of colorful nodes and arrows. If you're running this on a small codebase or one with little use of global state, hopefully you'll see only a few nodes. If you see a large tangle of lines and colors, don't worry, yEd makes it easy to work with.

There are six different types of nodes:

| Color | Type | Brief Description | |:------|:-----|:------------------| | Red | Singleton | A class for which there should only be one instance in the entire system at any given time. This program detects singletons which enforce their own singularity, which means they keep one static instance of themselves and pass it around through a static getter method. | | Orange | Hingleton | Derived from “helper singleton,” a class which turns another class into a singleton by enforcing that class's singularity. | | Yellow | Mingleton | Derived from “method singleton” a class which has any static method that returns some state without taking any parameters. | | Green | Fingleton | Derived from “field singleton,” a class which contains a public static field. | | Light Blue (Ellipse) | Other | Any class which is directly dependent on a Singleton/Hingleton/Mingleton/Fingleton. | | Dark Blue | - | Displays statistics about the current codebase. Is only drawn if the banner option (-b) is passed as a command line argument at runtime. |

Click on the Types for more detailed descriptions

Each node contains two lines of text; the first line is the name of the class that the node represents, and the second line is the package that class is in (this saves horizontal space). If the

<package>

argument was passed at runtime, this prefix will be omitted from the package name (again, to save space). Note that hingleton (orange) nodes will have an extra two lines surround by parens, which are the name and package of the class that is hingled by the hingleton (see Hingleton for more details).

An arrow is drawn from one node to another if the first class directly uses the global state of the second. In the case of singletons and hingletons, this means that a class calls the getInstance() method of the singleton/ hingleton. For mingletons and fingletons, this means that a class access the non-primitive global state of another class.