<?xml version="1.0"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<book id="index">

<!-- Meta info -->

<bookinfo>

<date>2009-08-03</date>

<title>DrJava User Documentation</title>

</bookinfo>

<toc></toc>

<!-- Chapter: Intro -->

<chapter id="intro">

<title>Introduction</title>

<para>DrJava is a programming environment for Java, primarily intended to help students focus more on program design than on the features of a complicated development environment. DrJava also provides many advanced features for experienced developers. These features center around DrJava's Interactions Pane, which is a "read-eval-print loop" that allows users to easily develop, test, and debug Java programs in an interactive, incremental manner.</para>

<simplelist>

<member>Home Page: <ulink url="http://drjava.org">http://drjava.org</ulink></member>

<member>Original Paper: <ulink url="http://drjava.org/papers/drjava-paper.shtml">http://drjava.org/papers/drjava-paper.shtml</ulink></member>

</simplelist>

</chapter>

<!-- **** Chapter: Getting Started **** -->

<chapter id="gettingstarted">

<title>Getting Started</title>

<para>This chapter describes the basics for how to start using DrJava, including where to get the program and how to run it.</para>

<section id="gs-philosophy">

<title>Philosophy</title>

<para>The general idea behind DrJava is to provide powerful development tools that are as easy to use as possible. For this reason, we try to make DrJava easy to run and easy to understand, through a simple user interface with few panes and a legible toolbar. Meanwhile, we want to help novice users become comfortable with writing Java code by allowing them to quickly evaluate expressions in DrJava's Interactions Pane. All of our powerful features try to build on this simple and interactive interface.</para>

<para>The rest of this chapter will walk you through downloading and running DrJava, but if you have the DrJava <filename>.jar</filename> file, you can just double-click it to get started.</para>

</section>

<section id="gs-downloading">

<title>Downloading DrJava</title>

<para>You can download the newest releases of DrJava as a <filename>.jar</filename> file from our home page, <ulink url="http://drjava.org">http://drjava.org</ulink>, or directly from our <ulink url="http://sourceforge.net/project/showfiles.php?group_id=44253">Project Filelist</ulink> page on SourceForge.</para>

<formalpara>

<title>Stable, Beta and Development Releases</title>

<para>We make a distinction between Stable, Beta and Development releases of DrJava. All releases must pass our rigorous suite of unit tests and should be safe to use, but we have found that a period of beta-testing can be helpful for finding additional bugs. Any large new features are first released as a Beta release and go through a beta-testing period before being included in Stable releases, ensuring these releases are safe for all users. Our Development releases contain newer features that are under development. We believe these releases are also ready to use, but they have not been widely beta-tested, so some users may prefer to use Beta or Stable releases, or perhaps only Stable releases.</para>

</formalpara>

</section>

<section id="gs-running">

<title>Running DrJava</title>

<para>On many platforms, DrJava can be started by simply double-clicking on the <filename>.jar</filename> file you downloaded. DrJava can also be started from a command prompt, where you can optionally give it a list of source files to open at startup:</para>

<cmdsynopsis>

<command>java -jar drjava-RELEASE-DATE-rREVISION.jar</command>

<arg choice='opt'>-config [CONFIG_FILE]</arg>

<arg choice='opt' rep='repeat'>filename.java</arg>

</cmdsynopsis>

<para>Replace RELEASE-DATE-rREVISION with the appropriate value for your version of DrJava, e.g. <command>java -jar drjava-stable-20080904-r4668.jar</command>. The "config" argument is optional and allows you to specify a custom configuration file, rather than the <filename>.drjava</filename> file stored in your home directory.</para>

<formalpara>

<title>Running DrJava on Mac OS X</title>

<para>If you are using Mac OS X, you can download DrJava as an Application from our website. Download the <filename>drjava-RELEASE-DATE-rREVISION-osx.tar.gz</filename> file and decompress it. You can then copy the DrJava icon into your Applications folder or keep it on your Dock.</para>

</formalpara>

<formalpara>

<title>Running DrJava on Windows</title>

<para>If you are using Windows, you can download DrJava as an executable file from our website. Download the <filename>drjava-RELEASE-DATE-rREVISION.exe</filename> file. You can then run it like a normal Windows program.</para>

</formalpara>

</section>

<section id="gs-requirements">

<title>System Requirements</title>

<para>DrJava requires Java version 5 or later. Note that you will need to have the JDK (not the JRE) installed if you wish to use the debugger or create Javadoc within DrJava.</para>

<para>We recommend downloading and using Oracle's JDK 6 (from <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html">http://www.oracle.com/technetwork/java/javase/downloads/index.html</ulink>) for Solaris, Linux, and Windows. Other users should use the Java virtual machine that comes with their operating system (including Mac OS X).</para>

<para>Mac OS X 10.7 "Lion" does not include a default Java runtime anymore. Therefore, the operating system may prompt you to install Java if you have not installed it before. You can also download <ulink url="http://support.apple.com/kb/DL1421">Java for OS X Lion</ulink> from Apple's website, or <ulink url="http://support.apple.com/kb/index?page=search&amp;fac=Downloads&amp;q=java%20for%20os%20x&amp;src=support_site.kbase.search.advanced">search for Java downloads for Mac OS X</ulink>.</para>

<para>DrJava uses two Java Virtual Machines (one for the main program, and one for the Interactions Pane) that use Java's Remote Method Invocation (RMI) to communicate with each other. RMI uses TCP/IP as the default transport mechanism, so you must have those drivers installed. Without TCP/IP, DrJava will not start properly.</para>

<para>Note that there is an incompatibility between Java's Swing

GUI library and the Compiz window manager on Linux. We, the developers

of DrJava, cannot do anything to fix this problem. We hope that future

versions of Java and Compiz will address the incompatibility. In the

meantime, we recommend that you disable Compiz if you experience

problems. We also suggest that you use the latest versions of Compiz

and Java, so you can benefit from possible bug fixes made by Oracle and

the Compiz developers. For more information, see <ulink url="http://drjava.org/compiz/">http://drjava.org/compiz/</ulink>.</para>

</section>

<section id="gs-license">

<title>License</title>

<para>

Copyright (c) 2001-2009, JavaPLT group at Rice University (drjava@rice.edu)

All rights reserved.

</para>

<para> Redistribution and use in source and binary forms, with or

withoutmodification, are permitted provided that the following

conditions are met: </para>

<itemizedlist mark="opencircle">

<listitem>

<para>

Redistributions of source code must retain the above copyright

notice, this list of conditions and the following disclaimer.

</para>

</listitem>

<listitem>

<para>

Redistributions in binary form must reproduce the above copyright

notice, this list of conditions and the following disclaimer in the

documentation and/or other materials provided with the distribution.

</para>

</listitem>

<listitem>

<para>

Neither the names of DrJava, the JavaPLT group, Rice University, nor the

names of its contributors may be used to endorse or promote products

derived from this software without specific prior written permission.

</para>

</listitem>

</itemizedlist>

<para>

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR

CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

</para>

<para>

This software is Open Source Initiative approved Open Source Software.

Open Source Initative Approved is a trademark of the Open Source Initiative.

</para>

<para>

<literallayout>

Developed by: Java Programming Languages Team

Rice University

http://www.cs.rice.edu/~javaplt/

</literallayout>

</para>

<para>DynamicJava - Copyright (c) 1999 Dyade</para>

<para>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</para>

<para>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</para>

<para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL DYADE BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE</para>

<para>Except as contained in this notice, the name of Dyade shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from Dyade.</para>

</section>

</chapter>

<!-- Chapter: Editing Programs -->

<chapter id="editing">

<title>Editing Programs</title>

<para>DrJava's core component is an editor for writing Java source code. Like most text editors, it supports a wide range of editing features such as "Find/Replace", "Go to Line", "Go to File", while also providing more advanced features like syntax coloring, automatic indentation, brace matching, and even a limited notion of auto-completion.</para>

<section id="edit-defpane">

<title>Definitions Pane</title>

<para>The Definitions Pane is the main window of DrJava, displaying the currently active source file. As you edit files in this window, DrJava helps out with several useful features.</para>

<formalpara>

<title>Syntax Coloring</title>

<para>DrJava colors special types of text differently to help make the structure of the program more apparent. Comments appear in green, while Java keywords and types appear in blue. Strings are colored red and characters are colored magenta, with all other text colored black. These colors are all configurable (see <link linkend="configuration">Configuring DrJava</link>).</para>

</formalpara>

<para>One notable difference between syntax coloring in DrJava and other common editors (such as Emacs) is that DrJava uses <emphasis>fully correct</emphasis> coloring as the document is edited. For example, simply typing the beginning of a block comment ("/*") will immediately update the coloring of the entire document, unlike some other editors which will only update the color of a line when that line is edited. Having an accurate view of the program is an important aspect of understanding its structure.</para>

<formalpara>

<title>Automatic Indentation</title>

<para>The key to indenting code in DrJava is the <keycode>Tab</keycode> key. Rather than simply inserting a tab or spaces, pressing <keycode>Tab</keycode> properly indents the current line (or selected text) using common coding conventions. As you type multiple lines of code into the Definitions Pane, DrJava automatically indents each line using the same technique. By default, two spaces are used for each indentation level, although this can be configured in the Preferences window. (In DrJava, code is always indented with spaces, and never with actual tab characters.)</para>

</formalpara>

<formalpara>

<title>Brace Matching</title>

<para>To help you match open and close braces, DrJava highlights the region enclosed by a pair of braces. If you place the cursor immediately after a close brace, parenthesis, or bracket, all text between that character and the corresponding open brace is highlighted in another color. Like syntax coloring, brace matching is also done in a <emphasis>fully correct</emphasis> manner, updated with each keystroke. In addition, when the cursor is right after a closing curly brace, the line containing the matching open brace is displayed in the lower status bar.</para>

</formalpara>

<formalpara>

<title>Commenting / Uncommenting</title>

<para>To help you easily write multi-line comments, DrJava automatically adds spaces and an asterisk on each new line. In addition, there is an option in the "Miscellaneous" section of the Preferences window that will tell DrJava to automatically close multi-line comments for you. Commands in the Edit menu are also available to comment out or uncomment a block of selected code using winged comments ("//"). The key bindings for these commands default to <keycode>Ctrl+Slash</keycode> and <keycode>Ctrl+Shift+Slash</keycode> respectively. Commenting out a block of code will place "//" markers at the start of each line in the block, preserving the indentation of the code.</para>

</formalpara>

<formalpara>

<title>Context Menu</title>

<para>The Definitions Pane has a context menu, which can be used by right-clicking in the pane. (Mac users should use <keycode>Ctrl+Click</keycode> or <keycode>Option+Click</keycode>.) This menu provides shortcuts to useful features such as cut, copy, and paste, as well as indenting, commenting, and setting breakpoints and bookmarks.</para>

</formalpara>

<formalpara>

<title>Auto-Completion</title>

<para>DrJava supports a very limited notion of auto-completion that is nonetheless useful. This feature is accessible as "Auto-Complete Word Under Cursor" in the Edit menu, and it is also bound to the keyboard shortcut <keycode>Ctrl-Shift-Space</keycode> by default. When invoked, DrJava will look at the word to the left of the cursor and attempt to auto-complete it, based on a list of documents currently open. If there is no unique auto-completion match, DrJava displays a <link linkend="predictive-input">predictive input dialog</link> with the auto-completion candidates.</para></formalpara>

<para>When a project is open, DrJava can also be configured to scan all class files after a compile to obtain the auto-completion information (see <link linkend="configuration">Configuring DrJava</link>). With that option set, DrJava can auto-complete the names of all classes in your project, even those of inner classes.</para>

<para>On the "Auto-Complete Word Under Cursor" diaog, there is a checkbox labeled "Java API". If this is checked, then DrJava will also use the class names from the Standard Java API, JUnit 3.8.2 and the user-specified additional libraries as suggestions for auto-completion. If it is disabled, only class names from your own source files are used.</para>

<para>Next to the "OK" button is the "Fully Qualified" button. If the class "Integer" is selected, and the user presses "OK", DrJava will auto-complete the word to "Integer". If, however, "Fully Qualified" is used to close the dialog, DrJava will enter the entire fully qualified class name, "java.lang.Integer" in this case.</para>

<para>Please note that auto-completion currently only works for class names, and completely ignores all context except for the word to the left of the cursor (i.e. it may generate code that does not compile).</para>

<formalpara>

<title>Clipboard History</title>

<para>Any text you copy or cut out of DrJava documents will be placed in the clipboard history, and the last 10 entries are kept (that number is configurable, see <link linkend="configuration">Configuring DrJava</link>). To access one of the entries in the history, use the "Paste from History" command in the Edit menu or press <keycode>Ctrl+Shift+V</keycode>. In the dialog that opens up, you can browse the history and select the entry to paste. In addition to inserting the text at the cursor, the selected entry will also be moved to the top of the clipboard history, and will therefore subsequently be available with the regular paste command.</para></formalpara>

<para>The clipboard history is a great tool to minimize scrolling and document switching: Instead of going back and forth several times, you can just "copy, copy, copy" several pieces of code in a row, then go to another place in the code and do "paste, paste from history, paste from history".</para>

<formalpara>

<title>Right Margin</title>

<para>DrJava can display a line after a specified number of columns, representing the right margin of the document. By default, this line is displayed after 120 columns. You can type past this line, and it has no effect on the saved files or executed programs, but the right margin line can help you format your source code more uniformly.</para></formalpara>

<para>You can enable or disable the right margin line in the Display category of the Preferences window. The color of the line can be changed in the Colors category of the Preferences. (See <link linkend="configuration">Configuring DrJava</link>.)</para>

</section>

<section id="edit-multiple">

<title>Multiple Documents</title>

<para>Most Java programs have several closely related source files, so DrJava supports having multiple documents open at the same time. A list of all of the names of the open documents appears in a pane to the left of the Definitions Pane, listing files in the order in which they were opened. You can view and edit a particular document by selecting it in the list, or by using the Previous and Next Document commands in the Edit Menu. These commands will switch to the next for previous document in alphabetical order. (These commands have keyboard shortcuts as well: <keycode>Ctrl+Comma</keycode> and <keycode>Ctrl+Period</keycode>.) You can also press <keycode>Ctrl+Back Quote</keycode> to switch between recently active documents. This short cut is similar to Window's shortcut for switching windows. Hold down <keycode>Control</keycode> and press <keycode>Back Quote</keycode> to activate it. A small window will show the filename of the document about to be switched to. Press <keycode>Back Quote</keycode> to cycle filenames and release <keycode>Control</keycode> to switch docments.</para>

<para>The full file path of the current document is displayed both in the title bar and in the status bar at the bottom of the window.</para>

<formalpara>

<title>Context Menu</title>

<para>The Document List also has a context menu, which can be used by right-clicking on any document in the list. (Mac users should use <keycode>Ctrl+Click</keycode> or <keycode>Option+Click</keycode>.) This menu provides shortcuts to document-related commands, such as saving, reverting, printing, compiling, testing, running Javadoc, and calling the main method.</para>

</formalpara>

</section>

<section id="edit-navigation">

<title>Source Navigation</title>

<para>DrJava has many simple features to help you edit and navigate source files.</para>

<formalpara>

<title>Find/Replace</title>

<para>DrJava has a Find and Replace utility, which is conveniently displayed as one of the tabs at the bottom of the window, rather than as a dialog blocking part of the window. The tab is first displayed when you Find/Replace from the Edit Menu (or using the keyboard shortcut, <keycode>Ctrl+F</keycode>), and it can be closed by clicking on the "X" button in the upper right corner of the tab (or by hitting the <keycode>Escape</keycode> key).</para></formalpara>

<para>To search for a term, type it in the Find text field and click "Find Next" or "Find Previous" (or press <keycode>Enter</keycode>). To replace the term with another, type the new term in the Replace text field, find an occurrence using "Find Next" or "Find Previous", and then click "Replace". The "Replace/Find Next", "Replace/FindPrevious" and "Replace All" buttons help to speed up this process.</para>

<para>The "Find All" button accumulates all occurrences and displays them in a new, separate pane labeled "Find: word", where "word" is replaced with the search string. You can keep as many "Find All" panes open as you like. The panes keep the occurrences sorted by document and line number and allow you to jump to the source location with the "Go to" button, bookmark an occurrence using the "Bookmark" button, or to remove an occurrence from the list with the "Remove" button. Occurrences can also be underlined with different colors to make them easier to find in the Definitions pane.</para>

<para>There are also four checkboxes to customize each search: "Match Case","Search All Documents", "Whole Word", "No Comments/Strings", and "No Test Cases". Unchecking the first box will return case-insensitive results, checking the second box will tell DrJava to search through all of the open documents in sequence, checking the third box will ignore partial matches (i.e. it will ignore "hello" if the search text is "lo"), and checking the last box ignores instances found within comments and strings. Checking the "No Test Case" box will cause Java to ignore matches in files with test cases. Currently, this is being determined by examining the file name: If the file name ends with "Test.java", it is considered a test case and will be skilled.</para>

<para>Note that if "Search All Documents" is enabled, the search will not wrap to the beginning of the current document until all other documents have first been searched.

DrJava can also search across more than one line of text (i.e. the search string can include line breaks). For detailed instructions on its usage, see the "Find and Replace" section in the Quickstart documents under the Help menu.</para>

<para>The last checkbox is "Search Selection Only". Checking this checkbox, allows the user only to Find/Replace All and disables the Search All Documents as well as No Test Cases checkboxes. The search will be limited to a highlighted portion of the document. The Find Again option after Find All with Search Selection Only has been checked only searches within the selected region likewise. </para>

<formalpara>

<title>Go to Line</title>

<para>Selecting "Go to Line" from the Edit Menu (or hitting <keycode>Ctrl+G</keycode>) will display a dialog allowing you to scroll to a particular line number.</para>

</formalpara>

<formalpara>

<title>Go to File</title>

<para>With the "Go to File" dialog from the Edit Menu (or hitting <keycode>Ctrl+Shift+G</keycode>), you can quickly jump to another file. It will open a <link linkend="predictive-input">predictive input dialog</link>, ask you to type the name of the document, and quickly narrow down the list of candidates. You can then use the cursor keys and <keycode>Enter</keycode> to select the file you want to view.</para>

</formalpara>

<para>The "Go to File" dialog also incorporates the function of the "Go to Line" dialog: If you enter a colon (":") followed by a line number at the end of your input text, the editor will select the file and then jump to the entered line number. Example: "FooBa:123" may take you to the FooBar.java file at line 123.</para>

<formalpara>

<title>Go to File Under Cursor</title>

<para>"Go to File Under Cursor", also in the Edit Menu and bound to the shortcut <keycode>F6</keycode>), is a special form of "Go to File": It considers the word the cursor is currently on and uses it as a starting point for your search. If there is a unique match, DrJava will open that file immediately; otherwise, this feature behaves just like "Go to File".</para>

</formalpara>

<formalpara>

<title>Fast Switching</title>

<para>With Fast Switching, you can easily switch between recently active documents. Simple hold down <keycode>Control</keycode>, and press the <keycode>Back Quote</keycode> key to navigate through the filenames of recently active documents. Release the <keycode>Control</keycode> key to switch to the document with that filename. </para>

</formalpara>

<formalpara>

<title>Line Numbering</title>

<para>DrJava displays the cursor's current line number and column number on the right side of the status bar at the bottom of the window. The line number is shown on the left and starts at 1, and the column number is shown on the right and starts at 0.</para>

</formalpara>

<para>All line numbers can also be displayed in the left margin of the Definitions Pane, using the "Show All Line Numbers" option in the "Display Options" section of the Preferences window. The line number font can be changed in the "Fonts" section. (See <link linkend="configuration">Configuring DrJava</link>.)</para>

<formalpara>

<title>Bookmarks</title>

<para>DrJava allows you to bookmark places in your code that you deem important. If you have a project open, the bookmarks even get saved to and loaded from the project file. By pressing <keycode>Ctrl-Shift-M</keycode> or using the "Bookmarks" item in the Tools menu, you can display the list of bookmarks in the "Bookmarks" pane. The bookmarks are sorted by document and line number.</para></formalpara>

<para>With the <keycode>Ctrl-M</keycode> keyboard shortcut or the "Toggle Bookmark" items from the Tools menu or the Definition pane's context menu, you can add and remove bookmarks. If no text is selected, "Toggle Bookmark" will add or remove a bookmark for the entire line the cursor is on. If text is selected, the selected text is bookmarked.</para>

<para>By selecting a bookmark in the "Bookmarks" pane and pressing the "Go to" button, you can jump to the location associated with the bookmark. You can also select one or more bookmarks and remove them with the "Remove" button, or clear the entire list with the "Remove All" button.</para>

</section>

<section id="predictive-input">

<title>Predictive Input Dialogs</title>

<para>DrJava uses "predictive input dialogs" in several places, e.g. in the "Go to File" and "Open Java API Javadoc" features. This type of dialog presents you a list of candidates and allows you to quickly select one of them based on its name.</para>

<para>The top portion of the dialog displays a list of candidates that match your current choice. The text field below allows you to enter text to narrow down the list. On the bottom, there is an "OK" button to accept the current selection, a "Cancel" button to leave the dialog, and a drop-down box to choose the way candidates are selected. Matching is always done case-insensitively.</para>

<formalpara><title>Fragments</title>

<para>With this matching strategy, you can enter word fragments separated by spaces, and the list will display all the items that contain all the fragments. Example: If you enter "foo bar", the items "FooBar" and "SomeFooMooBar" will be displayed, but "Foo" or "FumBar" will not.</para></formalpara>

<formalpara><title>Prefix</title>

<para>With this strategy, only items that begin with the text entered will be displayed in the list. If you enter "foo", the items "Foo" and "FooBar" will be displayed, but "BarFoo" will not.</para></formalpara>

<formalpara><title>RegEx</title>

<para>This matching strategy allows you to enter Perl-style regular expressions (as implemented by the java.util.regex package), and the list will contain all the items that match the regular expression. As an example, the regular expression ".*" will display all items, while "[a-m].*" will display all that begin with the letters 'A' through 'M'.</para></formalpara>

</section>

<section id="detachable-panes">

<title>Detachable Tabbed Panes</title>

<para>For a long time, the Interactions Pane, the Console Pane, Find/Replace, and the Compiler and JUnit Panes were always attached to the bottom of the DrJava main frame. Users who desire the Definitions Pane to be as large as possible, or users with multi-monitor displays, may wish to use the new "Detach Tabbed Panes" option in the "Edit" menu.</para>

<para>When this option is enabled, the tabbed panes will be detached from the bottom of the main frame and displayed freely floating in their own window. The window position is saved, so it's possible to create a nice layout, quit DrJava, and have the same layout restored when DrJava is started again. Another nice side-effect is that all panes can display a lot more items without the need for scrolling. To re-attach the tabbed panes to the DrJava main frame again, simply disable the "Detach Tabbed Panes" option again.</para>

<para>The panes in the free-floating window otherwise behave exactly the same as when they are attached. It's just a different screen layout.</para>

</section>

</chapter>

<!-- Chapter: Project Facility -->

<chapter id="projects">

<title>Project Facility</title>

<section id="project-overview">

<title>Overview</title>

<para>DrJava includes a project facility for managing many files. The project facility allows you to save your open files in a project file, and reopen the project file at a later time to work on some or all of the project files.</para>

<formalpara>

<title>New Projects</title>

<para>To create a new project, either select "New" in the Project menu for a project that is initially empty, or select "Save As" in the project menu when you have one or more files already open.</para>

</formalpara>

<para>Selecting "Save As" in the Project Menu will create a new project out of the files currently open.</para>

<formalpara>

<title>Saving a Project</title>

<para>To save a project, either select "Save" in the Project menu, or select "Save As" in the Project Menu. Note that when you save the project, it only saves the list of files that are in the project, not the files themselves. Saving the project does not save the individual files that are members of the project. Use "Save All" if you wish to save all files as well as the project file to which they belong.</para>

</formalpara>

<para>Saving a project will also save which document is currently active, as well as the cursor location in every open document. It will also remember the layout of the project tree, so if some folders are collapsed when the project is saved, then the folders will be collapsed the next time the project is opened.</para>

<formalpara>

<title>Opening a Project</title>

<para>To open a project, select "Open" under the Project menu, then select a previously saved project file. You can also open previously open projects in the recent project file list in the project menu. Simply open the Project Menu and click the name of the project file to open that project.</para>

</formalpara>

<formalpara>

<title>Compiling a Project</title>

<para>There are two options for compiling a project: compiling the open project files, or compiling the entire project. To compile all open project files, select "Compile Open Project Files" under the Project menu, or right click the root of the tree and select "Compile Open Project Files." This will compile all files in the project view including auxiliary files. All files in the external branch (Under the External Files folder) will not be compiled.</para>

</formalpara>

<para>Similarly, to compile all project files, even if they are not currently open in DrJava, select "Compile Project" from the Project Menu or the Context menu for the root of the tree. This will compile every source file in the project directory as well as source files in the Auxiliary Files branch.</para>

<para>When not in project view, the "Compile All" button compiles all open files, whereas in project view, "Compile All" only compiles the open project.</para>

<formalpara>

<title>Testing a Project</title>

<para>There are two options for testing a project: testing the open project files, or testing the entire project. To test all open project files, select "Test Open Project Files" under the Project menu. This will test all JUnit test files currently open in the Source Files project branch as well as the Auxiliary Files. All files in the external branch (Under the External Files folder) will not be tested.</para>

</formalpara>

<para> To test all project files, including files not open in DrJava, choose "Test Project" in the project menu. This will search the project directory (the directory that the project file is saved in) for source files, and test any and all junit test cases it finds. This will also test all test files in the Auxiliary Files branch of the project tree.</para>

<formalpara>

<title>Running a Project</title>

<para>To run the main method of a project, select "Run Main Class" under the Project menu. This option is only available if you have specified a file containing the project's main method in the "Project Properties" dialog in the Project menu.</para>

</formalpara>

<formalpara>

<title>Create Jar File from Project</title>

<para>You can create a jar file that contains the project's source code, its compiled class files, or both by selecting "Create Jar File from Project" in the Project menu. This will display a dialog that allows you to specify the jar file's location and what gets put into it. If you are placing class files into the jar file, you can make the jar file executable by selecting "Make executable" and entering the main class. For more control over the properties of the jar, you may enter a custom manifest by selecting "Custom Manifest" and pressing the "Edit Manifest" button. You may opt to include all source files in the jar, embeded in a seperate jar, by selecting "Jar source files". You can also include all files in the project directory by selecting "Jar All files".</para></formalpara>

<para>Note that if you have not specified a build directory in the <link linkend="project-properties">Project Properties</link> all classes found in the same directory contaning the project file will included if you place class files in the jar. For class files to be included successfully you must have recently compiled the project.</para>

</section>

<section id="tree-view">

<title>Tree View</title>

<formalpara>

<title>Overview</title>

<para>

When using the project facility, the navigator pane on the left hand side of the DrJava window displays the files in a tree view, giving you a graphical representation of where the project files are located in the project directories.

Files are organized into three main branches: Source Files, Auxiliary Files, and External Files. The exact characteristics of each of these branches will be described in the following paragraphs.

</para>

</formalpara>

<para>Some of the menu items behaviors change slightly when a project is open. The "Compile All" button will compile only project Source Files instead of every open file. Likewise, "Test All" will only test the files that are in the "Source Files" and "Auxiliary Files" branches.

You can manually compile or test the other branches by right clicking on the folder and selecting "Compile Folder" or "Test Folder" respectively.</para>

<para>Only one project can be opened at a time.

</para>

<formalpara>

<title>Source Files</title>

<para>A file is categorized as a Source File if it is located at or below the directory in which the project file is saved. We call the directory that the project file is saved the "project directory." This means that the location of the project file in your filesystem will determine which Java files will be considered part of your project.</para>

</formalpara>

<formalpara>

<title>External Files</title>

<para>Files located outside of the project directory will automatically be added to the External Files branch. External Files are not compiled or tested when you compile or test the project. Also, the list of external files that are currently open is not saved in your project file.

</para>

</formalpara>

<formalpara>

<title>Included External Files</title>

<para>Included External Files are files that are located outside of the project's root directory and are explicitly added to the project. Included External Files are compiled and tested when the project is compiled or tested. Also, the list of Included External Files is saved to the project file when the project is saved.

Included External Files will also be automatically opened when the project is opened. Only a file in External Files can be moved to the Included External Files branch.</para>

</formalpara>

<para>To add an External File to the Included External Files branch, right click the filename in the External Files list and select the "Include With Project" option.

To remove a file from the Included External Files, right click the filename and select the "Do Not Include With Project" option.

</para>

</section>

<section id="project-properties">

<title>Project Properties</title>

<formalpara>

<title>Project Root</title>

<para>The project root specifies the directory that corresponds to the default package of the project. All project files should be located in this directory or one of its subdirectories.</para>

</formalpara>

<formalpara>

<title>Build Directory</title>

<para>The project facility allows the user to set a build directory where class files will be compiled. This gives the user the ability to separate source and class files. This setting is required for the "Clean Build Directory" and "Create Jar from Project" features to work correctly.</para>

</formalpara>

<para>To clean the build directory, open the Project Menu and click "Clean Build Directory." This will remove all .class files and empty directories in the build directory.</para>

<formalpara>

<title>Working Directory</title>

<para>The working directory corresponds to "current" directory of the project, i.e. <command>new File(".")</command> or <command>System.getProperty("user.dir")</command>.</para></formalpara>

<formalpara>

<title>Main Class</title>

<para>The project facility allows the user to specify a "Main Class" for your project. When the "Run Project" button is pressed or the "Run Main Class of Project" is then selected in the Project menu, the main method of the "Main Class" specified will be executed. If no "Main Class" is specified, the "Run Main Document of Project" item will not be available, and the "Run Project" button is replaced by the "Run" button that runs the main method of the current document. The "Main Class" may be specified as a file, using the file selection dialog, or as a fully qualified class name entered directly into the field. Note that to run inner classes, the name must be entered directly.</para>

</formalpara>

<formalpara>

<title>Extra Classpath</title>

<para>In the "Extra Classpath" area, you may add additional directories or jar files to the project's classpath.</para>

</formalpara>

</section>

</chapter>

<!-- Chapter: Interactions Pane -->

<chapter id="interactions">

<title>Interactions Pane</title>

<para>One of the key distinguishing features of DrJava is its Interactions Pane, which allows you to enter and evaluate Java statements and expressions on the fly. This is remarkably useful for beginning students, who no longer have to learn to write main methods, recompile, and run programs from a command line simply to test how a new class or method behaves. From a teaching standpoint, the Interactions Pane is a very easy way to help students learn to write Java without having to explain the full meaning of syntax like "public static void main", and it also provides an ideal way to perform demonstrations in class. The Interactions Pane can also be used to experiment with your own programs or new libraries, or even to create graphical user interfaces interactively.</para>

<formalpara>

<title>How to Use</title>

<para>The Interactions Pane supports the execution of any valid Java statements as well as the evaluation of Java expressions. Simply define variables and call methods as you would in an ordinary method, or even define new classes and methods and call them interactively. In general, any statement or expression ending without a semicolon will display its result in the Interactions Pane, while those ending with a semicolon will complete without displaying a result. Result objects are displayed using the object's toString() method. Any system output will be displayed in the Interactions Pane in green (as well as in the Console tab), while system errors will be displayed in red by default. Any system input will cause a box to be inserted in the Interactions Pane where you can type what you want System.in to read. This text will be colored purple. These colors can be modified in the "Colors" section in the Preferences window.</para>

</formalpara>

<para>Here is a simple interactions session, to demonstrate how the Interactions Pane can be used to experiment with objects or show GUI components.</para>

<programlisting>

Welcome to DrJava.

> String s = "Hello World";

> s

"Hello World"

> s.length()

11

> import javax.swing.*;

> JFrame frame = new JFrame("My JFrame");

> frame.show();

>

</programlisting>

<formalpara>

<title>Intelligent Newlines</title>

<para>DrJava parses your input each time Enter is pressed. If it finds that the input is not complete (unmatched braces or a missing semicolon, for example), it will automatically insert a newline, prompting you for more input on the next line. This feature makes declaring loops, methods, and classes very clean.</para>

</formalpara>

<formalpara>

<title>Resetting the Interactions Pane</title>

<para>You can reset the Interactions Pane if you wish to start from scratch or if a method call hangs and does not return. Resetting removes any variables from scope and terminates any methods running in the Interactions Pane. To do this, simply choose the "Reset Interactions" command from the Tools menu. This will also reset the Debugger and any JUnit tests that are currently running.</para>

</formalpara>

<formalpara>

<title>Running the Main Method</title>

<para>For convenience, DrJava supports calling the main method of a class in the Interactions Pane by simply entering "java" followed by the class name and any arguments. For example, to run MyClass with args "arg1" and "arg2", type the following into the Interactions Pane:</para>

</formalpara>

<programlisting>java MyClass arg1 arg2</programlisting>

<para>Note that this feature does not support passing special flags or arguments to the JVM itself, as is supported on the command line.</para>

<para>Another shortcut for this feature is the "Run Document's Main Method" command, which can be found in both the Tools menu and the context menu of the document list. This command will simply insert the appropriate <literal>"java MyClass"</literal> text into the Interactions Pane to run the current class's main method.</para>

<para>DrJava also displays either a "Run Project" or a "Run" button in its toolbar, depending on whether you have specified a "Main Class" for the project or not, respectively. "Run Project" will run the main method of the project's "Main Class", while "Run" while execute the main method of the currently open document.</para>

<para>If "Smart Run Command" option is enabled, DrJava will also run applets and ACM Java Task Force programs using the "Run" or "Run Project" buttons (see <link linkend="configuration">Configuring DrJava</link>).</para>

<para>The same smart behavior of running regular Java classes, applets and ACM Java Task Force programs can also be achieved by entering "run" followed by the class name and any arguments in the Interactions Pane. For example, to run MySomething with args "arg1" and "arg2", type the following into the Interactions Pane:</para>

<programlisting>run MySomething arg1 arg2</programlisting>

<formalpara>

<title>Running the Document as Applet</title>

<para>For users who write Java applets, DrJava has a built-in applet viewer that supports calling the <filename>run()</filename> method of a class in the Interactions Pane by simply entering "applet" followed by the class name. Any arguments will be passed to the constructor as strings. For example, to create <filename>MyApplet(String a, String b)</filename> with arguments "arg1" and "arg2" and then call the object's <filename>run()</filename> method, type the following into the Interactions Pane:</para>

</formalpara>

<programlisting>applet MyApplet arg1 arg2</programlisting>

<para>Another shortcut for this feature is the "Run Document as Applet" command, which can be found in both the Tools menu and the context menu of the document list. This command will simply insert the appropriate <literal>"applet MyApplet"</literal> text into the Interactions Pane to run the current document as applet.</para>

<formalpara>

<title>Keyboard Shortcuts</title>

<para>Many actions in the Interactions Pane have keyboard shortcuts for ease of use. Use the Up and Down arrow keys to scroll through a history of the previously entered commands, or <keycode>Ctrl+B</keycode> to clear the current command. You can also use <keycode>Shift+Enter</keycode> to insert newlines into statements in the Interactions Pane. DrJava also now supports searching backwards through history. To use this feature, type in the first few characters of the command you wish to repeat and hit the Tab key. The last command that matches the characters you typed will appear. Hitting Tab repeated searches farther back, while Shift-Tab will move you forward in the history.</para>

</formalpara>

<formalpara>

<title>Setting the Classpath</title>

<para>To interact with any class within the Interactions Pane, it must be included on the Interactions Classpath, which can include more than the user's own classpath. Any class which is opened in the Definitions Pane of DrJava is automatically added to this classpath, but additional classes and directories can be added using the "Extra Classpath" configuration option. (See <link linkend="configuration">Configuring DrJava</link>.) The current classpath of the Interactions Pane can be viewed at any time by selecting "View Interactions Classpath" from the context menu.</para>

</formalpara>

<formalpara>

<title>Saving the Interactions History</title>

<para>You can save all of your past interactions to a file at any time, using the "Save Interactions History" command in the Tools and popup menus. This command gives you the option to edit any part of the history before saving it, through a separate window that supports editing. By default, up to 500 of the most recent Interaction commands are kept in this history, though this number is configurable. Histories are saved in files with a <filename>.hist</filename> extension, and they can be later executed in the Interactions Pane with the "Execute Interactions History" command in the Tools menu. Saving and executing histories can be particularly useful for initial setup of an often repeated task, such as importing several packages and initializing frequently used variables. To help manage the history, a "Clear Interactions History" command is also provided in the Tools menu.</para>

</formalpara>

<formalpara>

<title>Loading a History File as a Script</title>

<para>You can load a history file as a script that can be executed one line at a time, using the "Load Interactions History as Script" command in the Tools and popup menus. A panel will appear on the right side of the Interactions Pane with buttons that allow you to display the previous interaction, execute the current interaction, display the next interaction, and close the panel. This feature is useful during presentations because you can step through a series of interactions that has been prepared in advance, allowing the audience to see the result of each interaction.</para>

</formalpara>

<formalpara>

<title>Lifting Interactions to Definitions</title>

<para>One common use of the Interactions Pane is to test a line of code intended for a program, even before it is written in the program itself. For example, this can be the case when experimenting with method calls to determine their results. In this situation, it is convenient to copy a working line from the Interactions Pane into the Definitions Pane. This can be done quickly with the "Lift Current Interaction to Definitions" command in the Tools menu, which simply copies the text at the current prompt and pastes it at the cursor position in the Definitions Pane.</para>

</formalpara>

<formalpara>

<title>Context Menu</title>

<para>The Interactions Pane has a context menu, which can be used by right-clicking in the pane. (Mac users should use <keycode>Ctrl+Click</keycode> or <keycode>Option+Click</keycode>.) This menu provides shortcuts to useful commands for the Interactions Pane, including cut, copy, and paste, as well as resetting the Interactions Pane, executing, loading, and saving history files, viewing the current classpath, and copying the current interaction to the Definitions Pane.</para>

</formalpara>

<formalpara>

<title>Tiger Features</title>

<para>DrJava provides support for Tiger (JDK 1.5) features in the interactions pane. These include enum types, static import, for each statements, methods with variable arguments, generics, and autoboxing. Note that you must be running Java 2, version 1.5.0 or later to use 1.5 features in the Interactions Pane. Also, DrJava does not currently type check generics, so while they may be used in the interactions pane without a syntax error, we do not yet provide full support for type checking of generics.</para>

</formalpara>

<section id="interactions-pane-system-in">

<title>System.in and Closing the Input Stream</title>

<para>Your program can ask for text input from the user by invoking <filename>System.in</filename>. You can also use the <filename>System.in.read()</filename> method in the Interactions Pane directly. When the input box appears, type your text and then either press Return.</para>

<para>You can choose to close the input stream by selecting the menu item "Tools, Interactions &amp; Console, Close System.in", or by pressing the keyboard shortcut for it, which is <filename> Ctrl-D </filename>. The shortcut is labeled <filename>Close System.in</filename> in the Key Bindings section of the preferences.</para>

<para>Here is an example of closing the input stream. The text in square brackets was entered by the user.</para>

<programlisting>

Welcome to DrJava. Working directory is /Users/Shared/drjava

> System.in.read()

[1]

49

> System.in.read()

10

> System.in.read() // press Ctrl-D now

[]

-1

>

</programlisting>

<para>The user first types '1' and then presses Return. This lets DrJava read

a 49, which is the ASCII code for the character '1', and then 10, which is the

ASCII code for the new line created by Return. In the second input box, the

user pressed Ctrl-D immediately to close the input stream. This lets DrJava

read -1, indicating of the end of the stream.</para>

</section>

<section id="interactions-pane-import">

<title>Imports in the Interactions Pane</title>

<formalpara>

<title>Auto-Import</title>

<para>When you use a class name in the Interactions Pane that is not yet known, probably because the class or its package have not been imported yet, DrJava displays an error:</para></formalpara>

<programlisting>Welcome to DrJava. Working directory is /Users/Shared/drjava

&gt; File f

Static Error: Undefined class 'File'</programlisting>

<para>At this time, DrJava will open a <link linkend="predictive-input">predictive input dialog</link> populated with all Java API classes. The initial suggestion is a class that matches the unknown class as closely as possible. After choosing the desired class, DrJava will import that class and re-execute the line that caused the error:</para>

<programlisting>Welcome to DrJava. Working directory is /Users/Shared/drjava

&gt; File f

Static Error: Undefined class 'File'

&gt; import java.io.File; // auto-import

File f

&gt; </programlisting>

<para>In the predictive input dialog, there is also a checkbox that allows you to import the entire package that contains the selected class, e.g. java.io.* instead of just java.io.File:</para>

<programlisting>Welcome to DrJava. Working directory is /Users/Shared/drjava

&gt; File f

Static Error: Undefined class 'File'

&gt; import java.io.*; // auto-import

File f

&gt; </programlisting>

<formalpara>

<title>Default Imports</title>

<para>In DrJava's preferences under "Miscellaneous", the user can add or remove classes and packages that the user would like to automatically import in the Interactions Pane whenver the pane has been reset. After the Interactions Pane has been reset, these classes and packages are immediately available.</para></formalpara>

</section>

</chapter>

<!-- Chapter: Integrated Compiler -->

<chapter id="compiling">

<title>Compiling Programs</title>

<para>Java compilers check your programs for errors and translate them to class files which can be used. Any time you change the source file for a class, it must be compiled before it can be used. To do this in DrJava, you can simply click on the "Compile All" button on the toolbar to compile any open documents. Any resulting errors will be highlighted in the document.</para>

<section id="compiling-file">

<title>Compiling Files</title>

<para>To compile the documents you have open in DrJava, click on the "Compile All" button on the toolbar, or choose either "Compile All" or "Compile Current Document" from the Tools menu. Before the compilation can begin, all open files must be saved, even if only the current document is being compiled. This is necessary because one file can depend on other files, and it is important that no files have been modified when errors are displayed. (Otherwise, an error could be highlighted on a line which has changed.) Once a compilation completes successfully, the Interactions Pane is reset so that the new class files can be used. The output on the Console Tab is also reset to begin the new session, unless the "Clear Console After Interactions Reset" option in the "Miscellaneous" section of the Preferences is unchecked.</para>

<para>In project mode, you have the option to compile all project source files, even if those files are not currently open in DrJava. To compile all source files, click "Compile Open Project Files" in the Project Menu. This option is also available by right clicking the root of the project tree.</para>

</section>

<section id="compiling-errors">

<title>Viewing Compiler Errors</title>

<para>If the compiler finds any errors in your program, DrJava displays them in the Compiler Output tab at the bottom of the window. A summary of each error is displayed in the list, including the file name and line number. You can click on any error to highlight the corresponding line in the document itself. (Note that a file will be opened automatically if it contains errors detected by the compiler.) Similarly, if the cursor is moved to a line of code that contains an error while the Compiler Output tab is displayed, that line and the corresponding error message are highlighted. You can disable highlighting compiler errors in the source by unchecking the "Highlight Source" checkbox on the Compiler Output tab, or by closing the Compiler Output tab.</para>

</section>

<section id="compiling-selecting">

<title>Selecting a Compiler</title>

<para>DrJava supports the use of different Java compilers, such as different versions of the "Javac" compiler supplied with the JDK. DrJava will attempt to locate the your Java compiler on startup by searching for standard installation directories, but sometimes it is unable to find a compiler. In this case, it will use the included Eclipse compiler instead. Note that the location of the compiler can be specified in the Preferences (see <link linkend="configuration">Configuring DrJava</link>). If more than one compiler is specified, the active compiler can be selected from a menu on the Compiler Output tab itself.

</para>

<para>DrJava will only display one compiler for each major version even though you have more than one update the JDK installed (Example: you have JDK 6 Updates 10 and 14 installed; DrJava will only display JDK 6 Update 14). If you want to display all compiler versions that were found, enable "Show all compiler versions" in the Preferences (see <link linkend="configuration">Configuring DrJava</link>).</para>

<para>The preferred compiler can also be selected permanently by setting the <link linkend="config-options-compiler">Compiler Preference</link> in the Compiler Options category of the Preferences. DrJava will then choose the selected compiler at startup.</para>

</section>

</chapter>

<!-- Chapter: JUnit Integration -->

<chapter id="junit">

<title>Testing using JUnit</title>

<para>While compilers can look for structural problems in a program, they cannot tell whether the results of a program or method are correct. Instead, all developers test their programs to ensure that they behave as expected. This can be as simple as calling a method in the Interactions Pane to view its results, but this technique requires you to think about the answers you expect every time you run any tests. A much better solution is to give the tests the answers you expect, and let the tests themselves do all the work.</para>

<para>Thankfully, a technique known as unit testing makes this quite easy. You write many small tests that create your objects and assert that they behave the way you expect in different situations. A unit test framework known as JUnit (<ulink url="http://www.junit.org">http://www.junit.org</ulink>) automates the process of running these tests, letting you quickly see whether your program returns the results you expect.</para>

<para>DrJava makes the process of running unit tests very simple by providing support for JUnit. Once you have written a JUnit test class (as described in the next section), you can simply choose the "Test Current Document" command from the Tools menu to run the tests and view the results. The name of the tests being run will be shown in the Test Output tab, with each test method turning green if it completes successfully and red if it fails. Any failures will be displayed after the list of methods in the same way as the <link linkend="compiling-errors">compiler errors</link>. A progress bar will keep you updated on how many tests have been run.</para>

<para>Also, clicking the "Test" button on the toolbar or choosing "Test All Documents" from the Tools menu will run JUnit on any open testcases, making running multiple test files very simple.</para>

<section id="junit-writing">

<title>Writing Unit Tests with JUnit</title>

<!-- Partly contributed by Chris Haynes, chaynes@indiana.edu -->

<para>With the JUnit framework, unit tests are any public classes that extend the <literal>junit.framework.TestCase</literal> class, and that have any number of methods with names beginning with the word "<literal>test</literal>". JUnit provides methods to easily assert things about your own classes, as well as the ability to run a group of tests.</para>

<para>The requirements for writing unit test classes are described below, with an example provided in the next section. In general, though, the intent is for you to create instances of your classes in the test methods, get results from any methods that you call, and assert that those results match your expectations. If these assertions pass, then your program has behaved correctly and your tests have succeeded.</para>

<formalpara>

<title>Writing a Test Case</title>

<para>To use DrJava's Test command on a document, you must use the programming conventions outlined below. You can also choose the "New JUnit Test Case" command from the File menu to automatically generate a template with these conventions.

<itemizedlist>

<listitem>

<para>At the top of the file, include:</para>

<programlisting>import junit.framework.TestCase;</programlisting>

</listitem>

<listitem>

<para>The main class of the file must:</para>

<itemizedlist>

<listitem>

<para>be <literal>public</literal></para>

</listitem>

<listitem>

<para><literal>extend TestCase</literal></para>

</listitem>

<!-- No longer necessary as of JUnit 3.8

</itemizedlist>

</listitem>

<listitem>

<para>Methods of this class to be run automatically when the Test command is invoked must:</para>

<itemizedlist>

<listitem>

<para>be <literal>public</literal> and <emphasis>not</emphasis> <literal>static</literal></para>

</listitem>

<listitem>

<para>return <literal>void</literal></para>

</listitem>

<listitem>

<para>take no arguments</para>

</listitem>

<listitem>

<para>have a name beginning with "<literal>test</literal>"</para>

</listitem>

</itemizedlist>

</listitem>

<listitem>

<para>Test methods in this class can call any of the following methods (among others):</para>

<itemizedlist>

<listitem>

<programlisting>void assertTrue(String, boolean)</programlisting>

<para>which issues an error report with the given string if the boolean is false.</para>

</listitem>

<listitem>

<programlisting>void assertEquals(String, int, int)</programlisting>

<para>which issues an error report with the given string if the two integers are not equal. The first int is the expected value, and the second int is the actual (tested) value. Note that this method can also be called using any primitives or with Objects, using their <literal>equals()</literal> methods for comparison.</para>

</listitem>

<listitem>

<programlisting>void fail(String)</programlisting>

<para>which immediately causes the test to fail, issuing an error report with the given string.</para>

</listitem>

</itemizedlist>

<para>Test methods are permitted to throw any type of exception, as long as it is declared in the "<literal>throws</literal>" clause of the method contract. If an exception is thrown, the test fails immediately.</para>

</listitem>

<listitem>

<para>If there is any common setup work to be done before running each test (such as initializing instance variables), do it in the body of a method with the following contract:</para>

<programlisting>protected void setUp()</programlisting>

<para>This method is automatically run before any tests in the class. (Similarly, you can write a <literal>protected void tearDown()</literal> method to be called after each test.)</para>

</listitem>

<listitem>

<para>If you would rather control which methods are called when running the tests (rather than using all methods starting with "<literal>test</literal>"), you can write a method to create a test suite. This method should be of the form:</para>

<programlisting>

public static Test suite() {

TestSuite suite = new TestSuite();

suite.addTest(new &lt;classname&gt;("&lt;methodname&gt;"));

...

return suite;

}

</programlisting>

<para>It is then also necessary to import <literal>TestSuite</literal> and <literal>Test</literal> from <literal>junit.framework</literal>. There is also a version of the <literal>addTest</literal> method that takes a <literal>Test</literal>, so test suites can be composed.</para>

</listitem>

</itemizedlist>

</para>

</formalpara>

<para>A simple example of a TestCase class is given in the next section. There are many other ways to use JUnit, as well. See the JUnit Cookbook at <ulink url="http://junit.sourceforge.net/doc/cookbook/cookbook.htm">http://junit.sourceforge.net/doc/cookbook/cookbook.htm</ulink> for more examples and information.</para>

</section>

<section id="junit-example">

<title>Simple Test Example</title>

<para>Suppose you are writing a Calculator class that can perform simple operations on pairs of integers. Before you even write the class, take a moment to write a few tests for it, as shown below. (By writing tests early, you start thinking about which cases might cause problems.) Then write the Calculator class, compile both classes, and run the tests to see if they pass. If they do, write a few more test methods to check other cases that you have realized are important. In this way, you can build up programs with a great deal of confidence.

<programlisting>

import junit.framework.TestCase;

public class CalculatorTest extends TestCase {

public void testAddition() {

Calculator calc = new Calculator();

// 3 + 4 = 7

int expected = 7;

int actual = calc.add(3, 4);

assertEquals("adding 3 and 4", expected, actual);

}

public void testDivision() {

Calculator calc = new Calculator();

// Divide by zero shouldn't work

try {

calc.divide(2, 0);

fail("Should have thrown an exception!");

}

catch (ArithmeticException e) {

// Good, that's what we expect

}

}

}

</programlisting>

</para>

</section>

<section id="junit-failures">

<title>Viewing Test Failures</title>

<para>If one or more test methods in a JUnit test class fails, each one is displayed in the Test Output tab at the bottom of the window. This list of failures is similar to the list of <link linkend="compiling-errors">compiler errors</link>, in that a summary of the error is given in the tab, and clicking on it highlights the corresponding line in the file (as long as the "Highlight Source" checkbox is checked). Note that DrJava displays a warning message if the test class has been modified since the last time it was compiled, since the changes will not be reflected in the behavior of the test. Closing the Test Output tab resets the current set of JUnit failures.</para>

<formalpara>

<title>Aborting Tests</title>

<para>If a suite of tests takes a long time or goes into an infinite loop, you can abort the tests by choosing the "Reset Interactions" command from the Tools menu. An error will be displayed in the Test Output tab showing that the tests were aborted.</para>

</formalpara>

<formalpara>

<title>Viewing the Stack Trace</title>

<para>When a JUnit test fails or throws an exception, it is sometimes helpful to view the entire stack trace when diagnosing the problem. To view the stack trace for any test failure, right click on the failure in the Test Output tab and select "Show Stack Trace."</para>

</formalpara>

</section>

</chapter>

<!-- Chapter: Language Level Facility -->

<chapter id="language-levels">

<title>Language Level Facility</title>

<para>The Java Language Level Facility provides a student-friendly

introduction to Java. As of April 2010, there is a single,

simplified language level called <emphasis>Functional

Java</emphasis>. When used with a complementary curriculum, this

language level forms a powerful learning tool.</para>

<para>In the past, there are three levels: <emphasis>

Elementary</emphasis>, <emphasis>Intermediate</emphasis>, and

<emphasis>Advanced</emphasis>, and each level progressively introduces

students to more Java features. Files written using these three

language levels can still be compiled, but not be created anymore. The

new Functional Java language level can compile files written for the

old Elementary and Intermediate language leves; the old Advanced level

can be compiled by the regular Java compiler.</para>

<section id="usingLL">

<title>Using the Java Language Level Facility</title>

<para>The Java Language Level Facility is fully integrated into

DrJava. To select the level at which you wish to work, click on

the "Language Levels" menu in the menu bar and select a level.

If you do not want to use any Language Level, select "Full

Java".</para>

<para> Selecting your level affects how new files are saved.

Each file's extension specifies its level. Functional Java files

are given the <emphasis>.dj</emphasis> extension; Full Java

files have the usual <emphasis>.java</emphasis>

extension.</para>

<para>In the past, files using the Elementary, Intermediate, and

Advanced Levels had the <emphasis>.dj0</emphasis>,

<emphasis>.dj1 </emphasis>, and <emphasis>.dj2</emphasis>

extensions, respectively. These files can still be loaded and

compiled, but DrJava suggests that you rename .dj0 and .dj1

files to .dj files, and .dj2 files to .java files.</para>

<para>You can reference classes defined at any language level

regardless of the level you are currently using, but you cannot

reference Full Java files (or old Advanced Level files) unless

you have first compiled them seperately.</para>

<para>Because each level is a restricted subset of Full Java,

instructors must be careful when allowing their students to

use library functions. For instance, at the Elementary level,

"null" is not a valid keyword, so functions that may return

null should not be used. Similar caution must be exercised

with arrays. Arrays are not introduced until the Advanced

level, so library functions that rely on arrays should not be

used until then. Also, although we do not allow the mutation

of fields or variables at the Elementary and Intermediate

levels, we do not prohibit the use of library classes with

their own mutation methods such as

<filename>java.util.LinkedList</filename>. Because of this,

the students and their teachers must be careful to not use

mutable datatypes. </para>

<para>Internally, the Language Level Facility translates

<emphasis>.dj</emphasis>, <emphasis>.dj0</emphasis>,

<emphasis>.dj1</emphasis> and <emphasis>.dj2</emphasis> files

to <emphasis>.java</emphasis> files with the same name. For

example, the file <filename>Example.dj</filename> creates the

hidden file named <filename>Example.java</filename>. Please

make sure that you do not have both a Java Language Level file

and a <emphasis>.java</emphasis> file with the same name, as

this would overwrite your <emphasis>.java</emphasis> file. We

also advise against opening the generated

<emphasis>.java</emphasis> files. If you do open them, DrJava

will warn you when you compile and ask you to close the

<emphasis>.java</emphasis> files.</para>

</section>

<section id="DJBreakdown">

<title>What Does the Functional Java Level Provide?</title>

<para>The Functional Java language level roughly corresponds to the old <link linkend="intermediateLL">Intermediate Level</link>. More details to follow.</para>

</section>

<section id="OldLLBreakdown">

<title>What Did the Old Levels Provide?</title>

<para> The general presentation of concepts in the old Language Levels Facility corresponds to the book <emphasis> How To Design Programs</emphasis> by Felleisen, Findler, Flatt, and Krishnamurthi. Basically, the levels provide an incremental introduction to data structures and operations on those structures while helping to simplify syntax for the students. </para>

<para> The levels are also designed to allow the introduction of <emphasis>design patterns</emphasis>--models for writing code with certain abstract behavior that are essential to teaching elegant object-oriented programming. </para>

<para> Here is a summary of what is allowed at each of the three old language levels.</para>

<mediaobject>

<imageobject>

<imagedata fileref="LanguageLevelFeatures.jpg" format="JPG" width="80%" />

</imageobject>

</mediaobject>

<para>And here is a summary of the code augmentation performed at each level.</para>

<mediaobject>

<imageobject>

<imagedata fileref="LanguageLevelAugmentation.jpg" format="JPG" width="80%" />

</imageobject>

</mediaobject>

<para>Read on for a more detailed explaination of each level.</para>

</section>

<section id="elementaryLL">

<title>The Old Elementary Level</title>

<para> The old Elementary Level provides support for programming in functional Java, which can be taught with only algebraic data types--types that are inductively defined, such as <emphasis>integers</emphasis>, <emphasis>booleans</emphasis>, <emphasis>lists</emphasis>, and <emphasis>trees</emphasis>. Because of this, only a small subset of the Java language is necessary. Most importantly, all fields and variables are immutable; in other words, they are automatically made final, so their values cannot be changed once they are set. </para>

<para> Because of this immutability of data, <emphasis>for</emphasis>, <emphasis>while</emphasis>, and <emphasis>do</emphasis> loops cannot be used at the Elementary level. We also do not allow arrays because they are commonly used with a procedural-style approach to programming (loops) rather than an object-oriented one and are inherently mutable. And since void return methods have few uses without mutable data, they are only allowed in JUnit test cases at this level. We also simplify the language for the student by not allowing <emphasis>null</emphasis> as a keyword. This protects beginning students from getting null-pointer exceptions but also means that instructors should not allow the students to use library functions that return null. In addition, interfaces are not allowed at the Elementary Level; only classes and abstract classes are allowed. By waiting to introduce interfaces until after the students are familiar with abstract classes, we hope students will have an easier time differentiating between interfaces and abstract classes. We also disallow the use of explicit access modifiers (<emphasis>final,</emphasis> <emphasis>private,</emphasis> <emphasis>static,</emphasis> etc.), and instead automatically make all fields and local variables private and all methods public. The one exception to this is that classes and methods can be denoted as <emphasis>abstract</emphasis>. We also do not allow the use of <emphasis>package</emphasis> or <emphasis>import</emphasis> statements in order to simplify the concepts that beginning students must learn. Of course, students' classes can still reference other files in the same directory, and they also have access to all classes in the <emphasis>java.lang</emphasis> package, and if students extend "TestCase" we automatically import <emphasis> junit.framework.TestCase </emphasis>for them. </para>

<para> We automatically generate a <emphasis>constructor</emphasis> for each class that students write at the Elementary Level. Each class's constructor takes a value for each of its fields, and sets the fields to those values. None of a class's fields can be set outside of the automatically generated constructor. We consider fields to be any field in the class or one of its superclasses that also has a visible accessor (a method of the same name as the field that returns its type). We automatically generate <emphasis>accessors</emphasis> for each field (for example, field my_field would have an accessor my_field()). We also generate a <emphasis>toString()</emphasis> method that returns a description of the object--its class name and field values, an <emphasis>equals()</emphasis> method that determines if two objects are equal by comparing their class types and the values for each of their fields, and a <emphasis>hashCode()</emphasis> method that follows the Java Language Specification that if two objects are equal, their hash codes are the same. Students cannot override any augmented methods at this level. </para>

<para> Although at first glance this level seems limited, even the basic functionality provided is powerful and flexible. The <emphasis>Composite,</emphasis> <emphasis>Union,</emphasis> <emphasis>Interpreter,</emphasis> and <emphasis>Factory</emphasis> patterns can all be taught at the Elementary level. </para>

</section>

<section id="intermediateLL">

<title>The Old Intermediate Level</title>

<para> At the old Intermediate level, the focus is still on functional programming with immutable data. However, there is an added twist: functions can now be used as data. Because of this, we introduce anonymous inner classes as a new construct. These anonymous inner classes can be stored in variables and passed as arguments to methods. </para>

<para> Although we allow anonymous inner classes, students still cannot use nested classes or nested interfaces at this level. They introduce a level of complexity in naming and referencing that is best deferred to the Advanced Level. </para>

<para> In addition to anonymous inner classes, several new concepts are introduced at this level. We now allow interfaces, which should be intuitive to students since they have been working with abstract classes at the Elementary Level. In addition, we allow <emphasis>package</emphasis> and <emphasis>import</emphasis> statements to broaden the scope of classes the student has access to (including the Java libraries), and to help them learn how to modularize their own projects. We allow the <emphasis>null</emphasis> keyword to be used and also allow explicit visibility specifiers such as <emphasis>public</emphasis>, <emphasis>private</emphasis>, and <emphasis>protected</emphasis> for all constructs except fields and variables, and the keyword <emphasis>static</emphasis>. However, only fields can be static at this level; static methods are still prohibited. We also introduce casts because they are useful with the <emphasis>Visitor</emphasis> design pattern--frequently the arguments to and return type of visitors is Object, and if a more specific contract for the specific function is known, the data can be cast. Students can also define their own constructors at this level, though they must make sure that all of a class's non-static fields are given a value in the constructor. Non-static fields still cannot be assigned outside of a constructor, and static fields must be given a value where they are defined. All fields are still made final.</para>

<para> The code augmentation is the same as that done at the Elementary Level, except that if a student defines a constructor that takes in all the fields of the class, we do not generate a duplicate constructor, and accessors are not generated for static fields, so static field values are not included in the constructor, equals(), toString(), and hashCode() methods. Students cannot override any autogenerated methods besides the constructor.</para>

<para> Both the <emphasis>Command</emphasis> and <emphasis>Visitor</emphasis> design patterns deal with passing functions as data and should be taught at this level. The <emphasis>Singleton</emphasis> design pattern can also be taught here. </para>

</section>

<section id="advancedLL">

<title> The Old Advanced Level </title>

<para> As students move to the old Advanced level, they are introduced to mutable data for the first time. This change in perspective allows us to make several extensions to the language. </para>

<para> The introduction of mutable data goes hand in hand with the explicit use of the <emphasis>final</emphasis> keyword--students must now mark the data they do not want to be mutable as "final". Explicit visibility modifiers may now be used for fields and variables. <emphasis>For</emphasis>, <emphasis>while</emphasis>, and <emphasis>do</emphasis> loops, as well as <emphasis>switch</emphasis> statements are now allowed, though students cannot make assignments in the conditional expression of the loops and the switch expression of the switch statement. This should help students avoid a common error of using "=" instead of "==". Students can get around this restriction by nesting the assignment in parentheses--for instance ((i=5)) rather than (i=5). <emphasis>Break</emphasis> and <emphasis>continue</emphasis> statements are also allowed because they are useful with loops. We restrict <emphasis>switch</emphasis> statements further by not allowing fall through in any switch case, including the last one, and by enforcing that if there is a default case, it must be the last case in the block. A label in a switch statement can only be a character constant, integer constant, or a negative sign followed by an integer constant--not an arbitrary constant expression. Mutable data also means that arrays are now a useful data type, so we support the use of arrays at this level. And, mutable data means that <emphasis>void</emphasis> return methods make sense in some cases, so they are also allowed.</para>

<para> The language is more flexible in other areas at this level as well. We allow non-static fields to be assigned a value where they are declared, thus giving students more freedom in what arguments need to be passed to the constructor. In addition, we allow static methods as well as static fields at the Advanced level. Nested classes and interfaces, both static and dynamic, are also supported at the Advanced level. </para>

<para> No code augmentation is done at the Advanced Level. </para>

<para> The <emphasis>Strategy</emphasis>, <emphasis>State</emphasis>, <emphasis>Decorator</emphasis>, and <emphasis>Model-View-Controller</emphasis> design patterns can all be taught at this level. </para>

<para> Please note that this final level is still under development and may not be fully functional. It will be finished soon. </para>

</section>

</chapter>

<!-- **** Chapter: Debugger **** -->

<chapter id="debug">

<title>Debugger</title>

<para>DrJava provides advanced tools for debugging your programs in the Interactions Pane. You can set breakpoints in source files in the Definitions Pane, call methods that stop at the breakpoints in the Interactions Pane, and then interact with programs while they are suspended at breakpoints. Once a breakpoint is reached, users can interact with any variables, fields, or methods that are in scope in the suspended method. Users can also resume the method call, or step through it a line at a time. Finally, the values of local variables and fields can be watched in a table as the method call progresses.</para>

<section id="debug-setup">

<title>Using the Debugger</title>

<para>To use DrJava's debugger, select the "Debug Mode" command from the Debugger menu. An informational panel will be displayed between the Definitions Pane and the Interactions Pane, and several menu items in the Debugger menu will become enabled.</para>

<formalpara>

<title>A Note on Modifying Files</title>

<para>When using the debugger, it is essential to remember that any modifications to source files will not be reflected in the behavior of the Interactions Pane or the debugger until the classes are recompiled. Changing a source file while the debugger is running is not recommended, since lines which are highlighted by the debugger may no longer correspond to the lines in the running class file. To help notify you of this danger, DrJava displays a warning message in the Debug Panel if the current document is out of sync with its class file.</para>

</formalpara>

<para>Because the debugger depends on the classes used in the Interactions Pane, the debugger is automatically reset each time any files are compiled, or when the Interactions Pane is reset.</para>

</section>

<section id="debug-breakpoints">

<title>Breakpoints</title>

<para>You can set a breakpoint on almost any line of code in a source file in the Definitions Pane, using either the "Toggle Breakpoint on Current Line" command in the Debugger menu, the "Toggle Breakpoint" command on the context (right-click) menu in the Definitions Pane, or by pressing <keycode>Ctrl+B</keycode>. When a breakpoint is set, the line will be highlighted in red and an entry will appear in the "Breakpoints" panel, which can be displayed using the "Breakpoints" command in the Debugger menu, or by pressing <keycode>Ctrl+Shift+B</keycode>. When a method is called in the Interactions Pane and the control flow reaches a line of code where a breakpoint has been set, DrJava suspends the execution of the program, highlights the line in bright blue and prints a message to the Interactions Pane. DrJava then displays a new prompt in the Interactions Pane, allowing you to interact with the suspended program until it is resumed (see <link linkend="debug-interactions">Interactions at a Breakpoint</link>). Breakpoints are considered part of a project and are therefore saved to and loaded from a project file.</para>

<para>When setting breakpoints, it is important to remember that only lines with actual executable code can be used. Blank lines and comments will never trigger a breakpoint, even if the line is highlighted in red. (Note that we do not yet support breakpoints on method contracts either, although this will be supported in a later version of DrJava.)</para>

<formalpara>

<title>Breakpoints Panel</title>

<para>The "Breakpoints" panel can be displayed using the "Breakpoints" command in the Debugger menu, or by pressing <keycode>Ctrl+Shift+B</keycode>. It lists all breakpoints that have been set in the currently open documents, sorted by document and line number. There are several buttons on the right side of the panel that help you manage the breakpoints:</para></formalpara>

<para>You can select one or more breakpoints and press the "Enable" or "Disable" button to enable or disable the selected breakpoints. When a breakpoint is disabled, it remains set, but the program will not be suspended when the breakpoint is reached. This is useful if you may need the breakpoint again later, but want the program to ignore it right now.</para>

<para>If you select exactly one breakpoint, you can use the "Go to" button to jump to the location associated with the breakpoint.</para> <para>With the "Remove" button, you can remove one or more breakpoints that you have selected. You may also clear the entire list using the "Remove All" button.</para>

<formalpara>

<title>Debugging JUnit Tests</title>

<para>DrJava will also stop at breakpoints during JUnit tests. Simply set a breakpoint on a line of a test method or in a method called by a test, and then choose the "Test Using JUnit" command from the Tools menu. When control flow reaches the breakpoint, the test will be suspended.</para>

</formalpara>

</section>

<section id="debug-interactions">

<title>Interactions at a Breakpoint</title>

<para>When DrJava reaches a breakpoint during a method call, it prints a new prompt to the Interactions Pane. This new interpreter has the context of the program which has been suspended, including all variables, fields (even "<literal>this</literal>"), and methods that are in scope in the suspended method. (The prompt text itself contains the name of the thread which has been suspended. In most cases, this name will include the text being interpreted.) You can type the name of any variable or field to view its value or assign it a new value, or you can call any method in scope to observe its behavior. Existing lines of code in the program cannot be changed or skipped, however, and the "<literal>return</literal>" keyword is not available. Any changes you make to variables or fields will be reflected in the program when it resumes execution, either by stepping or resuming.</para>

</section>

<section id="debug-step">

<title>Stepping and Resuming</title>

<para>After DrJava reaches a breakpoint, the method being called is suspended, and several commands in the Debug Menu and Debug Panel become available. Choosing "Resume" allows the current method to finish execution, at least until another breakpoint is reached. If any other threads are suspended when you resume, the Interactions Pane will switch to the most recently suspended thread. Otherwise, the original ("top level") prompt is restored. Alternatively, you can use the Step commands in the Debug menu to step through the execution of the method, one line at a time. Each time a step completes, the debugger highlights the next line of code to be executed. If the code is in another file, the debugger will look for the file on the Sourcepath and attempt to open it.</para>

<formalpara>

<title>Step Into</title>

<para>The Step Into command will walk into any method calls that occur in the code, possibly opening additional files.</para>

</formalpara>

<formalpara>

<title>Step Over</title>

<para>The Step Over command will not enter any new method calls, treating them instead as a single operation to be stepped over.</para>

</formalpara>

<formalpara>

<title>Step Out</title>

<para>The Step Out command will finish running the current method and stop at the next line of code from where the method was called.</para>

</formalpara>

<formalpara>

<title>Sourcepath and Step Options</title>

<para>The sourcepath is the set of directories in which to look for source files when stepping. It can be set in the Debugger section of the Preferences window (which can be opened from the Edit menu). This section in the Preferences also contains options for controlling which classes will be included as part of stepping. By default, DrJava will never step into its own source, nor its Java Interpreter (DynamicJava), nor Java itself. If you are interested, and have downloaded the source files, you can enable these options to see how Java or DrJava works. You can also specify which classes and packages you want to exclude when stepping. To exclude specific classes, type in the qualified class name (the package name followed by a period and the class name). To exclude entire packages (as well as their subpackages), type the package name followed by a period and an asterisk. Each class or package name must be separated by a comma.</para>

</formalpara>

<formalpara>

<title>Automatic Trace</title>

<para>The Automatic Trace command allows the user to execute periodic "Step Into" commands, by default every 1000 milliseconds. This will cause DrJava to execute the program line by line, entering called methods. After such a periodic step, the user has the option oof disabling the automatic trace by pressing the "Disable Automatic Trace" button. If the automatic trace is not disabled, the program will run its course, and the automatic trace will be turned off at the end of the program. The user can change the delay interval for stepping located in DrJava's preferences.</para>

</formalpara>

</section>

<section id="debug-panel">

<title>Debug Panel</title>

<para>The Debug Panel appears when Debug Mode is on, with several informational tabs and buttons. DrJava displays currently watched fields and variables with their values in a table in the Watches tab. The Stack tab displays the current stack trace any time a method has been suspended, and the Threads tab shows all current threads along with their status at that point in time. Most of these tabs provide context (right-click) menus for easy access to related commands, such as scrolling to a line in a stack frame, or resuming a suspended thread.</para>

<formalpara>

<title>Watching Fields and Variables</title>

<para>You can watch the values of class fields and local variables by entering the field or variable name into a row in the Watches table. Any time a method is suspended (e.g. after a breakpoint or step), the current value of the field or variable (if any) is displayed. Watches can be removed from the table by deleting the name and pressing Enter. You cannot enter expressions that need to be evaluated into the watch table. For example, "s.length" is not a valid watch entry. Type expressions like these into the Interactions Pane to see their values.</para>

</formalpara>

</section>

<section id="detachable-debugger">

<title>Detachable Debug Panel</title>

<para>When the Debug Panel is visible, it is normally attached to DrJava's main frame and displayed just above the bottom panes, and below the editor pane. To conserve screen space or make better use of dual monitors, the Debug Panel can also be detached.</para>

<para>To do this, click on the "Detach Debugger" menu item in the "Debug" menu and make sure that a checkmark appears next to "Detach Debugger". All debugger controls are now displayed in a separate window called "Debugger". To re-attach the "Debugger" window to DrJava's main frame, remove the checkmark next to "Detach Debugger" or close the "Debugger" window.</para>

</section>

</chapter>

<!-- Chapter: Javadoc Integration -->

<chapter id="javadoc">

<title>Documentation with Javadoc</title>

<para>Documenting your code is crucial to help others understand it, and even to remind yourself how your own older programs work. Unfortunately, it is easy for most external documentation to become out of date as a program changes. For this reason, it is useful to write documentation as comments in the code itself, where they can be easily updated with other changes. Javadoc is a documentation tool which defines a standard format for such comments, and which can generate HTML files to view the documentation from a web broswer. (As an example, see Oracle's Javadoc documentation for the Java libraries at <ulink url="http://download.oracle.com/javase/6/docs/api/">http://download.oracle.com/javase/6/docs/api/</ulink>.)</para>

<para>You can easily run Javadoc over your programs from within DrJava, using the "Javadoc All Documents" and "Preview Javadoc for Current Document" commands in the Tools menu. These commands will generate Javadoc HTML files from the comments you have written and display them in a browser. This chapter gives a brief overview of these commands and how to write Javadoc comments. More detailed information on writing Javadoc comments can be found online at <ulink url="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html</ulink>.</para>

<section id="javadoc-writing">

<title>Writing Javadoc Comments</title>

<para>In general, Javadoc comments are any multi-line comments ("<literal>/** ... */</literal>") that are placed before class, field, or method declarations. They must begin with a slash and two stars, and they can include special tags to describe characteristics like method parameters or return values. The HTML files generated by Javadoc will describe each field and method of a class, using the Javadoc comments in the source code itself. Examples of different Javadoc comments are listed below.</para>

<formalpara>

<title>Simple Comments</title>

<para>Normal Javadoc comments can be placed before any class, field, or method declaration to describe its intent or characteristics. For example, the following simple Student class has several Javadoc comments.</para>

</formalpara>

<programlisting>

/**

* Represents a student enrolled in the school.

* A student can be enrolled in many courses.

*/

public class Student {

/**

* The first and last name of this student.

*/

private String name;

/**

* Creates a new Student with the given name.

* The name should include both first and

* last name.

*/

public Student(String name) {

this.name = name;

}

}

</programlisting>

<formalpara>

<title>Using Tags</title>

<para>Tags can be used at the end of each Javadoc comment to provide more structured information about the code being described. For example, most Javadoc comments for methods include "<literal>@param</literal>" and "<literal>@return</literal>" tags when applicable, to describe the method's parameters and return value. The "<literal>@param</literal>" tag should be followed by the parameter's name, and then a description of that parameter. The "<literal>@return</literal>" tag is followed simply by a description of the return value. Examples of these tags are given below.</para>