Cross-Indexing Assignment

Many of you may have used one of the Java cross-referencing tools available on the web.  For the current assignment you will build a simple variant of one of these tools. 

The best cross-referencing tools incorporate a compiler front end.  We’re going to take a shortcut and leverage the information saved by javac in the course of compiling a program to byte code.  This is not a fully general solution:  javac doesn’t save everything you’d like to know (the line numbers of class and field declarations, for example), but it saves enough to make for both an interesting base project and some challenging extra credit options.  It also gives us a chance to learn about the structure of Java .class files, to experiment with scripting languages, and to generate HTML. 

Requirements

You may write your cross-referencing tool (call it jxref) in Perl, Python, or Ruby (your choice).  You will run it in a directory containing .java source files and corresponding .class files, as produced by javac Jxref will run javap -verbose -private on the .class files, and then read the corresponding .java files.  You’ll want to pay particular attention to the LineNumberTables and the Code arrays in the javap output.  Note that a single .java file may produce multiple .class files:  one for each Java class. 

For every file foo.java, jxref should create a file foo.html that looks just like the Java source, except that every method invocation is a live link.  These files should be grouped together in a subdirectory named HTML, with an extra file index.html that contains a list of all the source files (with links), a special link to main, and information about when and where the xref tool was run. 

If you click on a method that is defined in one of the standard system libraries, your browser should move to the corresponding documentation page at http://java.sun.com/javase/6/docs/api/ (we're still running Java 6 at CSUG).  You’ll want to explore that site a bit to figure out its naming structure.  Use “view source” in your browser to examine the <a name> tags within the files; these will allow you to link to the documentation for individual methods. 

If you click on a user-defined method (one whose source is in the current directory), your browser should move to the .html version of the corresponding source file, with the relevant method declaration positioned near the top of the window, and its name highlighted in a contrasting color.  (You can do the highlighting dynamically with JavaScript; you won’t need to create separate files for each method declaration.) 

Nested classes introduce a bit of extra complexity.  Their .class file names contain a dollar sign ($) between the name of the surrounding (outer) class and the nested (inner) class.  You might want to solve the assignment for non-nested classes first, then enhance it to handle nesting. 

Division of labor and writeup

As in previous assignments, you may work alone or in teams of two.  If you choose to work in pairs, one possible division of labor is for one partner to write the code that parses the javap output and the other to use this information to create the HTML files.  If you do this, be very careful to agree on the information you need and the format in which to represent it. Also be sure to read each other’s code to look for errors. 

Be sure to follow all the rules on the Grading page.  As with all assignments, use the turn-in script:  ~cs254/bin/TURN_IN.  Put your write-up in a README.txt or README.pdf file in the directory in which you run the script.  Be sure to describe any features of your code that the TA might not immediately notice. 

Extra Credit Suggestions

Resources

You may find it useful to consult

Trivia Assignment

Before class on Tuesday, October 25, send e-mail to cs254 containing answers to the following questions: 

  1. Are you working alone or in a team?  If a team, who is your partner? 
  2. On the csug machines, copy /u/scott/Hello.class to your current directory and run javap -verbose Hello.  How many byte code instructions comprise the body of main?  How many entries are in the constant table? 
  3. Give a regular expression in Perl that matches only with syntactically valid email addresses. 
  4. How can you represent the characters ‘<’ and ‘>’ in HTML? 

MAIN DUE DATE:

Wednesday November 9, 11:59 pm; no extensions. 
Last Change:  24 October 2011 / Michael Scott's email address