Jude is a remarkable new Java documentation system. It combines:
This guide explains how to use install, configure and run the Jude server. A companion document, the Jude User's Guide explains how to interact with Jude from a web browser, and how to take full advantage of Jude's powerful navigation and searching features.
Jude 0.98 also uses a completely different application architecture than previous releases. Rather than displaying XUL-based interface, driven by a large applet, Jude is now a standalone Java program that acts as a web server. As a side-effect, this version of Jude is much easier to install than previous releases.
Jude is written in pure Java, and so should run on any platform that supports Java. It has been extensively tested on Linux, and should also run on Windows and Mac OS X.
To run Jude, you need the following software installed on your system:
Jude performs adequately on a Pentium II 333Mhz laptop, and should work fine on any system more powerful than that. 128Mb of memory is required during the "juicing" step in which javadoc comments are extracted from the source code and compressed down into Jude's data file.
Jude and this User's Guide are both works in progress. If you find bugs in Jude, or find errors or omissions in this documentation, please let me know by sending e-mail to judebug@davidflanagan.com or by following the bug-reporting guidelines below.
If you find any bugs in Jude, please tell me about them. If there is a missing feature that you would find helpful, please tell me about that, too, and I'll see if I can add it. The best way to do this is to use bug-tracking system I've installed at http://www.davidflanagan.com/mantis . This system allows you to log in anonymously to view and report bugs and request enhancements. I'd appreciate it if you'd take the extra time to register for a non-anonymous account with the bug-tracking system That way, I'll be able to communicate with you about the bug if necessary.
If you're unable or unwilling to use the bug tracker system, you can e-mail your bug report to me at judebug@davidflanagan.com.
However you file your bug reports, please be sure to include relevant information about your installation: your operating system, operating system version, Java version, and browser version. Jude's "About" screen (available through the Help menu) lists this information for you.
Installing Jude is a simple process:
java -jar jude.jar -autojuiceBe sure that the java executable you invoke is part of a JDK installation. If you use the java interpreter from a standalone JRE, Jude won't automatically know what to juice and will ask you to enter the JDK directory manually.
This juicing step extracts documentation from the src.zip file that Sun ships with its JDK, and also extracts some information from Sun's javadoc files, if you have them installed in your JDK directory. The extracted documentation is compressed and stored in a file named data/java.jude in the Jude installation directory.
This step can take several minutes on slower hardware.
When you run Jude with the -autojuice option on a Mac, it will ask you where the src.zip file (or the unpacked sources directory) is installed on your system. It will also ask you where the javadoc files are installed on your system.
You are now read to run Jude and start browsing documentation.
First, be sure you've installed Jude and run it with the -autojuice option as described above.
The Jude application is a web server. Start the server with this command line:
java -jar jude.jar
When Jude is started with this simple command-line, it reads and verifies the license contained in the file jude.license, and then to reads the data files found in the data/ sub-directory of the installation directory. Finally, it starts listening for HTTP connections on port 2009.
Systems running firewall software, such as the Windows XP Firewall may pop up an alert when Jude starts listening for connections. With Windows XP, simply click the appropriate button to allow Jude to continue to run
Once the server is running, simply point your Firefox browser to it. If you are running the browser and the server on the same computer, then the URL will be http://localhost:2009. If you find yourself using Jude frequently, bookmark this URL and place it in your bookmarks toolbar. Consult the Jude User's Guide for an explanation of what you can do with Jude once you have connected to this first page.
Jude is a single program that can be invoked in a number of different ways to extract documentation from an API or to serve that documentation to web clients. The basic form of a Jude command line is:
java -jar jude.jar options datafile...
The following list summarizes the available command-line options. Note, however, that many options may not be used together. The sections that follow this list describe the different ways that Jude may be run.
If no data files are specified, Jude looks in the data/ subdirectory of the Jude installation directory and uses any files with the extension ".jude" it finds there. To explicitly specify data files, you may name individual files or the directories that contain those files.
If no port is specified, Jude uses the default 2009.
If no data files are specified, Jude uses the contents of the data/ subdirectory of the installation directory.
When specifying data files for Jude to read and serve, you may explicitly specify the .jude files, or you may specify a directory that contains .jude files. Jude will scan any directories you specify to find all .jude files they contain.
Here are examples of launching Jude in this way:
# Have Jude listen on the default HTTP port # Serve the files stored in the data/ directory java -jar jude.jar -port 80 # Read the datafile myapi.jude and serve its contents on port 2009 java -jar jude.jar myapi.jude # Read all data files in the myapis/ directory, serve them on port 8080 java -jar jude.jar -port 8080 myapis
To invoke Jude this way, type:
java -jar jude.jar -autojuice
The -autojuice option skips the java.awt.peer, java.awt.dnd.peer packages, the java.swing.plaf package and its sub-packages, and the CORBA org.omg.* packages. If you want to include these packages in the generated data file, you can run Jude with the -juice option described below.
java -jar jude.jar -juice Collections -juice Webclient
When Jude is run with -juice, it asks you a series of questions about the API or APIs you've specified. You'll be asked to specify the installation directory for each API, as well as the location of the class files, the location of the source files, and so on. When Jude has collected all the information it needs, it begins the juicing process and saves the extracted information into the data file you specified. Before it does, however, it offers to save your answers to its questions into a configuration file so that you can more easily re-juice the APIs in the future.
As an example, the following is a transcript of extracting API documentation for the ANTLR (parser generator) API. Text in bold is my input. Text in code font is computer output. Text in italics is commentary. The notation [RETURN] means hitting the Return key without entering any text.
$ java -jar jude.jar -juice ANTLR ---- First we get startup messages... Jude version 1.00 Copyright (c) 1996-2005 by David Flanagan Licensed to: David Flanagan Number of licensed users: 10 ---- Next the questions begin... The next three questions ask for the names of output files. The answers you provide are relative to the current working directory. In what file should extracted docs be stored? [antlr.jude]:[RETURN] Where should logging messages be saved? [antlr.log]:[RETURN] What is the full name of the API? [none]: ANTLR Parser Generator Where is ANTLR installed? []: /usr/local/antlr/antlr-2.7.2 What version of ANTLR is this? [1.0]: 2.7.2 If ANTLR is copyrighted enter the copyright message here in HTML: []: \ ANTLR 1989-2003 Developed by jGuru.com, http://www.ANTLR.org\ and http://www.jGuru.com. We reserve no legal rights to the ANTLR--it is\ fully in the public domain. The following questions ask for the names of files or directories. Jude works best if the answers you provide are relative to and beneath /usr/local/antlr/antlr-2.7.2: What is the classpath for ANTLR? [antlr.jar]: . Source files may be in a directory or zip file. If there are no source files, enter 'none'. Where are the source files for ANTLR? []: . If there are no javadoc files, enter 'none'. Where are the javadoc files for ANTLR? [doc]: none What character encoding is used for the source and javadoc files? [UTF-8]:[RETURN] Now enter one or more package names or patterns to specify which packages are part of this API. Begin with a minus sign to exclude a package. Begin a regular expression with a slash. You may also use ?, *, and ** wildcards. End the list with a period on a line by itself. package> antlr package> . Should package private types be included? [no]:[RETURN] Should private and default members be included? [no]:[RETURN] Should Jude call property getter methods to determine their default value? [no]:[RETURN] Do you want to create a configuration file so you don't have to enter this information again? [yes]:[RETURN] Where should the configuration file be saved? [antlr.conf]:[RETURN] Configuration file saved. ---- Now Jude starts juicing; its output is below Scanning class path for ANTLR: Reading class files for ANTLR: 100% Indexing packages: / Indexing classes: 100% Sorting index: 100% Indexing fields and methods: 100% Sorting method and field indexes: 100% Looking for overridden methods: 100% Looking for JavaBeans properties and events: 100% Cross referencing classes: 100% Sorting cross-reference lists: 100% Parsing, indexing and compressing doc comments... Reading source files for: ANTLR: 100% antlr.GrammarElement Reading package descriptions for ANTLR: 100% antlr Getting version info for classes in ANTLR: 100% Checking method argument names: 103% Writing and compressing antlr.jude: Writing class, method, and field indexes. Writing full text index...: 99% Writing class information...: 97% Saving file offsets...: done.: Your Jude data file has been written to: antlr.jude ---- Don't forget to move the generated file to the data/ directory. $ mv antlr.jude data
Jude works best when a full source tree is available for it to extract comments, method argument names and auxiliary files from.
When source files are missing, Jude will do the best it can with javadoc files. The transformation from doc comments in source files to javadoc-produced HTML files is not a fully reversible one, however, and the results will be less satisfactory.
In some cases both source and javadoc files are required for complete operation. For Sun's JDK, for example, the src.zip file contains source code for most, but not all, public classes in J2SE. Javadoc files are used for the remaining classes. Furthermore, src.zip does not include package and API-level doc comments, nor does it include auxiliary files like images. Jude gets all these from the javadoc tree, if it is available.
Jude can juice an API even if no source or javadoc files are available. The resulting .jude data file can still be used to browse the API, but it will contain no documentation and method argument names will be missing as well.
# Read jude.conf configuration file if it exists java -jar jude.jar # Read myjude.conf configuration file java -jar jude.jar -config myjude.conf
A configuration file can tell Jude to create one or more data files by juicing one or more APIs. And it may tell Jude to start one or more instances of the Jude server. If you are using Jude to browse documentation for an API that is still under active development, you can create a configuration file that will first juice the API to capture its current state, and will then launch the server.
Configuration files also offer the only way to access an advanced juicing feature available with a Jude Pro license. If you want Jude to scan old releases of an API to determine when types and members were first introduced into the API, you must create a configuration file.
Configuration file syntax is covered later in this guide.
Security
Most of the web pages that Jude serves are generated
dynamically from data contained in the data files that it is
run against. Jude also serves auxiliary files (like
JavaScript files) from its own JAR file. And it can serve
other files from your filesystem, making these file
available to anyone who can connect to the Jude server. It
is important, therefore, that you understand exactly what
files Jude can serve, so that you can guard against
inadvertent disclosure of information.
If you are simply using Jude to display public APIs such as the J2SE API, there is no danger of exposing sensitive information. If, however, you are using Jude with a proprietary API, you should be careful how you use Jude so as not to expose the source code or other sensitive information about that API. Typically, this means that you should never run Jude on an outward-facing server; always run it behind a firewall.
Jude sessions time out after 30 minutes of inactivity. That is, if you stop using Jude for half an hour, the Jude server decides that you are not an active user anymore, and your license is freed up and becomes available so that someone else can connect to the server.
If you want to end your session without waiting 30 minutes, simply use the URL "/logout":
http://judehost:2009/logoutThis is useful, for example if you have a single user license for Jude, but want to visit a colleague's desk and let them try Jude out.
Note that the Jude server does not impose any access-control restrictions beyond limiting the number of concurrent users. That is, if you are running Jude on your desktop machine, then anyone who can see your desktop can connect to the Jude server.
The <server> tag has a simpler syntax than the <juice> tag, so we'll begin with it.
Here is a simple configuration file with a single <server> tag. Its settings are equivalent to Jude's default behavior:
<jude>
<server>
<datafile>data</datafile>
<port>2009</port>
</server>
</jude>
Notice that if the <datafile> tag specifies a non-absolute file it is interpreted relative to the current working directory, not relative to the Jude installation directory, nor relative to the location of the configuration file.
Here is an configuration file with a single <server> tag containing two <datafile> tags and a <mapping> tag that relocates one of the APIs from one of the datafiles:
<jude>
<server>
<port>2009</port>
<datafile>data/java.jude</datafile>
<datafile>antlr.jude</datafile>
<mapping>
<apiname>ANTLR</apiname>
<installdir>/home/david/antlr-2.7.2</installdir>
</mapping>
</server>
</jude>
Each <api> tag specifies a single API to be juiced, and has subtags that specify all of the details required by Jude. You may find the structure of an <api> tag similar to the list of questions that Jude asks when you invoke it with the -juice command-line argument. Rather that listing each of the <api> sub-tags one by one, they are best demonstrated by example. The following Jude configuration file includes a single <juice> tag with a single <api> tag. It is intended to juice the J2SE API of the Java 5.0 JDK without excluding the CORBA classes as the -autojuice command-line option does.
Note that the filenames shown below are are Unix-style. On a Windows system, you would replace / with \, and replace the colon path separator with a semi-colon.
The most important tags within the <api> tag are <installdir>, <classpath>, <source>, <javadocdir>. The comments in the listing below explain each one. See this section above for a discussion of how Jude uses source and javadoc files. Jude works best of the <source> and <javadocdir> are relative to and descendants of the <installdir>. They should be relative to <installdir> so that the API can be remapped with the <mapping> tag described above. And descendants of <installdir> for the security reasons explained here.
<jude>
<juice>
<outputfile>data/jdk.jude</outputfile> // where to store data file
<logfile>jdk.log</logfile> // where to put juicing log
<api> // juice a single API
<name>J2SE</name> // the short name of the API
<fullname>Java 2 Standard Edition</fullname> // the long name
<version>5.0</version> // what version of the API
// This is the root installation directory for the API
<installdir>/usr/local/java</installdir>
// This is the classpath for the API.
// It can consist of JAR files and directories, separated by
// the platform-dependent path separator character.
// Relative file names are interpreted relative to the installdir
// specified above.
<classpath>jre/lib/rt.jar:jre/lib/jsse.jar:jre/lib/jce.jar</classpath>
// This tag specifies where the source code for the API is.
// This should be a single directory or zip file.
// If there is no source, leave this tag empty or omit it.
// Relative file names are interpreted relative to the installdir.
// This should be a descendant of the the installdir.
<source>src.zip</source>
// This tag specifies where the javadocs for the API are.
// This should be a directory. If there are no javadocs
// for this API, leave this tag empty or omit it
// Relative file names are interpreted relative to the installdir.
// This should be a descendant of the the installdir.
<javadocdir>docs/api</javadocdir>
// Use one or more include tags to specify which packages are
// part of the API. You may list packages individually or use
// wildcards. The * wildcard matches any characters except .
// The ** wildcard matches any characters including .
<include>java.**</include> // Any package beginning "java."
<include>javax.**</include> // Any package beginning "javax."
<include>org.**</include> // Any package beginning "org."
// Use one or more exclude tags to exclude packages from the API
<exclude>java.awt.peer</exclude> // exclude java.awt.peer
<exclude>javax.swing.plaf</exclude> // exclude this package
<exclude>javax.swing.plaf.**</exclude> // and all its sub-packages
// The following three tags control advanced options.
// You may only set them to true if you have a Jude Pro license
<includePrivateTypes>false</includePrivateTypes>
<includePrivateMembers>false</includePrivateMembers>
<queryPropertyDefaults>false</queryPropertyDefaults>
// The copyright tag is optional. It may include HTML tags and
// entities, and you can put it in a CDATA section if necessary
<copyright>
<![CDATA[Copyright © 2004 Sun Microsystems, Inc.]]>
</copyright>
</api>
</juice>
</jude>
<enumIsIdentifier>true</enumIsIdentifier>
If you want to take advantage of this feature, your <api> tag should contain one <oldrelease> tag for each release of the API prior to the current one that you are juicing. You need not go back to the 1.0 release for any given API, but the <oldrelease> tags you specify must appear in chronological order from the oldest release to the most recent release before the current one.
Each <oldrelease> tag must contain a <version> tag and a <classpath> tag. Both have the same syntax as the <version> and <classpath> tags that appear directly within the <api> tag. Note, however that the classpath specified within an <oldrelease> must use absolute filenames, since there is no <installdir> to interpret relatives paths against.
As an example, here are the <oldrelease> tags that might be added to the configuration file shown above to have Jude scan all prior releases of Sun's JDK:
<!-- Note that these tags must appear in chronological order. -->
<!-- Also note that the classpaths must use absolute files. -->
<oldrelease>
<version>1.0</version>
<classpath>/usr/local/java1.0/lib/classes.zip</classpath>
</oldrelease>
<oldrelease>
<version>1.1</version>
<classpath>/usr/local/java1.1/lib/classes.zip</classpath>
</oldrelease>
<oldrelease>
<version>1.2</version>
<classpath>/usr/local/java1.2/jre/lib/rt.jar</classpath>
</oldrelease>
<oldrelease>
<version>1.3</version>
<classpath>/usr/local/java1.3/jre/lib/classes.zip</classpath>
</oldrelease>
<oldrelease>
<version>1.4</version>
<classpath>
/usr/local/java1.4/jre/lib/rt.jar:/usr/local/java1.4/jre/lib/jsse.jar:/usr/local/java1.4/jre/lib/jce.jar
</classpath>
</oldrelease>