Jude is a remarkable new Java documentation system. It combines:

• The elegant quick-reference format of the bestselling book Java in a Nutshell
• The definitive API documentation from Sun Microsystems (and other API owners)
• The expressive power and flexibility of hyperlinked HTML
• The searchability and ease of use of a help browser program
• Extensive keyboard commands so you can find information quickly without tedious mousing

This guide explains how to use Jude, taking full advantage of its powerful navigation and searching features. Everyone who connects to the Jude server with a web browser should read this manual.

The separate Jude Administrator's Guide explains how to install, configure, and run Jude, and also contains copyright and legal information, a Jude revision history, and information on reporting bugs and requesting enhancements. Only the person who runs the Jude server needs to read the Jude Administrator's Guide. (If you purchased a single-user license to Jude, however, then you are both the user and the administrator and will have to read both manuals.)

Jude was written by David Flanagan. It is the copyrighted property (© 1996-2005) of David Flanagan who reserves all rights to it. If you find it useful, please purchase a license for it. Note that Jude is provided AS-IS, and is supplied with absolutely NO WARRANTY.

Connecting to Jude

http://localhost:2009

Navigating the Documentation

Jude makes it very easy to browse and navigate Java documentation and to quickly find the documentation you want. Since Jude runs in a web browser, it obviously uses hyperlinks. But it also provides pull-down menus and keyboard shortcuts for finding what you want. These are detailed in the sections below. Pay particular attention to the keyboard shortcuts. Jude was designed for quick operation with the keyboard, with a minimum of mousing.

Navigating with Hyperlinks

Jude displays hyperlinked documentation. Links are displayed in red, and the names of packages, classes, methods, and fields are almost always displayed as links. Click on a link to see complete documentation for the package, class, method, or field.

When Jude starts, it shows you a list of packages in the API you've extracted documentation for. (If you have extracted documentation for multiple APIs, it displays a list of APIs instead). When you first start using Jude, this toplevel page also displays a useful tip to help you get the most out of Jude. The keyboard shortcut 'T' returns to this top level page, and displays a new tip. (If you've used versions of Jude prior to Jude 0.99 you won't see the tips by default, unless you edit your preferences (keyboard shortcut 'R') and check the option "Display Tips".)

Click on a package, and it will show you the documentation for that package, including a list of the classes and interfaces that comprise that package.

Click on one of these and it will show you the members of the class or interface, along with javadoc documentation for the class or interface.

Click on a member, and it will show you the documentation for that particular member.

Each page of documentation Jude displays begins with a header that includes links back to the containing pages. The header also includes a one-sentence summary, and may also include additional information such as a version number.

Tooltips on Hyperlinks

Jude's hyperlinks have a couple of special features. If you hold the mouse over one of these links, a tooltip will appear providing a summary sentence from the documentation that is the target of the link.

If you hold down the Shift key while clicking on a class, interface, or method link, Jude will display a longer, more detailed tooltip. For classes and interfaces, this detailed tooltip shows the declaration of the class, including superclass and interfaces, and includes a hierarchy diagram. For methods, the detailed tooltip shows the complete method signature, with summary documentation for each method argument. Shift-clicking the link to a package or API has no effect.

Regular tooltips disappear when you move the mouse again. Detailed tooltips are dismissed when you click on them. (Note that you can click anywhere within the detailed tooltip to dismiss it. The boxed X icon is simply displayed to indicate that you can click to dismiss it.)

Tabbed Browsing

One of the powerful features of the Mozilla and Firefox browsers is their support for tabbed browsing. If you hold down the Ctrl key while clicking on any Jude link, the link will be displayed in a new tab. Suppose you are using Jude to view the documentation for a class. If you want to know more about a particular method, you can click on the method to the see method's documentation. Then you can use the Back button (or the B shortcut described below) to go back to the class documentation. Often, however, it is easier to open the method documentation in a new tab. When you are done with it, just use Ctrl-W to close the tab, and you will be returned to the tab that displays the class documentation. This is usually quicker because the Jude server does not need to re-generate the class documentation page.

If you do use multiple tabs, remember that you can use Ctrl-PageUp and Ctrl-PageDown to cycle among the tabs. Also, note that you don't have to open a new Jude tab by Ctrl-clicking on a link. You can open a new tab or new window with Ctrl-T or Ctrl-N and then simply typing the Jude URL http://localhost:2009 into the location bar. (If you bookmarked this URL it is even easier.)

Navigating Backward and Forward

You can navigate back and forward among previously-viewed Jude pages with your browser's Back and Forward buttons. As a convenience, Jude also provides these commands in its Go menu, and binds them to the B and F keys. The browser's Go menu (different from Jude's menu) also typically has a list of the most recently viewed pages, making it easy to skip backward and forward more than one page at a time.

Menu Command	Shortcut	Command
Go->Back	B	Same as the browser's Back button
Go->Forward	F	Same as the browser's Forward button

Navigating the Hierarchy

Java types and their members fall into two distinct hierarchies: a inheritance hierarchy from superclass to subclass and a containment hierarchy from package to type to member. Jude provides commands for navigating these hierarchies:

Menu Command	Shortcut	Command
Go->Up to Superclass	U	Display the superclass of the currently displayed type, or the method overridden or implemented by the currently displayed method.
Go->Out to Container	O	Display the type that contains the currently displayed member, the package that contains the currently displayed type or the API that contains the currently displayed package.
Go->Top	T	Go back to the top-level start page.

Selecting Pages By Name

If you've used Sun's javadoc documentation to look up a method in a large API, you know how tedious it can be. First, you scroll in one frame until you find the name of the package you want. Then click on it. Then scroll in another frame until you find the name of the class you want. Click on it. Then scroll again until you find the name of the method you want and click on it. It is time consuming and hard on the wrists. Jude's alternative is simple: it lets you type the name of the package, class, or member that you want, and takes you right to the appropriate documentation.

The Search menu includes four commands, with associated keyboard shortcuts, that allow you to jump directly to the documentation you want.

If you select one of these commands, or type one of the associated keyboard shortcuts, a text entry box will appear in the menubar and you will be prompted to enter the name of the package, class, interface, method, or field you are interested in.

Type it in and hit Return, and Jude will take you directly to the page you want. (Alternatively, if you change your mind, hit Escape to cancel the status line input.) If the text you enter is ambiguous (for example "List" can refer to java.util.List or java.awt.List) then Jude will take you to a page that displays a list of choices.

Menu Command	Shortcut	Description
Search->Package search	P	Jump to named package
Search->Class search	C	Jump to named class or interface
Search->Member search	M	Jump to named method or field
Search->Local search	L	Jump to a named member of the current class or interface, ignoring members with the same name in other classes. This command only works when viewing class or method documentation.

These commands are more powerful than described here: they support wildcards and auto-completion. Complete details on these commands are found in Searching below. That section also explains how to do a full-text search of the javadoc documentation itself.

Navigating within a Page

The Sections menu contains commands for navigating within a page. These commands, and their keyboard shortcuts, cause the browser to scroll directly to the named section, if the currently-displayed page has a section by that name.

Menu Command	Shortcut	Description
Sections->Hierarchy	H	Scroll to Hierarchy section
Sections->Synopsis	Y	Scroll to Synopsis section
Sections->Description	D	Scroll to Description section
Sections->Cross Reference	X	Scroll to Cross Reference section

To search within a page, use your browser's standand Ctrl-F and Ctrl-G commands. Firefox and Mozilla also typically bind the "/" key to a find-as-you-type command. Jude overrides this binding, however, because find-as-you-type does not interact correctly with Jude's other keyboard commands. Instead, Jude binds "/" to a search-in-page command that works like the C, P, and M commands described above.

View Source

Preferences

Jude's Preferences->Edit Preferences command (also available with the keyboard shortcut R) allows you to specify your preferences for what kind of information Jude should display, how that information should be organized, and how it should be styled. Simply check or un-check the checkboxes and select a stylesheet from the pulldown menu, and then click the Set Preferences button. Note that Jude uses web browser cookies to store these preferences, so if you have disabled cookies, you will be unable to change Jude's default values.

The first column of checkboxes is simply a list of sections that Jude can display. For example, if you want Jude to display the contents of javadoc @author tags, check the Authors checkbox on the preferences page. The third column of checkboxes is similar: this is a list of sub-sections within the Cross Reference section. If you don't find the "Used By" cross references useful, for example, you can un-check the Used By checkbox.

The middle column of checkboxes control the organization and content of the Synopsis section of a class or interface. The first two checkboxes in this column allow you to select a functional or alphabetical listing (or both or neither!) of class members. The default is to organize the synopsis functionally: grouping static methods separately from instance methods, grouping public methods separately from protected methods, grouping property accessor methods separately from other methods, and so on. This setting is useful when you are learning about a class, and are trying to get a feel for how it all works. The alternative is an alphabetical synopsis, in which all methods and constructors are grouped in strict alphabetical order. This setting is useful when you already understand the class, and simply want to quickly look for a named member: the use of alphabetical order makes it quicker to find what you want. (Although if you already know the name of the member you're looking for, the L keyboard shortcut to the Search->Find Local... command makes it even quicker to find what you want.) Because switching between the functional and alphabetical listing is a common thing to do, Jude provides an easy way to toggle this preference. The Preferences menu contains the command Toggle Alphabetical Synopsis, which you can access it with the keyboard shortcut A.

The remaining checkboxes in this second column of the Edit Preferences page have the following meanings:

Checkbox	Meaning
Group Property Methods	If this option is checked, then public property accessor methods (which begin with get, set and is and have the correct signatures) will be grouped in a special section of their own and listed alphabetically by property name instead of by method name. If unchecked, then property accessor methods will be grouped alphabetically with the other public methods of the class.
Group Event Methods	If this option is checked, then event registration methods (used frequently in Swing GUI packages) will be grouped in their own section, and will be listed by event name rather than method name. If unchecked, these methods will simply be listed alphabetically with other public methods of the class.
Group Interface Methods	If this option is checked, then when a class implements an interface, then the methods that implement that interface will be grouped in a sub-section of their own. If unchecked, the implementing methods will be flagged, but will be listed alphabetically with the other public methods of the class.
Group Overriding Methods	If this option is checked, then methods that override methods of a superclass will be grouped in a sub-section of their own. If unchecked, the overriding methods will be flagged, but will be listed alphabetically with the other methods of the class.
Display Deprecated Members	If checked, display deprecated members (they will be grouped at the bottom of the synopsis, and flagged with a # to indicate their deprecation). If unchecked, deprecated members will not be shown at all.
Display Protected Members	If checked, display protected members. Otherwise display only public members.
Display Package Visible Members, etc.	These options are available only if you have a Jude Pro license, and cause Jude to display types and members other than public and protected.

Jude Style Sheets

If you create a styles/ submenu of your Jude installation directory, and place other stylesheets in it, Jude will also list these stylesheets in the preferences menu. Creating a Jude-compatible stylesheet is beyond the scope of this documentation, but if you are good with CSS, you can unzip the jude.jar file to find the built-in stylesheets and use these as a guide for creating your own. User-contributed stylesheets are most welcome.

Font size

Searching

Jude has powerful searching features to help you find the documentation you're looking for. There are two distinct kinds of search that Jude can perform:

Search the API

The Package search, Class search, Member search, and Local search commands, introduced above, take you directly to a named package, class, or member. These command support wildcards, regular expressions, and can autocomplete a partially typed name.

Search the Documentation

When the Jude datafile is generated, Jude creates a complete index of all javadoc comments for the packages, classes, and members it knows about. This allows Jude to quickly find documents that contain the word or words you specify. This kind of full-text search works in much the same way that an internet search engine does.

The following sub-sections document both kind of searches.

Searching the API

Specifying Package, Class, and Member Names

The P, C, M, and L commands allow packages, classes, and members to be specified in slightly different ways.

For the P command, you simply enter a package name.

With the C, you most often will simply type an unqualified class name, such as "String". The command does allow you to specify a fully-qualified name as well, however, which is useful when the unqualified name is ambiguous. For example, to jump directly to the documentation for java.util.List, you would enter "java.util.List" to avoid the ambiguity with "java.awt.List"

The M command allows you to specify an unqualified member name, a class name followed by a member name, or a package name, a class name, and a member name. Furthermore, if the member you are interested in has an overloaded name, the M command also allows you to follow the name with a list of argument types in parentheses. For example, all of the following lines are valid input to the M command:

indexOf
String.indexOf
java.lang.String.indexOf
indexOf(String)
String.indexOf(String)

Finally, the L command works like the M command, but constrains its search to the currently displayed class or interface, or to the containing class or interface of the currently displayed member. This means that it does not allow you to qualify the member name with a class or package. You can, however, specify argument types.

Wildcards and Regular Expression Searches

In the examples we've seen so far, the input to the API search commands has always been a plain-text string. These commands also support wildcards like those used in the Unix and DOS filesystems, and even support the full power of regular expression matching.

The following characters behave as wildcards:

Character(s)	Matches
*	Any number of letters or digits, but not periods.
**	Any number of characters, including periods.
?	One letter or number, but not a period.

Note the difference between the * wildcard and the (non-standard) ** wildcard. It is useful mainly with the P command, as the following examples illustrate:

java.*     // lists java.lang, java.awt, etc.
java.*.*   // lists java.lang.reflect, java.awt.event, etc
java.**    // lists all packages beginning with "java."
java**     // lists all java and javax packages

If these wildcard characters are not flexible enough for you, the Jump commands also support full regular-expression matching. To use regular expressions, begin your search string with a slash character. Follow this character with any regular expression. You may end the search string with a matching slash character, but are not required to. If you end the search string with "/i", then the match will be case insensitive. For example, you can pass the following search string to the C command to get a list of all classes in java.lang whose name consists of two capitalized words (such as StringBuffer and ClassLoader):

/java.lang.[A-Z][a-z]+[A-Z][a-z]+/

Completion

If you do not use wildcards or regular expressions in your search strings, then Jude can save you typing by completing partially-typed package, class, and member names. To ask Jude to complete the name that you've started typing, just hit the Tab key. What happens next depends on how many completions there are.

If Jude cannot find any name that begins with what you have typed, that is, if there are not any completions, then Jude will display the message "No completions. Press TAB" Pressing Tab again clears this message and allows you to resume typing.

If there is exactly one valid completion, then Jude will display it. You can then hit the Return key to have Jude take you to the documentation for the named item.

If there is more than one valid completion, then Jude will display the longest common prefix of all such completions followed by a * wildcard character. If you type Return at this point, Jude will display a list of all valid completions. Alternatively, you can hit Tab repeatedly to cycle through the possible completions. When you find the one you want, simply hit Return and Jude will display the documentation for it. Hitting Escape once will take you back to the longest common prefix (and hitting Escape a second time will cancel the search command.)

This makes more sense if you try it out. Type C to invoke the Class search command. Then type "Strin" and the Tab key. Jude displays "String*", because there is more than one completion, and the longest common prefix is "String". Type Tab again, and the display changes to "String", because that is the full name of the first possible completion string. Hit Tab twice more and the display changes to "StringBuffer" and then to "StringBufferInputString". There are many other possible completions, but if you keep hitting Tab, you will eventually cycle back to the "String*" completion.

Searching the JavaDoc Documentation

In addition to the Jump commands this command, Jude also supports full-text queries with the Full-text Query command in the Search menu, and through the corresponding keyboard shortcut Q . The Jude data file contains a full-text index of all the javadoc documentation it contains, and Jude can search all the javadoc text in much the same way that an internet search engine does.

When you begin a full-text search, Jude asks you what to search for. You may type one or more words to search for. By default, Jude will return results that contain all of the words you enter. If you enter "thread deadlock", Jude will return matches that contain both of those words.

Case-sensitivity

Internal Words

Forbidden and Optional words

If you prefix a word with a '|' character, then it is optional. Thus, if you search for "|thread |deadlock", Jude returns results that contain either word.

Note, that the "|" prefix is a unary operator, not a binary "or" operator. If you search for "thread |deadlock", all matches are still required to have the word "thread" in them. You could get the same results simply by searching for "thread". The use of an optional term like "|deadlock" is useful to affect the scoring and ordering of matches, however. Pages that contain the required term "thread" and the optional term "deadlock" will be scored higher than those that only contain "thread".

Prefix searches

Full-text queries do not support true wildcards, but you may end a search term with a '*' character to specify that the term is a prefix and that any words that begin with that prefix should be returned. This can be useful to search for both the singular and plural forms of a word, for example. The '*' suffix can be combined with the | and - prefixes as well. For example, if you search for "deadlock -thread*", Jude will return documents that contain the word "deadlock" but that do not contain the word "thread" or any word that starts with "thread".

Document Type Constraints

For example, to search for classes whose javadoc comments include the word "deadlock", use the query "class:deadlock".

Document Section Constraints

The following table lists all allowed section constraints.

Constraint	Match only in
argname:	Method argument names
arguments:	Method argument descriptions
authors:	Authors section
deprecation:	Deprecated section
description:	Description section
exceptions:	Exceptions descriptions
name:	Package, class, or member name
returns:	Method Returns section.
link:	@see, @{link}, or @{linkplain} tag

Note that you can combine a type constraint with a section constraint. The two constraints may appear in any order, but they must both appear before the search word and after any + or - prefix. For example, the query "class:name:str*" lists classes whose name (or an internal word of whose name) begins with "str". There are a surprisingly large number of results, including StringBuffer and BufferStrategy.

Stop Words

Match Scoring

Request for Comments