DJDoc User Manual

Jens Voß


Table of Contents

1. Overview
2. Licensing
3. Requirements
4. Installation
4.1. Installation from Source
4.2. Binary Installation
5. Configuration
5.1. Central Configuration
5.2. Logging Configuration
5.3. Hibernate Configuration
5.4. Authentication Method
6. Usage
A. Tomcat configuration with ContainerBasedUserStrategy

1. Overview

DJDoc is a web application which serves as an entry point to the JavaDoc documentation of various Java APIs. The additional value DJDoc provides over the "plain" JavaDoc API documentation is that it remembers the times at which the DJDoc user has accessed the individual packages and classes/interfaces/... (by clicking the respective links in the two frames on the left side of the JavaDoc frameset) and displays a "most often used" and "most recently used" list of the respecitive package or class item list in addition to the standard list.

2. Licensing

The DJDoc API is licensed under the Gnu Lesser General Public License (LGPL).

The application uses the following APIs which are included in the distribution:

Table 1. 

ArchiveDescriptionVersionUseLicenseRemarks
junit.jarUnit testing framework3.8.1compiling (just unit tests), testing Common Public License 1.0  
servlet-api.jarServlet API2.4compiling, testingSun J2EE 1.4 license 
jsp-api.jarJSP API2.0compilingSun J2EE 1.4 license 
xercesImpl.jarXerces XML parser2.7.1generating user manual Apache Software License 2.0  
xalan.jarXalan XSLT transformer2.6.0generating user manual Apache Software License 2.0  
docbook-xsl-1.69.0.zipDocbook XSLT stylesheet library1.69.0generating user manual Docbook-XSL license  
fop.jarFOP fo processor0.20.5generating user manual Apache Software License 2.0  
batik.jarBatik SVG processor1.6generating user manual Apache Software License 2.0 Shipped with FOP
avalon-framework-cvs-20020806.jarAvalon framework4.1.2generating user manual Apache Software License 2.0 Shipped with FOP
asm.jarASM bytecode library1.5.3runtime BSD license Used by Hibernate
cglib-2.1.jarCGLIB bytecode generator2.1.0runtime Apache Software License 1.1 Used by Hibernate
commons-collections-2.1.1.jarCommons Collections2.1.1runtime Apache Software License 2.0 Used by Hibernate
commons-logging-1.0.4.jarCommons Logging1.0.4runtime Apache Software License 2.0 Used by Hibernate
dom4j-1.6.jarDOM4j XML parser1.6runtime BSD license Used by Hibernate
ehcache-1.1.jarEHCache cache provider1.1runtime Apache Software License 1.1 Used by Hibernate, may be replaced by other cache library
ejb-3.0-edr2.jarEJB 3.0 persiststence API early draft3.0-edr2compile, runtime Used by Hibernate Annotations
hibernate-annotations.jarJ2SE 5.0 annotation based persistence configuration for Hibernate3.0beta1compile, runtime Still beta!
hibernate3.jarPersistence engine3.0.3compile, runtime GNU Lesser General Public License 2.1  
hsqldb.jarHSQLDB Java database1.7.3.3runtime BSD license May be replaced by any other JDBC database
jstl.jarJavaServer Pages Standard Tag Library1.1.0runtime  
jta.jarJava Transaction API1.0.1runtime  
log4j-1.2.9.jarLogging library1.2.9compile,runtime Apache Software License 2.0  
standard.jarJakarta JSTL implementation1.1.0runtime Apache Software License 2.0  
Tidy.jarJTidy HTML parser04aug2000r7compile, runtime JTidy license  

3. Requirements

DJDoc is a JSP/servlet application, therefore a servlet container is required for running it. The application depends heavily on the JDK 5.0 language features such as metadata, so the servlet engine will have to run in a Java VM of that JDK version.

The DJDoc web application has been developed and tested exclusively with the Apache Jakarta Tomcat server version 5.5, but it should be able to run it in most standard application servers with support for Java Servlets 2.4 and JSP 2.0.

In addition to the libraries listed above, DJDoc requires a database backend supported by the Hibernate framework. These include RDBMS databases from most major vendors.

DJDoc has been developed with the open source database HSQL. It has been tested with HSQL and with MySQL (also open source).

If you intend to build the DJDoc application from the sources, you need to have Apache Ant installed. (The version used for testing and building the application on the SourceForge site is 1.6.5, but earlier versions probably should work without problems, too.) Make sure the directory containing the ant.bat resp. ant.sh script is contained in your PATH.

Finally, in order to view the API documentation supplied by the DJDoc application, a browser is needed. Since all request processing is done on the client, every web browser should work. The ones DJDoc has been tested with are Mozilla Firefox 1.0 and Microsoft Internet Explorer 6.0.

4. Installation

4.1. Installation from Source

If you have downloaded the DJDoc sources, follow these steps to install the software:

  1. Extract the source archive into a new directory and open a shell in that directory.

  2. Run the build.sh resp. build.bat script. This will invoke the Ant build utility and execute a number of build steps such as cleaning the directories, compiling the DJDoc and the unit test sources, running the tests, generating the documentation and packaging the generated classes into a WAR file.

  3. Deploy the djdoc.war file place in the dist directory your web application server. If you use the Apache Jakarta Tomcat servlet engine, this can be done by simply copying the file into the webapps directory of the Tomcat installation and starting the servlet engine.

4.2. Binary Installation

If you have just downloaded the binaries of the DJDoc application, install DJDoc by following these steps:

  1. Extract the DJDoc binary archive into a new directory.

  2. Deploy the djdoc.war file place in the dist directory your web application server. If you use the Apache Jakarta Tomcat servlet engine, this can be done by simply copying the file into the webapps directory of the Tomcat installation and starting the servlet engine.

If you have successfully installed DJDoc, the application is now ready to run with the following default settings:

  • The DJDoc API documentation itself is the only API registered in the DJDoc installation.

  • The installation uses an in-memory instance of a HSQL database.

  • The DJDoc installation uses the SameUserStrategy authentication method.

5. Configuration

After the initial installation, you may adjust the default settings by modifying the different components of the configuration as follows.

5.1. Central Configuration

The central DJDoc configuration is placed in a file named djdoc.properties which is searched in the following places (in the order listed):

  1. The home directory of the user running the web application server process.

  2. A subdirectory named djdoc of the home directory of the user running the web application server process.

  3. The web application root directory (this is where the file is located per default).

If you want to move the configuration file out of the default location (and thus out of the control of the application server), copy it to one of the places listed first and customize it.

The DJDoc configuration file contains a handful of settings that you can modify. All settings may contain placeholders of the form ${placeholder-name} where the placeholder name is either webapp.root (denoting the path of the DJDoc root dir) or the name of a system property. When the configuration settings are read, the placeholders are replaced by their respective values. (Before you try: No, this will not be done recursively!)

The settings specified in the DJDoc configuration file are:

  • log4jInitFile: This specifies the location of the Log4J initialization file.

  • hibernateInitFile: This sets the place where the configuration file for the Hibernate persistence framework is placed.

  • apiConfigDir: This is the place where documented APIs can be registered in the DJDoc application.

  • monitoringInterval: This sets the time rate (in milliseconds) at which the API configuration directory is monitored for changes. The default value is 1000.

  • userStrategyClass: Here you specify the authentication method to be used.

5.2. Logging Configuration

The DJDoc application uses the Apache Log4J logging framework (the necessary jar file is shipped with DJDoc). If you want to modify the default logging behavior, customize the Log4J configuration file specified by the log4jInitFile parameter of the central DJDoc configuration file.

For details regarding the different options for loggers, output formats and logging levels, see the Log4J documentation.

By default, the application only logs to the standard output stream, with log level INFO for all messages except those produced by loggers named org.apache.* (i.e. those used by the Jakarta Commons classes and by the Apache Log4J framework itself) which are logged with level ERROR.

5.3. Hibernate Configuration

The information about the DJDoc users and their "API access history" is stored in a relational database. The mapping of the rows of the database tables to corresponding internal Java business objects (and back) is done by the famous persistence framework, Hibernate.

Hibernate supporst a large number of (both commercial and open source) databases. DJDoc is by default configured to run with an in-memory version of the open source HSQL database. This choice requires basically no additional database configuration, but the contents of the database will be deleted every time the application is shut down.

For usage of different databases (or a different flavor of the HSQL database), see the Hibernate documentation as well as the documentation of the respective database vendor.

Typically, you will have to install a JDBC driver for the database you intend to use (normally, you will just need to place some JAR file in the WEB-INF/lib directory of the DJDoc application. The HSQL JDBC driver (named hsqldb.jar is already included in the DJDoc distribution.

5.4. Authentication Method

Since the information displayed by the DJDoc application is user specific, the system must be able to identify the user sending an HTTP request. This can be done in different ways, so-called user strategies.

The user strategy that suits your DJDoc installation depends on the usage scenario in which you intend to use the application.

You configure which user strategy is used by specifying the name of the user strategy class as the value for the userStrategyClass parameter in the central configuration file (note that this value is case-sensitive). The following options are available:

SameUserStrategy

This strategy assumes that only one user is using the DJDoc application. One row in the corresponding user database table is created on first access, and every subsequent access of a package or class item of an API is registered for that user.

This implies that while it is possible to use the system with different (human) users, every such users will see the item lists based on the cumulative access actions of all other users.

SimpleUserStrategy

This strategy allows use by multiple users without container aided authentication. It identifies the current user by a persistent cookie which is valid for one week.

This strategy is useful in scenarios where (human) users are closely tied to an individual client (i.e. a browser); for persons frequently switching workstations (or browsers on one machine), it will not be very beneficial. Moreover, the browser used will have to have cookies enabled in order for the strategy to work.

Since no user request is rejected by the system, a new user entry will be written to the database for every request without a valid cookie (this includes those with outdated cookies). Consequently, in scenarios with infrequent use, the database may well contain many outdated entries in the user tables and - probably worse - in the tables keeping track of these users' accesses to packages and items. The SimpleUserStrategy should therefore only be used in smaller scenarios.

ContainerBasedUserStrategy

This strategy makes use of the authentication functionality provided by the servlet container. It assumes that some sort of authentication mechanism is configured for the container and that a user is already authenticated by the container before a HttpServletRequest is created for that user and is handed as the first parameter to the DJDocFilter.doFilter() method where the name of the user is retrieved via the HttpServletRequest.getUserPrincipal() method.

The actual authentication mechanism used with this method thus depends on the configuration of the servlet container.

A standard scenario is a user database which is used exclusively by the servlet container. In order to avoid data duplication in such cases, DJDoc allows its own user table to be used not only for storing information about the DJDoc user's access history, but also as the container's authentication database. An example for this is provided in the Appendix A below.

6. Usage

Once the DJDoc web application is running, you may register (and unregister) additional APIs by placing an API configuration file in the API configuration directory (or removing it again from there).

The API configuration directory is the directory configured by the apiConfigDir parameter in the central DJDoc configuration file.

The name of an API configuration file must be api-name.properties where api-name is the name of the API (for safety, avoid blanks and exotic special characters like dots, slashes or backslashes in the API name).

The API configuration file must be a properties file containing key-value pairs, and must contain values for the following keys:

description

A descriptive name of the API (this gets displayed on the API list page).

path

The path of the API documentation root directory. Like the values in the central configuration file, the value of this parameter may contain placeholders (with system properties or the literal webapp.root as allowed placeholder names).

Note that changes to the content of an existing API configuration file will not be reflected in the system (neither on the fly nor on restart of the servlet engine); if you want to make changes to the settings of one API, you need to remove the corresponding configuration file and re-add it with modified contents.

On the other hand, renaming an existing API file will have an immediate effect in the system; the old API (and all dependant entries) will be removed, and the new API (with all dependant items) is added.

A. Tomcat configuration with ContainerBasedUserStrategy

We assume that we are using a DJDoc installation inside a Jakarta Tomcat 5.5 servlet engine with a MySQL backend. When the DJDoc application is initially started, the necessary tables will be created in the database. The user table will have the following structure:

mysql> describe djdoc_user;
+----------+--------------+------+-----+---------+----------------+
| Field    | Type         | Null | Key | Default | Extra          |
+----------+--------------+------+-----+---------+----------------+
| id       | int(11)      |      | PRI | NULL    | auto_increment |
| password | varchar(255) | YES  |     | NULL    |                |
| name     | varchar(255) | YES  |     | NULL    |                |
| viewPref | tinyint(4)   | YES  |     | NULL    |                |
+----------+--------------+------+-----+---------+----------------+

Note that the table contains a column named 'password'. This column is not used at all in the DJDoc application itself, but is provided only for use by the container in this case of a combined container/web application authentication.

The DJDoc users will have to be inserted manually:

mysql> insert into djdoc_user(password, name, viewPref)
    -> values ('test', 'DJDoc', 36);
Query OK, 1 row affected (0.21 sec)

Now, we create a file named djdoc.xml in the conf/Catalina/localhost subdirectory of the Tomcat installation. The file should contain the djdoc context configuration (adjust the connection parameters according to your MySQL installation):

<Context reloadable="true">
  <Realm  className="org.apache.catalina.realm.JDBCRealm"
         driverName="com.mysql.jdbc.Driver"
      connectionURL="jdbc:mysql://localhost/djdoc"
     connectionName="djdoc"
 connectionPassword="djdoc"
          userTable="djdoc_user"
        userNameCol="name"
        userCredCol="password"
      userRoleTable="djdoc_user"
        roleNameCol="'djdoc'" />
</Context>

Next, place a copy of your MySQL JDBC driver JAR file in the server/lib directory of your Tomcat installation.

Finally, edit the web.xml file of the DJDoc web application and uncomment the security-constraint and login-config elements at the end.

Then, restart Tomcat and point your browser to your DJDoc base url. You will get a login dialog in which you enter the user name and password you entered into the MySQL user table above (in the example, 'DJDoc' and 'test').