Whyline for Java

Usually when we see something go wrong in a program's output, we have to guess what code is causing the problem. We usually guess wrong. The Whyline for Java allows you to instead ask questions about a program's output and get answers in terms of the code responsible. Click the screenshot above to watch a 90 second demonstration or download the video (5 MB). (And because I love my iPhone, here's an iPhone version too).

download

Here are some basic requirements for using the Whyline.

Java 1.5 or higher
1 GB of RAM, preferably 2 GB. The Whyline is a memory hog! You'll need at least 1 GB of RAM free to let the Whyline process the recordings to ask questions. (Its processing hundreds to thousands of MB to support these questions and it needs memory to do it quickly)
A Java program (consisting of a class hierarchy or a .jar file) that can be executed using a standard JVM
The Java Whyline supports questions about the textual or graphical output of most Java programs, but not questions about other types of output such as sound, network traffic, or file output. Specifically, it can only record graphical output rendered with java.awt.Graphics and its subclasses and textual output produced by java.io.PrintStream and its subclasses.

Choose your platform and follow the instructions.

OS X

Download the OS X application bundle (which is a fancy wrapper for the .jar file).
As with all other OS X apps, you can store the app wherever you like.
Double-click to launch the Whyline.

On first launch, the Whyline creates a folder called "Whyline" inside the application bundle to cache instrumented classes and store saved traces. You'll probably want to change this to some where in your home directory. You can do this in the preferences dialog in the Whyline, or by manually editing the plist file in which this path is stored.

To change the JVM's heap size (by default, its 1 GB), right-click on the application and choose Show package contents. Navigate to Contents > Info.plist. Inside the file, you want to find the property in Root > Java > VMOptions and change the number after -Xmx; this will increase the maximum amount of memory that the JVM can allocate.

Windows, Linux, or other platforms with Java support

Download the .jar file
Store the app wherever you like.
Make sure you have a Java version 1.5 or higher installed.
I've yet to create a windows wrapper, so to launch the Whyline, you'll need to open up a command window (Start > Run > and type cmd).
Navigate to the directory that contains the Whyline .jar file. Then, launch the Whyline like a standard Java app and give it lots of heap space (1 GB in the example below):
java -jar -Xmx1024m whyline.jar

On first launch, the Whyline creates a folder called "Whyline" inside the same directory as the Whyline. If you want to change this location, you can do this in the preferences dialog in the Whyline. The path itself is stored in the registry.

feedback

Yes, it's buggy, as are all research prototypes. If you'd like to send any feedback, send it to Andy at whyline@gmail.com. It's actually more helpful if you send it from within the Whyline using the "send feedback" button, because you can send a screenshot with your feedback.

tutorial

Rather than write a bunch of text documentation, I created a brief tutorial video (25 MB). It demonstrates:

what to do after downloading the Whyline
creating a launch configuration
launching your program
demonstrating the problem
loading the recording
asking questions
inspecting answers
saving your recording for later

I'll post answers to other questions I get here.

faqs

Is this software actively maintained? No; I wish it was, but the software is provided AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED and all that stuff. It's a research prototype and very buggy! If you find bugs, send them to whyline@gmail.com with lots of detail about the context of the problem and preferably a screenshot or two. Andy Ko was and is the sole author of the software and probably won't have time to address these issues quickly, as he is currently graduating and moving on to a new research position in the fall.

Is it open source? Not yet. I haven't released the source yet because of a provisional patent jointly owned by CMU, my advisor Brad Myers and myself. I'm trying to get them to allow me to release it anyway. That would certainly make it easier to maintain it!

Can you help me to make it work for my program? I wish I had time to help everyone because I want to get the idea out there. The best I can do for now is collect bug reports and try to get the source released. As people ask questions, I'll try to update the documentation on this page with workarounds.

Is there an Eclipse plug-in? No, not yet. Wanna write one? The Whyline is implemented independent of any Eclipse APIs; it just needs to be launched from the standard Eclipse launch configuration platform.

publications

I've published much about the implementation of the Whyline for Java in a paper at the International Conference on Software Engineering in 2008, which won one of a few distinguished paper awards.

Best
Paper!

local

Ko, A.J. and Myers, B.A. (2008) Debugging Reinvented: Asking and Answering Why and Why Not Questions about Program Behavior. International Conference on Software Engineering (ICSE), Leipzig, Germany, May 10-18. To appear.

disclaimer

CARNEGIE MELLON UNIVERSITY (CMU) MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR PURPOSE, OR MERCHANTABILITY, EXCLUSIVITY OR RESULTS OBTAINED FROM SPONSOR'S USE OF ANY INTELLECTUAL PROPERTY DEVELOPED UNDER THIS AGREEMENT, NOR SHALL EITHER PARTY HERETO BE LIABLE TO THE OTHER FOR INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES SUCH AS LOSS OF PROFITS OR INABILITY TO USE SAID INTELLECTUAL PROPERTY OR ANY APPLICATIONS AND DERIVATION THEREOF. CMU DOES NOT MAKE ANY WARRANTY OF ANY KIND WITH RESPECT TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT INFRINGEMENT, OR THEFT OF TRADE SECRETS AND DOES NOT ASSUME ANY LIABILITY HEREUNDER FOR ANY INFRINGEMENT OF ANY PATENT, TRADEMARK, OR COPYRIGHT ARISING FROM THE USE OF THE PROGRAM, INFORMATION, INTELLECTUAL PROPERTY, OR OTHER PROPERTY OR RIGHTS GRANTED OR PROVIDED TO IT HEREUNDER. THE USER AGREES THAT IT WILL NOT MAKE ANY WARRANTY ON BEHALF OF CMU, EXPRESSED OR IMPLIED, TO ANY PERSON CONCERNING THE APPLICATION OF OR THE RESULTS TO BE OBTAINED WITH THE PROGRAM UNDER THIS AGREEMENT. USERS ACKNOWLEDGE THAT THE PROGRAM IS A RESEARCH TOOL STILL IN THE DEVELOPMENT STAGE, THAT IT IS BEING SUPPLIED "AS IS," WITHOUT ANY ACCOMPANYING SERVICES OR IMPROVEMENTS FROM CMU.