Best viewed in the Internet Explorer.
Contact us at info@sourceglider.com
for feedback about MetriX.
Online Manual
Customizing SourceGlider
Customizing SourceGlider
This chapter describes the different ways of customizing SourceGlider. Also you can find here the details on License
Key Dialog, Check for updates and Send report features.
All the features described here are not directly related to source analysis and don't require the analysis to be computed.
Therefore you can launch them in any phase of analysis.
Using SourceGlider Options Page you can set up the general parameters of SourceGlider. To launch the page select
Window > Preferences... in Eclipse menu and choose Source Analysis from the list.
Views activation group allows you to configure the views behavior. You can set up when each view has to be shown and
hidden. Choose the concrete view from the list on the left and configure in using controls at the right. You can select one of the
four modes:
During analysis - the view will be activated during the phase Being Analyzed. After transition to the phase
Analyzed, the view will be hidden.
After analysis - the view will be activated after transition to the phase Analyzed.
On first query - the view will be activated in the phase Analyzed when user
selects some Java Elements for the first time.
Manually - the view will never be automatically activated. But you are still able to activate it manually by selecting
Window > Show View > Other... and choosing the view from the Source Analysis group.
You can set up two additional parameters for each view such as:
Close during analysis - the view will be hidden after transition to the phase Being Analyzed.
Close after analysis kill - the view will be hidden after you terminate the analysis. For example you can set this option
for all views. This is very useful if you want to quickly clean up the Eclipse workbench and get rid of annoying views. Simply
close the Analysis Summary View, the analysis will be killed in this case and all SourceGlider views will be hidden.
Note: You cannot set up the behavior for Analysis Summary View. It
should be always active when the analysis has been computed.
Some dialogs in SourceGlider have do not show again option. After you set that option for some particular dialog, the dialogs
of this type will never be shown again. To regain the original behavior of such dialogs, set the corresponding option in the
Dialogs enablement group.
Here you can specify where to store the saved analyses. If you change the value, you will
be prompted to move all the stored analyses to the new location.
You will hardly ever need to change the Analysis engine settings.
Enable safe mode - switch this option on if you encounter the errors during source analysis. It will slow down the
analysis.
Enable memory optimization - switch this option off if you still encounter the errors during source analysis.
Analysis running with this option set will require more memory, but is more error-safe.
There are some other ways to customize SourceGlider, scattered in the Eclipse menus.
To set up the color scheme for Analysis Report View,
Analysis Progress View and some other features, select
Window > Preferences... in the Eclipse menu, choose General > Appearance > Colors and Fonts, and select
Source Analysis from the list.
To change the key binding for the Analysis Report Action (default is Ctrl+`),
select Window > Preferences... in the Eclipse menu, choose General > Keys, select Source Analysis in
Command > Category, provide the new binding in Key Sequence > Name, and press Add.
To remove SourceGlider from the list of Startup Plugins (it is not recommended), select Window > Preferences...
in the Eclipse menu, choose General > Startup and Shutdown and deselect Source Analysis in the
Plug-ins activated on startup list.
To add some of SourceGlider views to the Shortcuts, select Window > Customize Perspective... in the Eclipse menu,
choose Shortcuts tab, choose Show View in Submenus, and select either the whole Source Analysis
category or some particular views.
To remove Source Analysis submenu from the Eclipse menu, select Window > Customize Perspective... in the Eclipse menu,
choose Commands tab, and deselect Analysis Action Set category.
The real power of customizing the analysis is the Filters Mechanism. It allows you to add some missing dataflow information
to the analysis. Currently there are two types of filters.
Arrays are the common way of storing the sets of values. The more sophisticated way of storing the values is to use
Java Collections. You can do the same things with collections as you do with arrays: you can add and get the values of collection.
To enable Arrays Analysis for some collections, SourceGlider treats them as plain arrays. To do that SourceGlider needs to map
the methods of particular collection to the three basic array mechanisms: get the value by index, set the value by index
and copy the contents. SourceGlider has the complete set of mappings for Java 1.5 Collections, including the concurrent
collections. You can change these mappings or add the new collections into the Arrays Filters Dialog. It will affect the analysis
behaviour.
Arrays Filters Dialog has four mappings representing four common array mechanisms. If you think that some class resembles the
array and you want to perform Arrays Analysis on that class, you need to add this class to the Arrays Filters. Add the new item
to each map, if this class provides the corresponding array-like mechanism:
Generic container types - this map helps SourceGlider to derive the type of elements of this container provided that it
knows the type of the collection. Use second and third columns if the collection is generic. Enter the index number of the type
parameter, corresponding to the type of stored values, in third column. Second column is for map-like containers. If the collection
is not generic and you know the concrete type of stored values, enter this concrete type in the fourth column. Use none of columns when
there's nothing known about the type of stored values. Note: when you use the concrete type mode, enter the value "concrete type" in the third column.
For example let's consider the collection java.util.Map< K, V > - this collection can store the keys of type
K and values of type V. You need to enter the value "1", the index number of type parameter
K, in the second column, and "2", the index number of type parameter V - in the third column.
Another example is the class java.lang.Integer. This class can be considered as the array that can hold exactly one element
of type int. You need to enter the value "concrete type" in the third column and the value "/I", the Java type
signature for the primitive type int, in the fourth column.
Access methods - this map helps SourceGlider to find the array-like "get"-method in the collection. You need
to provide the method signature and number of parameters of the "get"-method. Note: The method signature in SourceGlider is not the same as the method signature in Java. Our method signature doesn't carry
the information about parameter types, it is defined as the full-qualified name of the method + "()" if it has no parameters
or "(...)" if it has one or more parameters.
For example for class java.util.Map the "get"-method get( key ) will have the signature
java.util.Map.get(...) and the number of parameters 1.
Store methods - this map helps SourceGlider to find the array-like "set"-method in the collection. You need
to provide the method signature, number of parameters of the "set"-method, the index number of the parameter that corresponds
to the values to be stored and the domain. Domain is usually set to values, indicating that this method sets the
values for the container. Other two modes: keys and both are for setting the keys to the map-like containers.
For example for class java.util.Map the "set"-method set( key, value ) will have the signature
java.util.Map.set(...), the number of parameters 2, index number of the value-parameter 2,
and domain values. For treating keys you need to enter another row for this method: index number of the key-parameter
will be 1 and domain will be keys.
Copy methods - this map helps SourceGlider to find the array-like "copy"-method in the collection. "Copy"-methods
allow to add the whole collection to the other collection, while "set"-methods add the single value. You need to provide the
method signature, number of parameters of the "copy"-method, the index number of the parameter that corresponds
to the source-collection, the index number of the parameter that corresponds to the destination-collection and the domain
(see above). Note: The index number of the parameter is not necessarily the "digital" number. Values can be passed not only through the
parameters, but also through the invocator and through the return value. The values invocator and result,
corresponding to that ways of values passing, are among the acceptable in the parameter-index-columns. Note: If the method copies not only the values, but also the keys (for example HashMap.clone()), set the domain
to both.
For example for class java.util.List the "copy"-method addAll( collection ) will have the signature
java.util.List.addAll(...), the number of parameters 1, index number of the source-parameter 1,
index number of the destination-parameter invocator (because it copies all the values to the invocator collection),
and domain values.
Another example is the class java.util.List. The "copy"-method iterator() will have the signature
java.util.List.iterator(), the number of parameters 0, index number of the source-parameter
invocator (because it takes the source values form the invocator collection), index number of the destination-parameter
result (because it copies all the values to the collection that is returned as the result of this method), and domain
values.
You can add the new items to the maps by button and remove the items by
button. After the changes to the filters were made, press Close button. You will be
asked whether to save the changes or not. If the filters were modified, the logic of the analysis changes. Therefore if there is an
active analysis and you have changed the filters, you will be prompted to perform the reanalysis.
You can restore the original Filters that are delivered with SourceGlider by pressing Restore defaults button.
Threads are another example of the filters mechanism described above. Threads searching mechanism of SourceGlider is very sophisticated
and is based on the set of heuristics. Three of these heuristics can be customized:
Method thread prefixes heuristic: if the fully-qualified name of the method starts with the prefix Prefix, this method
will represent the thread with the name Thread.
For example, if the method name starts with javax.swing, then SourceGlider considers that this method is called from the
Swing UI Thread.
Thread switches heuristic: if the method M with the signature Thread method start signature is declared in
the class that has the instance which is passed to the method with the signature Switch signature by the parameter with the index
number Thread param index, then the method M will represent the thread with the name Thread.
For example, if the instance of java.lang.Runnable is passed to the method
javax.swing.SwingUtilities.invokeLater(...), then SourceGlider considers that the run() method of the
java.lang.Runnable is called from the Swing UI Thread.
User threads heuristic: if the method with the signature Signature is declared in the type Type, then this
method will represent the thread denoted by Type.
For example, if there is an instance of class java.lang.Thread with redeclared method run(), then SourceGlider
considers that this method is started in the new thread denoted by this instance of java.lang.Thread.
You can add the new items to the maps by button and remove the items by
button. After the changes to the filters were made, press Close button. You will be
asked whether to save the changes or not. If the filters were modified, the logic of the analysis changes. Therefore if there is an
active analysis and you have changed the filters, you will be prompted to perform the reanalysis.
You can restore the original Filters that are delivered with SourceGlider by pressing Restore defaults button.
Source analysis is a complex process and may cause errors to appear. There are three types of errors in SourceGlider:
Warnings are the least severe type of errors. Warnings are basically displayed because of incorrect treatment of
SourceGlider, providing wrong values, etc. Warnings can be displayed either as dialog messages or as Error Log entries.
Errors are displayed when there is some inconsistence either in external parameters (e.g. some files do not exist) or
in Eclipse runtime (e.g. Eclipse failed to parse some source files). Errors can be displayed either as dialog messages or as
Error Log entries.
Bugs are special type of Errors. They appear when some unexpected exceptions appear. When the Bug happens, you
get the following message:
You may check for updates directly from this dialog. With some certain probability this bug may has been fixed in the new
SourceGlider release. In this case you need to download and install it.
If you press Send report button, the new Bug Report will be automatically generated and you will be redirected to the
SourceGlider support page. Optionally fill the bug description, press
Send button, and soon we will receive your bug report.
Note: You are able and recommended to send us bug reports even when Bug message dialog does not appear. If you
have noticed some incorrect behavior of SourceGlider, you can send the Bug Report by either of two ways:
Select Source Analysis > Send bug report in the Eclipse menu
Visit SourceGlider support page at http://www.sourceglider.com/support
and manually provide the detail information for this bug. Note that in order for us to reproduce your bug, you need to
include the Eclipse Error Log into the bug report. This is done automatically when you use the Send bug report
feature, but if you prefer not to use it, you need to get the textual representation of the error log. You can get it by
pressing button in the Error Log View.
Note: You can check for updates without encountering the bug. Simply select Source Analysis > Check for updates
in the Eclipse menu and you will be told whether your SourceGlider version is the last one, or there is a new release. In the latter
case it will suggest you to be redirected to the SourceGlider download page.
If your SourceGlider copy is unlicensed, each try to launch the analysis (either Quick Analysis or Composite Analysis)
will lead you to the Enter License Key dialog window. Also you can launch this dialog either by following the link at
the bottom of Analysis Report View or by selecting Source Analysis > Enter License Key...
in the Eclipse menu.
You need to paste the key that you have recently received by email into the form. You can do it by either of three ways:
Paste from clipboard, Get license from file or enter it from the keyboard. Immediately after it is proved that the key
is correct, the Licensee information will be shown at the bottom of this dialog and the OK button will be enabled.
If you have entered the Trial License Key into the dialog, you have only 30 days to evaluate SourceGlider. The number
of days left will be shown at the bottom of the Analysis Report View. If you decide to purchase SourceGlider, you will get the
Purchase License Key. You need to enter it the same way as you entered the Trial License Key.
Note: When you are using SourceGlider in Trial Mode, some features are disabled. You cannot perform analysis on
the sources bigger than 1M (except for performing the Structure Metrics Analysis). You cannot also load big analyses and dynamically
add sources to the analysis to get the analysis on sources bigger than 1M.
Note: The 30 days evaluation period starts immediately after you have requested the Trial Key from our web site,
but NOT from the moment you enter this key into SourceGlider. Therefore if you are not planning to try SourceGlider now, don't
request the Trial License Key beforehand.
After the evaluation period expires, you will not be able to perform analyses, but you will still be able to load previously
saved analyses and use all the SourceGlider features related to the loaded analysis except for performing the incremental analysis
recomputation (analysis update).
When you reinstall (update) SourceGlider, your License Key will be saved and you don't need to enter it twice. If you have several
instances of SourceGlider in different instances of Eclipse, you will still have only one instance of License Key.
Online Manual
button and remove the items by
button. After the changes to the filters were made, press Close button. You will be
asked whether to save the changes or not. If the filters were modified, the logic of the analysis changes. Therefore if there is an
active analysis and you have changed the filters, you will be prompted to perform the reanalysis.
button in the Error Log View.