RECODER Example Applications

This document describes a set of small example applications for RECODER. You should follow the instructions given here in a command shell. Users of non-Unix operating systems will have to adapt some commands.

Setup

Make sure you are using a current, stable JDK (at least 1.2 is required to analyze the input programs).
Make sure recoder.jar and recoder-examples.jar are in your classpath.
Change to the examples directory.
```
cd doc/examples
```

To compile the SOURCERER example, you need a current version of BeanShell in your classpath, available from www.beanshell.org. Beanshell is not required to run, however; the console will be simply be inactive if bsh can not be found.

Example Data

converter: Taken from the Sun Java Tutorial, a Swing-based unit converter mini application (7 files, 648 lines of code).
collections: The collections framework from the JDK 1.3 sources (30 files, 15770 lines of code) containing a lot of nested inner classes.

Example Programs

For most of the examples you may also try out a different project file than the one used in the instructions.

Source Analysis Examples

Cross Reference HTML Generator
A Syntax Node Statistic Tool
Sourcerer - Source Code Browsing Demo

A Simple Obfuscator

This transformations replaces all names of variables, methods, classes and packages by artificial ones, when this is feasible. It leaves main methods and methods redefining bytecode methods as are, such that the resulting program will be executable.

Perform function check for the Converter program:

cd converter
javac *.java
java Converter
rm *.class
cd ..

Run the transformation
```
java Obfuscate converter.prj
```
Inspect the modified source files. Check if they compile. Locate the main method.
```
cd output
ls
javac *.java
grep main *.java
```
Execute the class containing the main method (the exact file name may differ between JVMs).
```
java _56
```
You can remove all files in that directory afterwards - they are no longer needed.
```
rm *.*
```
Return to the base directory.
```
cd ..
```

[Source] [Top]

Global Code Instrumentalization

This transformation inserts a debug statement in front of any single method call within the program. Sometimes expressions must be flattened to do so. The resulting program will be executable and report method callers and callees for each call contained in the sources.

Note: The implementation is not yet really fast. We estimate a possible speed-up of factor 10-100 as soon as the incremental model update works.

Run the transformation.
```
java Instrumentalize converter.prj
```
Copy any unmodified files (Unit.java) into the modified directory. Inspect the modified files.
```
cp converter/Unit.java output
cd output
```
Compile the results and execute the class containing the main method.
```
javac *.java
java Converter
```
You can remove all files in that directory afterwards - they are no longer needed.
```
rm *.*
```
Return to the base directory.
```
cd ..
```

[Source] [Top]

A Poor Man's Cross Reference Viewer

This program will generate a bunch of HTML files containing pretty printed variants of the original sources. References are hyperlinked to the entity they refer to.

Run the generator.

java XReferenceHTMLGenerator collections.prj

Browse the results with an HTML viewer of your choice that supports frames.

cd output
netscape -remote openURL\("file:$PWD/index.html",new-window\) > /dev/null 2>&1 || exec netscape index.html &

You can remove all files in that directory afterwards - they are no longer needed.
```
rm *.*
```
Return to the base directory.
```
cd ..
```

[Source] [Top]

A Syntax Node Statistics Tool

This shell application shows the number of occurances of all encountered object types in the syntax forest of a project. For convenient classification, the existing type hierarchy is also taken into account. You can see from the results that the most frequent node is the identifier, and that it is most frequently contained in variable references.

Run the statistic tool on any input project.
```
java SyntaxStatistics collections.prj
```

[Source] [Top]

Sourcerer - Source Code Browsing Demo

This Swing application displays formatted sources and syntax trees of all compilation units in a project. It allows to navigate between declarations and referers. There are currently some auxiliary transformations that identify superfluous code fragments such as unused imports, interfaces, exceptions and type casts. If the example code is too small, try this on recoder itself (use a global path to the src directory as command argument). The browser is currently a proof of concept rather than a useful application but it already looks and feels okay. Some of the other examples will be integrated and further analyses and transformations will be added.

Run the tool.
```
java sourcerer.Main converter.prj
```

[Source] [Top]