SDA SE Wiki

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

User Tools

Site Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
research:jtransformer:tutorial_old:stepbystep2 [2010/06/01 11:06]
fabian.noth
research:jtransformer:tutorial_old:stepbystep2 [2018/05/09 01:59] (current)
Line 1: Line 1:
 +//**Diese Anleitung ist in Bearbeitung. Bitte nicht löschen.**//​
 +/*
 +Projekte:
 +  * {{:​research:​jtransformer:​jt_tutorial.zip|}} (kleines Java Beispiel Projekt)
 +  * {{:​research:​jtransformer:​jt_tutorialprolog.zip|}} (Prolog Dateien für Analyse und CTs)
 +  * {{:​research:​jtransformer:​jhotdraw6.1.zip|}} (Beispiel für ein größeres Projekt)
 +  * {{:​research:​jtransformer:​copytoclipboard-example.zip|}} (Beispiel für copy to clipboard example)
 +*/
  
 +====== Getting Started ======
 +
 +-> [[..:#​prerequisites]]\\
 +-> [[..:#​jtransformer tutorial project]]\\
 +-> [[..:#your first jtransformer query]]\\
 +-> [[..:#the factbase inspector (fbi)]]\\
 +-> [[..:#​working with prolog files|Working with Prolog Files (Example: Pattern Mining)]]\\
 +-> [[..:#​further reading]]
 +----
 +
 +===== Prerequisites =====
 +
 +  - Before you start using JTransformer it is important that you understand the concept of //logic program representation and transformation//​. This presentation will give you all the information needed for this tutorial: ​ {{:​research:​jtransformer:​kniesel-analysisandtransformation.pdf|Logic-based Software Analysis and Transformation}}:​!:​
 +  - If you haven'​t done so already, [[:​research:​jtransformer:​installation|download and install JTransformer]].
 +  - If everything worked fine you should see a "​JTransformer"​ menu and "​Prolog"​ menu. For this tutorial you will need the following views:
 +          * Open the "​Factbase Inspector"​ (F.B.I.): Window -> Show view -> Other -> JTransformer -> Factbase Inspector
 +          * Open the "​Factbase Statistics":​ Window -> Show view -> Other -> JTransformer -> Factbase Statistics
 +          * Open the "​Prolog Console": ​     Window -> Show view -> Other -> Prolog -> Prolog Console
 +
 +----
 +
 +===== JTransformer Tutorial Project =====
 +
 +In the course of this tutorial we will be using the //​JTransformer Tutorial Project//.
 +Please add the JTransformer Tutorial Project to your workspace:
 +
 +  - Download the {{:​research:​jtransformer:​jt_tutorial.zip|JTransformer Tutorial Project}}
 +  - Open "File -> Import -> Existing Projects into Workspace ​
 +  - Choose "​Select archive file" and open the just downloaded archive.
 +
 +/*
 +FIXME Neue Version des JT-Tutorial einbinden FIXME
 +
 +  - Open "File -> New -> Example... -> JTransformer Tutorial Project
 +  - Choose a project name and click "​Finish"​
 +*/
 +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 projects((On one million lines of code it may take 15 to 30 minutes, depending on your hardware.)) but it only happens //once//. From this point on, the fact representation will be updated whenever a Java editor is saved, as long as there are no compilation problems. Updates are very fast since only the changes are propagated. They will mostly be unnoticeable. ​
 +
 +During 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 the JT_Tutorial and the JT_Tutorial-output project in your package explorer:
 +
 +{{:​research:​jtransformer:​gs_package_explorer.png|}}
 +
 +There are some example classes and packages in the source folder of this project. /* You can change anything you want, since it's always possible to create a new project by choosing "New -> Example ...". */
 +
 +If you want to see how JTransformer can handle a larger project you can download and import the {{:​research:​jtransformer:​jhotdraw6.1.zip|JHotDraw Project}} (273 source classes).
 +
 +----
 +
 +=== Activating JTransformer for your own Project ===
 +
 +//If you choose to work with the JTransformer Tutorial Project you can skip the following steps, since the assignment of the factbase has already been done. You can continue with [[..:#your first jtransformer query]].//
 +
 +You can, of course, use your own favorite Java 1.4 or Java 5.0 project for your experiments but be aware that Java 5 "​generics"​ are **not** supported by JTransformer,​ yet. All other [[..:​prologast|Java 5 features]] (enumerations,​ the for each construct, annotations,​ etc.) are supported.
 +
 +In order to be able to use JTransformer on a particular project you must first assign it to a //​JTransformer Factbase//​. ​
 +
 +  - Right-click on your project and select "​Configure"​ -> "​Assign JTransformer Factbase"​ from the context menu (left-hand-side image below). ​
 +  - A new dialog window will open offering a number of configuration options (right-hand-side image below).
 +  - For the purpose of this basic tutorial leave everything at it's default value and click "​OK"​.
 +
 +{{:​research:​jtransformer:​assign_factbase_contextmenu.jpg?​400|"​Assign Factbase"​ Context Menu Item}} ​  ​{{:​research:​jtransformer:​assign_factbase_dialog.jpg|"​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:
 +
 +{{:​research:​jtransformer:​gs_first_query_1.png|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 explicitly((For more details about factbase switching, see the PDT tutorial)). Now you see
 +the prompt "?​-"​ that invites you to enter a query: ​
 +
 +{{:​research:​jtransformer:​gs_first_query_2.png|The Prolog Console displaying the prompt "?​-"​ asks you to enter a query.}}
 +
 +Type the following query in the Prolog Console and hit <​Enter>​((You do not need to enter the prompt "?​-"​.)):​
 +  ​
 +<Code lang-prolog>?​- classT(Id, CompilationUnit,​ Name, Members).</​Code>​
 +  ​
 +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: 
 +
 +{{:​research:​jtransformer:​gs_first_query_3.png|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 unit((A compilation unit is the set of all classes defined in the same Java source file.)) containing the class definition. ​  
 +  * Members is a list((Syntax:​ Square braces indicate lists.)) of IDs of member elements (fields, methods, nested classes).
 +
 +All the predicates that represent [[:​research:​jtransformer:​prologast|the Java AST]]  are documented [[:​research:​jtransformer:​prologast|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) ((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.)).\\
 +  * To abort the query type '​a'​ or <​Enter>​ ((If you activated the "Use Enter key for backtracking"​ option in your PDT Console preference settings you must type '​a'​ to abort)).
 +
 +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 ((__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**.)): ​  
 +
 +<Code lang-prolog>?​- classT(Id, CompilationUnit,​ '​B',​ Members).</​Code>​
 +
 +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.:
 +
 +<Code lang-prolog>?​- classT(Id, _, '​B',​ _).</​Code>​
 +
 +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 ",":​
 +
 +<Code lang-prolog>?​- classT(Id, CompilationUnit,​ Name, Members), not(externT(Id)).</​Code>​
 +
 +
 +Now you can:
 +  * Find out about the predicates that represent [[:​research:​jtransformer:​prologast|the Java AST]]
 +  * Learn more about the Prolog Console and the [[..:​..:​pdt:​start|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:​start|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| ​  node ID selected in the Prolog Console]],
 +  * [[..:#​displaying an fbi for an editor selection| ​           source code selection in a Java Editor]],
 +  * [[..:#​displaying an fbi for a file in the package explorer| file selected in the Package Explorer]] or
 +  * an arbitrary node ID entered interactively. ​
 +
 +== Displaying an FBI for an ID in the Prolog Console ==
 +
 +Enter the following query in the Console:
 +
 +<Code lang-prolog>?​- classT(Id,​CompilationUnit,'​B',​Members).</​Code> ​
 +
 +The result will look similar to this((Don'​t worry if your results aren't identical to the ones shown here. IDs may differ.)): ​
 +<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":​
 +
 +{{:​research:​jtransformer:​fbi_open_from_console.png|}}
 +
 +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 B((Choose //show groups// in the [[..:#​factbase inspector options]] if you don't see the folders but only the PEFs.)).
 +
 +
 +{{:​research:​jtransformer:​fbi_example.png|}}
 +
 +
 +== Displaying Related Source Code from the FBI ==
 +
 +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:
 +
 +{{:​research:​jtransformer:​fbi_show_sc.png|}}
 +{{:​research:​jtransformer:​fbi_show_sc2.png?​600px|}}
 +
 +== 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):
 +
 +{{:​research:​jtransformer:​fbi_open_from_editor.png?​600|}}
 +{{:​research:​jtransformer:​fbi_example2.png|}}
 +
 +== 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:
 +
 +{{:​research:​jtransformer:​fbi_open_from_explorer.png|}}
 +
 +== More on the FBI ==
 +
 +For more details see the [[factbase_inspector|Factbase Inspector tutorial]].
 +
 +----
 +
 +===== Working with Prolog Files =====
 +An alternative to enter your query in the console is to work with Prolog Files (*.pl).
 +
 +Download and import the {{:​research:​jtransformer:​jt_tutorialprolog.zip|JT-Tutorial Prolog Project}}. It consists of some examples for analysing and modifying your factbase.
 +
 +==== Edit & Create Prolog Files ====
 +If you want to edit a prolog file, just click on it in your Package Explorer. The Prolog Editor will open and you can edit the Prolog Code. To create a new Prolog file just click "​New"​ -> "​File"​ and chose the file extension "​.pl"​.
 +
 +==== Load Prolog Files ====
 +To let a prolog file work on your factbase 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 menu item '​Prolog -> Consult'​ or the shortcut '​F9'​. It is not necessary, that the prolog files belong to the same project like your factbase. Just make sure, that you choose the right factbase in your Prolog console. If a popup shows up just click "​No"​ (you don't want to switch to default runtime).
 +
 +To consult all Prolog files belonging to the JT_Tutorial project open the load.pl and press '​F9'​. You should see something like this:
 +
 +{{:​research:​jtransformer:​gs_consult_example.png?​600|}}
 +
 +Now you can analyse your program with some examples:
 +  * search for database calls in nested loops (potential performance issue)
 +  * use //Depth of inheritance//​ metric to find bad smells
 +  * count classes, methods ...
 +  * pattern mining (see example below)
 +  * ...
 +
 +==== Example: Pattern Mining ====
 +In the 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. One simple example is the Singleton Pattern. You can describe it in the following way:
 +  * there is a static method which returns an instance of this class
 +  * in this method there is an access on a field of the same type
 +  * //all constructors should be private// (this is not always true)
 +
 +The file '​singleton.pl'​ provides a prolog statement called: //​mineSingleton//​. The implementation is the following:
 +<Code lang-prolog>​
 +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
 +</​Code>​
 +
 +//​classMethodReturnsOwnInstance//​ is also implemented in the '​singleton.pl'​. So the result will consist of all classes which have a (static) method that returns the own instance.
 +
 +Let's try it with the JT_Tutorial project (of course you can take any project you like which has a singleton pattern).
 +
 +Make sure you choose the right factbase in your Prolog console (JT_Tutorial : JTtransformer). Consult the load.pl file and type:
 +<Code lang-prolog>​
 +mineSingleton(ClassName,​ MethodName, FieldName).
 +</​Code>​
 +
 +The result should look like this:
 +
 +{{:​research:​jtransformer:​pattern_mining.png|}}
 +
 +
 +Maybe you want to make sure that all singleton classes should only have private constructors. This can be done by extending the singleton.pl file with the following code:
 +
 +<Code lang-prolog>​
 +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,​_,​_,​_),​ not(externT(Class)),​
 +   ​forall( constructorT(Method,​Class,​_,​_,​_), ​   % Constructor method
 +           ​modifierT(Method,​ private) ).
 +</​Code>​
 +
 +Save the file, consult it again and call the just created Prolog statement from your console:
 +
 +<Code lang-prolog>​
 +mineSingletonWithNonPrivateConstructor(ClassName,​ MethodName, FieldName).
 +</​Code>​
 +
 +The only result for this query should be the '​BadSingleton'​ class. ​
 +
 +Now you can try to analyse your program with other Prolog files (find bad smells, nested DB accesses etc. ). Or you can make modifications on your factbase by using [[cts|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
 +
 +  * -> [[cts|Using Conditional Transformations]]
 +  * -> [[copy_to_clipboard|Using Source Templates for Queries and Transformations]]
 +  * -> [[error_tolerance|Working With Incomplete Programs]]
 +  * -> [[..:​analysing multiple projects]]
research/jtransformer/tutorial_old/stepbystep2.txt · Last modified: 2018/05/09 01:59 (external edit)

SEWiki, © 2019