Home

# 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

1. Make sure you are using a current, stable JDK (at least 1.2 is required to analyze the input programs).
2. Make sure `recoder.jar` and `recoder-examples.jar` are in your classpath.
3. 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 to Source Transformation Examples

- A Simple Obfuscator

- Global Code Instrumentalization

### 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.

1. Perform function check for the Converter program:

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

2. Run the transformation

       java Obfuscate converter.prj

3. Inspect the modified source files. Check if they compile. Locate the `main` method.

       cd output
       ls
       javac *.java
       grep main *.java

4. Execute the class containing the main method (the exact file name may differ between JVMs).

       java _56

5. You can remove all files in that directory afterwards - they are no longer needed.

       rm *.*

6. 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.

1. Run the transformation.

       java Instrumentalize converter.prj

2. Copy any unmodified files (`Unit.java`) into the modified directory. Inspect the modified files.

       cp converter/Unit.java output
       cd output

3. Compile the results and execute the class containing the main method.

       javac *.java
       java Converter

4. You can remove all files in that directory afterwards - they are no longer needed.

       rm *.*

5. 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.

1. Run the generator.

       java XReferenceHTMLGenerator collections.prj

2. 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 &

3. You can remove all files in that directory afterwards - they are no longer needed.

       rm *.*

4. 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.

1. 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.

1. Run the tool.

       java sourcerer.Main converter.prj

[Source] [Top]