|
1. What is Spoiklin Soice?
2. Functions in a class.
3. Classes in a package.
4. Packages in a system.
5. Transitive Dependencies.
6. Sequence-diagrams.
7. Automatically generating your image files.
7.1. The basics.
7.2. Package-level diagrams.
7.3. Functions in a class.
7.4. Specific function-transitive dependencies.
7.5. Class-diagrams.
7.6. Diagram size.
7.7. Loading multiple directories of classes.
7.8. Loading a specific configuration file.
7.9. Changing the analysis view.
7.10. Sequence-diagrams.
7.10. Saving statistics overview.
1. What is Spoiklin Soice?
Spoiklin Soice is a free tool (you can get it from the Downloads section above) that helps you document your Java source code graphically. This can be a great help when performing code reviews, investigating legacy code or just improving in-house WIKI code descriptions.
It loads the .class files compiled from your source code and draws spoiklin diagrams like this:
Figure 1: A small but entire system on function-level.
WFT, right?
But let's walk through it. Figure 1 happens to be show function-level structure of a system, that is, it's a spoiklin diagram of all the functions, and dependencies between all the functions. And, really, if you're going to look at all the functions in your system, what do you expect?
A spoiklin diagram shows each source code function as a circle and each dependency as a line.
If the line is straight then the dependency is from the function above to the function below. If the line is curved then the dependency is from the function below to the function above. This eliminate the visual clutter of using arrow-heads to show dependency direction.
The circles are coloured according to whatever analysis is currently active. Spoiklin Soice provides several analyzes each showing a different aspect of the system. The default analysis is, "Transitive dependency."
In figure 1, a circle is coloured red proportionate to the amount of transitive dependencies of which it is a member. So we can see some very red functions towards the top-left: these are functions called by or calling many, many other functions. The pink circles take part in fewer transitive dependencies. The (practically) white circles are functions in very few transitive dependencies.
2. Functions in a class.
OK, once you've got over the shock of that, Spoiklin Soice allows you to select any particular class and show only the functions it contains, see figure 2.
Figure 2: Functions in a single class.
Figure 2 shows more clearly how spoiklin diagrams try to have all the dependencies going from above to below but it's not always possible. On the right-hand side you can clearly see a curved line, this is going from the lower function to the upper.
Figure 3 shows the same collection as in figure 2 but with names added.
Figure 3: Named functions in a single class.
You'll note that in figure 3 Spoiklin Soice automatically adds bands to try to highlight functions of similar transitive dependency depth or parentage, though again, this isn't always possible.
So, in figure 3 we see, along the top, many functions with no dependencies coming from them. They call no other functions within the selected class. The start() function, however, calls the manageThread() function, which then calls execute(), prepareSystem(), etc. Admittedly, some of the function names are hard to read as they're quite long and the graphic has been reduced to fit this web page.
That, then, is a spoiklin diagram of function-level structure. With the click of a button Spoiklin Soice will display the class-level structure, see figure 4.
Figure 4: Class-level spoiklin diagram.
3. Classes in a package.
Again, don't be alarmed by the mess. In figure 4, each circle is a class and so it shows all the classes in the system, which is not so helpful for your documentation. Far more useful is viewing all the classes in any particular package, see figure 5.
Figure 5: Classes in a specific package.
Figure 5 shows all the classes in (as it happens) the explore package. Here, for example, ConcreteFileExplorer depends on the DirectoryContents class which in turn depends on the inner-class DirectoryContents$1. Note that DirectoryContents$1 also has a dependency back on DirectoryContents.
4. Packages in a system.
Package-level structure are also just a click away.
Figure 6: Package-diagram of the system.
Where graphics like these most help with documenting source code, however, is not in just showing functions within classes or classes within packages, but entire transitive dependencies of functions as they snake across class boundaries.
Going back to that scary figure 1, if we click on any function Spoiklin Soice will highlight all the dependencies flowing though that function. If we then extract those highlighted functions, we can see a graphic of just the functions in which we are interested.
5. Transitive Dependencies
Figure 7 shows the transitive dependencies related to the creation of various buttons in some GUI functionality that spans from the top of the diagram to the bottom, cutting through many classes (of course, similar dependency chains can be shown on class-level as well).
Figure 7: Some class-spanning transitive dependencies.
6. Sequence-diagrams.
Finally, Spoiklin Soice can show the same information as that of figure 7 but in sequence-diagram form, see figure 8.
Figure 8: Sequence diagram.
Spoiklin Soice is more than a documentation tool. It was actually designed as a vehicle for monitoring adherence to the Tulegatan principles but that's for a later post. (Note, for example, that the process() function of figure 3 is an excellent example of the, "Sunburst," pattern characteristic of the depth principle.)
Do please download Spoiklin Soice for yourself and enjoy a journey through your code as you've never seen it before.
7. Automatically generating your image files.
7.1. The basics.
Loading your system into Spoiklin Soice in normal, graphical mode can provide invaluable insight into your design but often you will want to see an image of the system's package-structure generated every time the code is updated and deployed. Spoiklin Soice provides just such automated image-generation.
To do this, you will need to save a plain-text command-file and pass this command-file to Spoiklin Soice as a command-line argument when the tool starts. Spoiklin Soice will then carry-out each command as it appears in the file.
The most simple command-file you can have is one that loads the system and saves its image.
Let's say the root directory for your compiled Java classes is: C:\Users\sarah\Documents\projects\cake\classes and you wish to save the image-file of the system in directory C:\Users\sarah\Documents\images then the simplest command-file will be:
load_files "C:\Users\sarah\Documents\projects\cake\classes"
save_graphics "C:\Users\sarah\Documents\images\function-level"
(Note that all double-quotes used to specify directory paths are optional unless your directory path contains space characters.)
This will save the image-file in the default graphical format of your system, which is usually a PNG-file, so in this case the image will be saved in function-level.png
If the above two lines are saved in a file called commands.txt in directory C:\Users\sarah\Documents then Spoiklin Soice will automatically generate the image file when started from the command-line as follows:
java -jar spoiklin.jar command_file "C:\Users\sarah\Documents\commands.txt"
(The command_file is the instruction that tells Spoiklin Soice to expect the following command-file.)
Incorporating this into an Ant task, for example, will allow you to automatically generate diagrams each time your system is updated.
Note that, if your system is large, you may want to run the command with extra memory, for example:
java -Xmx1024m -Xms128m -jar spoiklin.jar command_file "C:\Users\sarah\Documents\commands.txt"
When prerparing automatically-generated graphics, it is worthwhile to load a configuration file (see later) with the, "Output logs to standard out," option enabled so that you are notified of any selection or scope failures made.
You can see all the commands available via:
java -jar spoiklin.jar help
7.2. Package-level diagrams.
When Spoiklin Soice starts it processes the lowest level of your program structure: the function-level. So the above command-file will show all the function transitive dependencies in your system, which is not so useful.
If you want instead a package diagram of your system then you must go up a level to class-level and go up a level again to package-level before saving the image, as in:
load_files "C:\Users\sarah\Documents\projects\cake\classes"
level_up
level_up
save_graphics "C:\Users\sarah\Documents\images\package-level"
7.3. Functions in a class.
Let's say you want to save two images: the first of all functions in a particular class and the second of the system package-structure. Then you should set the scope to the appropriate class before saving the first image and going on to level-up to package-level, as in:
load_files "C:\Users\sarah\Documents\projects\cake\classes"
set_scope com.sarah.model.GameFactory
save_graphics "C:\Users\sarah\Documents\images\GameFactory-class"
level_up
level_up
save_graphics "C:\Users\sarah\Documents\images\package-level"
The above will save all the function transitive dependencies within the GameFactory class and the system package-structure.
The scope is automatically reset when the tool levels up, but if you want to reset the scope to all, use:
set_scope all
7.4. Specific function transitive dependencies.
You may want to save all the function transitive dependencies that pass through a particular function as well as the above two images. No problem:
load_files "C:\Users\sarah\Documents\projects\cake\classes"
select com.sarah.controller.Controller.start
extract_highlighted
save_graphics "/home/ed/tmp/Controller-start-trans"
set_scope com.sarah.model.GameFactory
save_graphics "C:\Users\sarah\Documents\images\GameFactory-class"
level_up
level_up
save_graphics "C:\Users\sarah\Documents\images\package-level"
The above will highlight all function transitive dependencies passing through the start() method in the Controller class, extract them to a new screen and save them in an image (as well as saving the two images already described). You can use this select/extract_highlighted combination on any level - function, class or package - to focus on specific targets you want to capture images of.
7.5. Class-diagrams.
If you want all the above and you want to save a class-diagram of the model package, you simply have to ensure to set the scope on the right level, as in:
load_files "C:\Users\sarah\Documents\projects\cake\classes"
select com.sarah.controller.Controller.start
extract_highlighted
save_graphics "/home/ed/tmp/Controller-start-trans"
set_scope com.sarah.model.GameFactory
save_graphics "C:\Users\sarah\Documents\images\GameFactory-class"
level_up
set_scope com.sarah.model
save_graphics "C:\Users\sarah\Documents\images\model-package"
level_up
save_graphics "C:\Users\sarah\Documents\images\package-level"
7.6. Diagram size.
The graphics are saved with a size relative to the screen on which they are captured but this may not be ideal when intended for a corporate wiki with strict size-requirements. To save images of a specific size you can simply set the size in pixels (note this must be done first, before loading any files):
width 600
height 400
load_files "C:\Users\sarah\Documents\projects\cake\classes"
select com.sarah.controller.Controller.start
extract_highlighted
save_graphics "/home/ed/tmp/Controller-start-trans"
set_scope com.sarah.model.GameFactory
save_graphics "C:\Users\sarah\Documents\images\GameFactory-class"
level_up
set_scope com.sarah.model
save_graphics "C:\Users\sarah\Documents\images\model-package"
level_up
save_graphics "C:\Users\sarah\Documents\images\package-level"
The above saves all the images described so far, each 600 pixels wide and 400 pixels high.
7.7. Loading multiple directories of classes.
Let's say your system is enormous and you are interested not in loading it entirely but only in some package sub-trees. You can then use the load_files and add_files combination to load only the relevant sub-packages:
width 600
height 400
load_files "C:\Users\sarah\Documents\projects\cake\classes\com\sarah\controller"
add_files "C:\Users\sarah\Documents\projects\cake\classes\com\sarah\model"
select com.sarah.controller.Controller.start
extract_highlighted
save_graphics "/home/ed/tmp/Controller-start-trans"
set_scope com.sarah.model.GameFactory
save_graphics "C:\Users\sarah\Documents\images\GameFactory-class"
level_up
set_scope com.sarah.model
save_graphics "C:\Users\sarah\Documents\images\model-package"
level_up
save_graphics "C:\Users\sarah\Documents\images\package-level"
7.8. Loading a specific configuration file.
When Spoiklin Soice runs in normal, graphical mode, it automatically saves a configuration file, Spoiklin_Soice.cfg, in the directory from which the Spoiklin Soice jar is launched. In this configuration file, you can specify such options as the default graphical format in which images are saved. You can load such a configuration file if you want to configure your final images further. (Note that the Spoiklin_Soice.cfg file is best not altered manually, instead start Spoiklin Soice graphically and configure the options you want then save the options and copy the Spoiklin_Soice.cfg file somewhere else so that it is not overwritten). Below shows how to load a configuration file together with all commands shown so far:
width 600
height 400
config_file "C:\Users\sarah\Documents\projects\cake\Spoiklin_Soice.cfg"
load_files "C:\Users\sarah\Documents\projects\cake\classes\com\sarah\controller"
add_files "C:\Users\sarah\Documents\projects\cake\classes\com\sarah\model"
select com.sarah.controller.Controller.start
extract_highlighted
save_graphics "/home/ed/tmp/Controller-start-trans"
set_scope com.sarah.model.GameFactory
save_graphics "C:\Users\sarah\Documents\images\GameFactory-class"
level_up
set_scope com.sarah.model
save_graphics "C:\Users\sarah\Documents\images\model-package"
level_up
save_graphics "C:\Users\sarah\Documents\images\package-level"
7.9. Changing the analysis view.
The tool defaults to showing the, "Transitive dependency," analysis of your system. You can change this to show any analysis by specifying the analysis name as shown in the GUI. For example, if you wish to switch to the, "Impacted set," analysis, use (note that the case is irrevelant but the quotation marks are mandatory):
set_analysis "Impacted set"
7.10. Sequence-diagrams.
Sequence-diagrams can only be generated on function-level but apart from this constraint, they are generated in much the same way as all other specific diagrams.
You must select the function that you wish to diagram, extract that image, issue the command to generate a sequence-diagram of the extracted image and finally save the sequence-diagram to a file (the latter being a different command from saving non-sequence-diagrams graphics to a file):
width 600
height 400
load_files "C:\Users\sarah\Documents\projects\cake\classes\com\sarah\controller"
select com.sarah.controller.Controller.start
extract_highlighted
sequence_diagram
save_sequence "/home/ed/tmp/Controller-start-trans"
Sequence-diagrams only really make full sense when there is just one function at the "top" of the diagram, otherwise your sequence-diagram will have multiple starting points in the same diagram (which can look ragged). One solution to this is to set the analysis to "Impact Set" before selecting the function in which you are interested: this will then ensure that this function appears as the sole "root" of the functions in extracted diagram (though this of course cuts off the transitive dependencies leading into this function).
Note that sequence diagrams are slightly narrower than the number of pixels given via the width command and ignore the height command comletely growing as long as necessary to fit the sequence of interest.
7.11. Saving statistics overview.
Once a system is loaded you can dump all its statistics to a plain text file.
load_files "C:\Users\sarah\Documents\projects\cake\classes\com\sarah\controller"
dump_stats "/home/ed/tmp/overview.txt"
|
