<?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">

<!--

User Documentation for DrJava @version $Id$

-->

<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 8 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 8 (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" and later do 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>.

Or, simply use <ulink

url="https://wiki.archlinux.org/index.php/Compton">Compton.</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.

<!-- You may notice that the same compiler may appear multiple times in the

menu. This happens because DrJava looks for compilers in three different

places: on the user classpath, the user specified location in Preferences,

and in the usual locations that the compiler can be found (the default

installation directory, where java is located, etc.). -->