The technology which is used to transform the factbase (and therefore the source code) is called “Conditional Transformations” (or short: CTs). In this section we will describe how to define basic and parameterized CTs, how to run them manually and how to examine the changes they did on the factbase. To save time while writing conditions and transformations you can use the Source Templates feature.
Conditional Transformations are named specifications of program transformations. They consist of a name, a precondition and a transformation. If the precondition holds the transformation is executed.
A CT is represented in JTransformer by the Prolog fact ct/3. Its first argument is the head of the CT, the second one is its condition and the third one is the transformation description.
Below is a simple 'addField' CT. It creates the field 'newField' in the class 'MyClass' and sets the field's visibility to public. If you don't use the JT_Tutorial project just replace 'MyClass' by the name of any Class in your project.
ct( addField, % HEAD ( % CONDITION classT(Class, _, 'MyClass', _, _), % Get the ID belonging to class 'MyClass' not(externalT(Class)), % ... which is no external class not( fieldT(Field, Class, _, 'newField', _) ), % Make sure, that no field with the % name 'newField' exists basicTypeT(IntType, int), % Get the ID belongig to type int new_id(Field), % Field is a yet unused ID new_id(Modifier) % ... and so is Modifier ), ( % TRANSFORMATION: add(fieldT(Field, Class, IntType, 'newField', null)), % Add the field add(modifierT(Modifier, Field, 'public')), % Make it public add_to_class(Class, Field) % Let the class know, that it has a new member ) ).
The precondition describes structural requirements on the program to be transformed. It consists of Program Element Facts (PEF) and invocations of Prolog predicates connected by the usual boolean operators written in Prolog syntax:
Every non-negated PEF in the precondition is a check whether a corresponding program element exists in the internal representation of the program that we want to transform. In addition, the predicate 'new_id(Id)' is used to generate unique identifiers for new PEFs to be created in the transformation part. It binds the free variable Id to a new, unique identifier. In the example above, this is used to generate the identifier for the PEF representing 'newField'.
The transformation part can contain a conjunction of the following operations that transform the fact representation as their names suggest:
There are also some useful commands, which you can use in a transformation, under Java Transformations.
You can parametrize a CT head by appending comma-separated variables enclosed by parenthesis. The parameters can be used to pass values to a CT application and to link multiple CTs that are invoked together. If you just want to replace a specific call (and not all calls) you can use the parameterized version and bind the paramter “CallId” to the ID of the specific call.
ct( addField(FName,CName), % HEAD with parameters ( % CONDITION classT(Class, _, CName, _, _), % Get the ID belonging to class 'MyClass' not(externalT(Class)), % ... which is no external class not( fieldT(Field, Class, _, FName, _) ), % Make sure, that no field with the % name 'newField' exists basicTypeT(IntType, int), % Get the ID belongig to type int new_id(Field), % Field is a yet unused ID new_id(Modifier) % ... and so is Modifier ), ( % TRANSFORMATION: add(fieldT(Field, Class, IntType, FName, null)), % Add the field add(modifierT(Modifier, Field, 'public')), % Make it public add_to_class(Class, Field) % Let the class know, that it has a new member ) ). ct( makeFieldPrivate(FName, CName), % HEAD with parameters ( % CONDITION classT(Class, _, CName, _, _), % Get the class ID... fieldT(Field, Class, _, FName, _), % ... and the field ID modifierT(Modifier, Field, Visibility), % Get the modifier... ( Visibility = 'public' % ...and make sure it is public ... ; Visibility = 'protected' % ... protected ... ; Visibility = 'package') % ... or package visibility ), ( replace( modifierT(Modifier, Field, Visibility ), % replace the selected modifier with private modifierT(Modifier, Field, 'private') ) ) ).
To run a CT make sure it had been consulted and use the 'apply_ct(CT_Name)' predicate in the Prolog Console View. For instance, you can apply the 'addField' CT by executing the query:
To run several CTs in sequence, consult them and use the predicate 'apply_ctlist([ctHead1,…])'. The example below invokes the two parametrized CTs defined above, passing the desired arguments:
?- apply_ctlist( [ addField('testField', 'MyClass'), makeFieldPrivate('testField','MyClass') ]).
In either case, the invoked CTs are applied to all matching facts. So if you type: “apply_ct(addField('field123', Class)).”, the field 'field123' will be added to all classes.
Running a CT doesn't overwrite your existing Java source code, it only modifies your internal factbase. See view transformation results.
Note that substitutions computed for free variables in a CT invocation are not displayed in the Prolog console. In most cases there would simply be too many of them. Since all results are computed at once, backtracking on a CT application (by typing ';') will produce no new results.
Running CTs does NOT overwrite the existing source code. Only the internal factbase is modified. You can inspect it before deciding whether to save its new state as source code.
To inspect the results of the transformation you can use the Factbase Inspector (FBI). Open the FBI for a class that you expect to have been modified by the transformation. The new FBI's contents should look like this:
The FBI shows all different types of nodes (added, modified, deleted):
By double-clicking any node in the FBI you can either
The double-click is actually just a context-sensitive shortcut for different actions of the FBI context menu. The context menu offers additional actions to further inspect the results of your transformation. Just give it a try.
CTs only modify the internal factbase. Your source code is left unmodified. To write the changes back to java code you can use JT's “Reverse Engineering” feature.
If inspection of the factbase reveals some error in the perfomed CT its execution can be undone. There is currently no GUI for this. You have into type the following to your Prolog console:
See also: Transaction API.
By default, a CT will only have true or false as output. If you want to know more, you can enable logging for the CTs and see which facts were added or deleted. Call the predicate
enable_ct_logging/0. To disable the logging you can use