Table of Contents
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.
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.
Archive | Description | Version | Use | License | Remarks |
---|---|---|---|---|---|
junit.jar | Unit testing framework | 3.8.1 | compiling (just unit tests), testing | Common Public License 1.0 | |
servlet-api.jar | Servlet API | 2.4 | compiling, testing | Sun J2EE 1.4 license | |
jsp-api.jar | JSP API | 2.0 | compiling | Sun J2EE 1.4 license | |
xercesImpl.jar | Xerces XML parser | 2.7.1 | generating user manual | Apache Software License 2.0 | |
xalan.jar | Xalan XSLT transformer | 2.6.0 | generating user manual | Apache Software License 2.0 | |
docbook-xsl-1.69.0.zip | Docbook XSLT stylesheet library | 1.69.0 | generating user manual | Docbook-XSL license | |
fop.jar | FOP fo processor | 0.20.5 | generating user manual | Apache Software License 2.0 | |
batik.jar | Batik SVG processor | 1.6 | generating user manual | Apache Software License 2.0 | Shipped with FOP |
avalon-framework-cvs-20020806.jar | Avalon framework | 4.1.2 | generating user manual | Apache Software License 2.0 | Shipped with FOP |
asm.jar | ASM bytecode library | 1.5.3 | runtime | BSD license | Used by Hibernate |
cglib-2.1.jar | CGLIB bytecode generator | 2.1.0 | runtime | Apache Software License 1.1 | Used by Hibernate |
commons-collections-2.1.1.jar | Commons Collections | 2.1.1 | runtime | Apache Software License 2.0 | Used by Hibernate |
commons-logging-1.0.4.jar | Commons Logging | 1.0.4 | runtime | Apache Software License 2.0 | Used by Hibernate |
dom4j-1.6.jar | DOM4j XML parser | 1.6 | runtime | BSD license | Used by Hibernate |
ehcache-1.1.jar | EHCache cache provider | 1.1 | runtime | Apache Software License 1.1 | Used by Hibernate, may be replaced by other cache library |
ejb-3.0-edr2.jar | EJB 3.0 persiststence API early draft | 3.0-edr2 | compile, runtime | Used by Hibernate Annotations | |
hibernate-annotations.jar | J2SE 5.0 annotation based persistence configuration for Hibernate | 3.0beta1 | compile, runtime | Still beta! | |
hibernate3.jar | Persistence engine | 3.0.3 | compile, runtime | GNU Lesser General Public License 2.1 | |
hsqldb.jar | HSQLDB Java database | 1.7.3.3 | runtime | BSD license | May be replaced by any other JDBC database |
jstl.jar | JavaServer Pages Standard Tag Library | 1.1.0 | runtime | ||
jta.jar | Java Transaction API | 1.0.1 | runtime | ||
log4j-1.2.9.jar | Logging library | 1.2.9 | compile,runtime | Apache Software License 2.0 | |
standard.jar | Jakarta JSTL implementation | 1.1.0 | runtime | Apache Software License 2.0 | |
Tidy.jar | JTidy HTML parser | 04aug2000r7 | compile, runtime | JTidy license |
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.
If you have downloaded the DJDoc sources, follow these steps to install the software:
Extract the source archive into a new directory and open a shell in that directory.
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.
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 just downloaded the binaries of the DJDoc application, install DJDoc by following these steps:
Extract the DJDoc binary archive into a new directory.
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.
After the initial installation, you may adjust the default settings by modifying the different components of the configuration as follows.
The central DJDoc configuration is placed in a file named
djdoc.properties
which is searched in the
following places (in the order listed):
The home directory of the user running the web application server process.
A subdirectory named djdoc
of the home
directory of the user running the web application server
process.
The web application root directory (this is where the file is located per default).
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.
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.
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.
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:
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.
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.
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.
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:
A descriptive name of the API (this gets displayed on the API list page).
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.
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').