Note

Preliminary instruction is written by (qiuruizju@gmail.com) and edited by Jihun Park (jhpark@se.kaist.ac.kr)

Introduction

To run CHIME UI, you should install and run CHIME core correctly.
CHIME UI is an Eclipse plugin project that utilizes the logic fact databases generated by Chime core project and let users input Tyruba logic queries to search over the code repository. To better understand how this works. You might want to learn a little bit about Tyruba queries and predicates. (http://tyruba.sourceforge.net)

Running CHIME UI


1. We hardcoded a Tyruba syntax file. In the project, you can see a folder named "SyntaxFile". In that folder there is a file named "syntax.rub". It is a syntax file for Tyruba. You need to copy that file to your local disk and change that file's location in the source code. Go to the file "ExecuteQuery.java" in package "us.utexas.ece.arise.chime.ui.queries". In line 60, you can see where we specify that file's location. So you can change the string variable "syntaxFile" and change it to your new location of syntax.rub. (This is inconvenient. I will try to fix this issue later.)

ChimeUI_1.gif

settings.pngsettings2.png

The parameters in the CHIME settings are required to run the application properly, such as the SVN URL, the user name, the password, the each revision number, the report path, and the report name (e.g., "https://subversion.assembla.com/svn/chimeexample", "anonymous", "annonymous", 1, -1, and Test_1)

* Update “org.eclipse.jdt.junit;bundle-version="3.7.100"” from MANIFEST.MF.

If you have a compile error on this issue, you need to update to match the version like:
a) Select “org.eclipse.jdt.junit (3.7.0).
b) Click “properties”.
c) Click “match” on “Available versions to match”.

Screen Shot 2013-07-09 at 7.19.59 PM.png

2. Run the project as Eclipse Application. (The Chime Core project needs to be in the same workspace as this one.) Open the menu Window -> Show View -> Other… You should be able to see a category called Chime. Open "Chime View" under it.

chime_ui_2.gifchime_ui_3.gif

3. After open the view, you can see a three column view. The leftmost column is several types of queries. You can click on one of them and the middle column will show you which queries that category contains. For example, the last group of predefined queries contains two queries named "DR7" and "DR8". Here "DR" stands for "Delta Relationship" which means a relationship between code elements or revisions.

chime_ui_4.png

4. You can double click on one of the predefined queries in the middle column. A query dialog will pop out and you can see each query's predicates. Each predicate will contain several arguments and you can edit the arguments by clicking on it. (You have to choose that predicate first.)

5. When you want to invoke this query, you can click "Ok". Then the query's results will show in the right column. The results are shown as a list of facts. If you are interested in one of them, you can double click on one of them. A dialog containing this result's predicates will pot out. If you want to see its source code, choose one and click "Ok". After a few seconds (fetching code from repository), the source code of that predicate will show in Eclipse. (Some of the predicate types might cause unexpected exceptions. I have not tested this part fully. So if it has any issue you can let me know. Thanks!)

6. If you want to compose your own queries instead of predefined queries, you can input a query all by yourself. You can see an icon "i" in the top right corner of Chime view. Click on that and a input text dialog will show and you can input your own query from scratch there. Then click "ok" the results will show in the right column like predefined queries.

7. An alternative is to compose a query by selecting existing predicates. You can do this by clicking on the icon beside the icon "i" in the previous step. A two column dialog will pop out. The left column lists all the predicates you can use now. ( These predicates will be explained later.) You can choose predicates by double clicking one of them and it will show in the right column. You can edit its arguments in the right column and double clicking one of the predicates in right column will delete that predicate. Click "ok" after you are done and the query will be invoked.

Logic predicates


In Chime, each logic predicate represents a code element or a relationship between code elements. You can take a look at the generated fact base and take the following as reference. It will make more sense if you can create a simple multi version sample program and run Chime against it and check the generated results.

PL(String, Integer, Integer)
Package Lifetime: A package in the program. First argument is the name of the package, the next two arguments are the starting and ending revisions of that package.

CL(String, String, Integer, Integer)
Class Lifetime: A class in the program. First argument is the fully qualified name of a class and second argument is the short name of that class. Last two arguments are the starting and ending revisions of that class.

ML(String, String, Integer, Integer)
Method Lifetime: A method in the program. First argument is the fully qualified name of a method and second argument is the short name of that method. Last two arguments are the starting and ending revisions of that method.

FL(String, String, Integer, Integer)
Field Lifetime: Represents fields in the program. The meaning of the arguments are similar to class or method.

MC(String, String, Integer)
Method change: This represents a method's body is changed in a revision. The first argument is the fully qualified name of that method and second argument is short name for that method. The last argument is the revision number that this method's body is changed.

LC(String, String, String, Integer)
Lookup change: This represents a dynamic dispatch change. Due to some changes in the code, a method is dynamically dispatched to another method. The first argument is a combination of the second one and the third one. The second argument is the FQN(fully qualified name) of the original method the it is dispatched to and the third argument is the new method's FQN that it is dispatched to after change. The last argument is the revision number that this change happen.

containment_edge(String, String)
This represents a containment relationship, such as a class contains a method. The first argument contains the second argument.

inheritance_edge(String, String, Integer, Integer)
This represents class hierarchy, such as a class inherits another class. The first argument is FQN of a super class and the second argument is FQN of its subclass. The last two arguments are the beginning and ending revision numbers for this relationship.

change_order_edge(String, String)
In Chime's graph data structure, this edge connects ML with MC. So it would be more meaningful in a graph but not very useful in logic database. I think you can ignore this edge for now.

reference_edge(String, String, String, Integer, Integer)
Currently, this fact only represents method invocation. The first argument is FQN for callee method and second argument is FQN for caller method. The third argument is a constant string "MI" which stands for "method invocation". The last two arguments are the beginning and ending revision numbers for this method invocation relationship.