SDA SE Wiki

Software Engineering for Smart Data Analytics & Smart Data Analytics for Software Engineering

User Tools

Site Tools


Getting Started

Prerequisites

  1. View the presentation on Logic-based Software Analysis and Transformation to understand the basic concepts of JTransformer.
  2. Restart Eclipse

If the installation was successful you should see a “JTransformer” menu. For this tutorial you will need the following views:

  • The “Factbase Inspector” (F.B.I.): Window → Show view → Other → JTransformer → Factbase Inspector
  • The “Factbase Statistics”: Window → Show view → Other → JTransformer → Factbase Statistics
  • The “Prolog Console”: Window → Show view → Other → Prolog → Prolog Console

JTransformer Tutorial Project

Add the JTransformer Tutorial Project to your workspace:

  1. Open “File → New → Example… → JTransformer Example Projects1)
  2. Select “JTransformer Tutorial” and click “Finish”
  3. The Files will be downloaded (if necessary) and the example projects will be added to your workspace.

It will take some seconds to build the factbase. The creation of the factbase is indicated by the tiny progress bar in the lower right corner of the Eclipse window. As usual, you can open the Progress View (Window→Show View→Progress), to get more detailed information. The initial factbase creation may take a while on large projects2) but it only happens once. Afterwards, the factbase will be updated whenever a Java editor is saved (if there are no compilation problems). Updates are very fast since only the changes are propagated. They will be unnoticeable.

During the initial factbase creation, a new project named like your current project but with an added '-output' suffix will appear in the Eclipse Navigator and the Eclipse Package Explorer. It is used for storing the results of transformations when you activate the menu item “JTransformer → Save Factbase… → To Output Project(s)…”.

You should now see three new projects in your package explorer: JT_Tutorial, JT_Tutorial-output and JT_Tutorial_Prolog.

We will first take a look at the JT_Tutorial project. You can change anything you want, since it's always possible to delete the project and create a new one via the “New Example Project” dialog. If you want to keep the Prolog project and just reset the Java part of the tutorial you can choose “JTransformer Tutorial - Java Files”.

To see how JTransformer handles a realistic small project you can create the “JHotDraw” project (273 source classes). Here you have to activate JTransformer manually (see next section).


Activating JTransformer for a Project

If you work with the JTransformer Tutorial Project the assignment of the factbase has already been done, so you can continue with your first jtransformer query.

You can, of course, use your own favorite Java 1.4 or Java 5/6 project for your experiments. To use JTransformer on a particular project you must first assign a JTransformer Factbase to your project.

  1. Right-click on your project and select “Configure” → “Assign JTransformer Factbase” from the context menu (left-hand-side image below).
  2. A new dialog window will open offering a number of configuration options (right-hand-side image below).
  3. For the purpose of this basic tutorial leave everything at it's default value and click “OK”.

"Assign Factbase" Context Menu Item "Assign Factbase" Dialog


Your first JTransformer Query

It is now time to test the newly created factbase by trying out a few basic queries in the Prolog Console.

To enter a query, locate the Prolog Console view. If it is not visible, you might have to open it: From the JTransformer Menu, select Open Prolog Console. The console in which you can type your queries will appear.

Before you can ask your first query you must tell the Prolog Console which factbase you want to query. This is done by selecting a factbase in the drop down menu in the Prolog Console toolbar:

The Factbase Switcher of the Prolog Console

By default, the Factbase Switcher uses “Follow Mode”. Follow Mode means that the console always shows the factabase associated to the currently active editor window (if any).

Since we haven't opened any Java source file yet, we deactivate Follow Mode and select the JT_Tutorial factbase explicitly3). Now you see the prompt ”?-“ that invites you to enter a query:

The Prolog Console displaying the prompt "?-" asks you to enter a query.

Type the following query in the Prolog Console and hit <Enter>4):

?- classT(Id, CompilationUnit, Name, Members).

This way you ask for any class in the current factbase. A query basically asks the system to find correct values for the variables in the query. The capital spelling of Id, CompilationUnit, Name and Members indicates that these are variables. In our example, the first tuple of correct values for the variables is displayd like this:

Result for first query

This tells us that the first class found is the class named “Object”. The values for the variable

  • “Id” is the internal ID of the fact that represents the class “Object”.
  • “CompilationUnit” is the ID of the fact that represents the compilation unit5) containing the class definition.
  • Members is a list6) of IDs of member elements (fields, methods, nested classes).

All the predicates that represent the Java AST are documented here.

The yellow background of the Prolog Console indicates that the query is not completed yet – there might be more results:

  • To see the next result type ';' (semicolon) 7).
  • To abort the query type 'a' or <Enter> 8).

Try replacing the variable “Name” with a class name, e.g. 'B'. Be sure to surround the class name with simple quotes – otherwise it will be misinterpreted as a variable 9):

?- classT(Id, CompilationUnit, 'B', Members).

Now only one fact is matched: the fact that represents the “B” class.

If you just want to know which ID belongs to the class 'B' (and you are not interessted in the values CompilationUnit or Members) you can use an underscore “_” for this arguments.:

?- classT(Id, _, 'B', _).

Now the only result is the Class ID for Class 'B'.

If you just want to see your source-code classes (and not the ones from bytecode, like Object) you can connect two predicates with ”,“:

?- classT(Id, CompilationUnit, Name, Members), not(externT(Id)).

Now you can:

  • Find out about the predicates that represent the Java AST
  • Learn more about the Prolog Console and the Prolog Development Tool (PDT) included in JTransformer
  • Try your own queries, connecting basic predicates with ”,“ (AND) or ”;“ (OR). You might want to have a look at the PDT tutorial before.
  • Write your own, eventually recursive, predicates.
  • Learn how you can easily connect the IDs in the query results to source code in the Java editor.
  • Learn how you can navigate the internal representation of a Java project using the factbase inspector.

The Factbase Inspector (FBI)

The Factbase Inspectors of JTransformer let you view and easily navigate the fact representation of your Java program. You can open an FBI instance to inspect the AST subtree belonging to a particular

Displaying an FBI for an ID in the Prolog Console

Enter the following query in the Console:

?- classT(Id,CompilationUnit,'B',Members).

The result will look similar to this10): <code prolog > Id = 17252, CompilationUnit = 17327, Members = [17253, 17257, 17258] </Code>

Now select the number representing the ID of the class B and from the context menu select “Open In Factbase Inspector”:

A new Factbase Inspector View will open, showing a single classT element representing the class B, as the root of a tree. Expanding the classT element reveals the elements inside B11).

Now select an element (for example a methodT element). Bring up the context menu of that method and select the “Show Source Code” item. A Java Editor opens and the source code corresponding to the selected fact is displayed in the editor, setting the editor selection to precisely the text representing the element:

Displaying an FBI for an Editor Selection

Now select the field “dbAccess” in the Java editor. From the context menu select the “Open In Factbase Inspector” item (left-hand-side-image). A new Factbase Inspector View opens with the corresponding PEF as root (right-hand-side image):

Displaying an FBI for a file in the Package Explorer

Another option is to open the Factbase Inspector for a file in selected in the Package Explorer:

More on the FBI

For more details see the Factbase Inspector tutorial.


Working with Prolog Files

An alternative to typing your query directly in the console is to store it as a predicate definition in a Prolog file (*.pl).

Try this on the “JT_Tutorial_Prolog” project. To create it, just choose “File → New → Example… → JTransformer Example Projects → “JTransformer Tutorial - Prolog Files”. It consists of some examples for analysing and modifying your factbase.

Edit & Create Prolog Files

To open an editoer for a Prolog file just click on it in your Package Explorer. To create a new Prolog file just click “New” → “File” and chose the file extension ”.pl”.

Load Prolog Files

To load the predicate definitions (analyses) in a Prolog file you have to “consult” it. This is the Prolog term for compiling a file and loading it into the Prolog system. You can consult the currently active Prolog Editor file via the shortcut 'F9'. The Prolog files do not need to belong to the same project as your factbase. Just make sure that you choose in your Prolog console the factbase that you want to analyse before loading the Prolog file that defines the analysis. If a popup shows up asking whether to switch to the “default runtime” please click “No”.

To consult all Prolog files belonging to the JT_Tutorial project open the load.pl file and press 'F9'. You should see something like this:

Now you can analyse your program with some sample queries:

  • Search for database calls in nested loops (potential performance issue)
  • Use the Depth of inheritance metric to find bad smells
  • Count classes, methods …
  • Design pattern mining (see example below)

Example -- Design Pattern Mining

In the “JTransformer Tutorial Prolog project” there is a subfolder called 'patterns'. You can use the files in this folder to search for design patterns in your source code. A simple example is the “Singleton Pattern”. Any class C that uses this pattern are characterized by the following properties:

  • It contains a static method that returns an instance of C.
  • In this method there is an access to a static field of type C.
  • all constructors should be private (this is not always true)

The file 'singleton.pl' provides a Prolog predicate called mineSingleton. A predicate is the equivalent of a procedure / method in imperative / object oriented languages. The mineSingleton predicate is defined as:

mineSingleton(TypeName, MethodName, FieldName) :-
   classMethodReturnsOwnInstance(Type, Method, Field),
   classT(Type,_,TypeName,_),                % Get type name
   methodT(Method,_,MethodName,_,_,_,_),     % Get method name
   fieldT(Field,_,_,FieldName,_).            % Get field name

The predicate classMethodReturnsOwnInstance, also implemented in 'singleton.pl', does the real analysis, determining <Type, Method, Filed> triples consisting of identities of program elements that together form a Singletons (see above). The subsequent three predicate calls just access basic JTransformer facts (PEFs), to determine the names associated to the respective identities.

Let's try to find singletons in the JT_Tutorial project (of course you can use any other project that contains occurrences of the Singleton pattern).

Make sure you choose the proper factbase in your Prolog console (JT_Tutorial : JTtransformer). Consult the load.pl file and type:

mineSingleton(ClassName, MethodName, FieldName).

The result should look like this:

Maybe you want to detect Singleton classes that do not adhere to the requirement that all their constructors must be private. This can be done by extending the singleton.pl file with the following code:

mineSingletonWithNonPrivateConstructor(ClassName, MethodName, FieldName) :-
   classMethodReturnsOwnInstance(Class, Method, Field),
   not(allConstructorsPrivate(Class)),       % There are non-private constructors
   classT(Class,_,ClassName,_),              % Get type name
   methodT(Method,_,MethodName,_,_,_,_),     % Get method name
   fieldT(Field,_,_,FieldName,_).            % Get field name
   
allConstructorsPrivate(Class) :-
   classT(Class,_,_,_), 
   forall( constructorT(Method,Class,_,_,_),    % For each constructor method it is true 
           modifierT(Method, private)           % ... that its modifier is "private"
   ).

Save the file, consult it again and call the newly created Prolog predicate in your console:

mineSingletonWithNonPrivateConstructor(ClassName, MethodName, FieldName).

The only result for this query on the Java part of the Jtransformer tutorial should be the 'BadSingleton' class.

Now you can try to run the analyses implemented in other Prolog files (find bad smells, nested DB accesses etc. ). Or you can modify your factbase by using Conditional Transformations.

Further Reading

Now you now the basics of working with JTransformer: creating factbases, analysing and inspecting them. Next, you could continue to the tutorials on

1)
This is a feature of JTransformer 3.x
2)
On one million lines of code it may take 15 to 30 minutes, depending on your hardware.
3)
For more details about factbase switching, see the PDT tutorial
4)
You do not need to enter the prompt ”?-“.
5)
A compilation unit is the set of all classes defined in the same Java source file.
6)
Syntax: Square braces indicate lists.
7)
If you activated the “Use Enter key for backtracking” option in your PDT Console preference settings you must type <Enter> to see the next result.
8)
If you activated the “Use Enter key for backtracking” option in your PDT Console preference settings you must type 'a' to abort
9)
Syntax: A parameter starting with a capital letter or an underscore (_) represents a variable. One starting with a lower-case letter or enclosed in simple quotes represents a constant.
10)
Don't worry if your results aren't identical to the ones shown here. IDs may differ.
11)
Choose show groups in the factbase inspector options if you don't see the folders but only the PEFs.
research/jtransformer/tutorial_old/stepbystep.txt · Last modified: 2018/05/09 01:59 (external edit)

SEWiki, © 2019