Running The App

Requirements

• Java 11
• MongoDB

Installation

Windows

Download and install version 11 (or above) of the JDK, I recommend doing so via AdoptOpenJDK. Download and install MongoDB server via https://www.mongodb.com/try/download/community. I also recommend installing Compass, which is a MongoDB client.

Unix (macOS/Linux)

Open your preferred terminal and run these commands individually:

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh" # run this if you don't want to open a new terminal
sdk install java 11.0.10.hs-adpt

Follow the relevant guide here for installing MongoDB.

Verification

Verify your install works by opening a new terminal, and running java -version. It should say the java version is 11 somewhere in the message. If you installed compass, you can verify your installation by opening the app, and simply clicking connnect. You don't need to enter any text in the input box.

Usage

To run the app, simply execute the following command:

java -Xmx2G -XX:MinHeapFreeRatio=10 -XX:MaxHeapFreeRatio=15 -jar docdex.jar

Depending on the amount of javadocs you have, you'll need to adjust the maximum ram amount, as it can use a fair bit. The public instance for example, has 93 javadocs loaded, and actively uses ~1.7GB (although to an observer this will be 2GB, due to unallocated memory). The ratios there help keep the memory usage down, as without them, memory usage can inflate to insane numbers. If you want to save more memory, lower the ratios, if you want it to (potentially) go a tiny bit faster, make the ratios higher.

The speed of the population process is directly proportional to how much ram you have (and is limited by the capabilities of your CPU, assuming you're indexing more javadocs than you have cores). Basically, at start up, a number of threads is spun up depending on how much ram you give the application, and is capped at the amount of javadocs you're actually indexing. In practice, provided you have more javadocs than cores, and have allocated sufficient ram, your cpu usage should hover around 100% on all cores during indexing. If you don't want this, lower the allocated ram. The public instance has 7GB allocated (of which it uses all during indexing), and after that hovers around ~2GB.

Configuration

There are 3 main parts to the configuration, the HTTP settings, MongoDB settings, and javadoc settings. The HTTP stuff is extremely self explanatory, with a host and a port.

The Mongo section has some basic details, including the host & port, database name, and credentials. You do not need to create the database manually, docdex will do that for you. If you've never used mongo before and are only installing it for the purpose of using docdex, ignore the username and password. By default mongo is not authenticated, just make sure it's not also publicly accessible.

The javadocs section may be a bit more confusing, here's the basic schematic:

javadocs: array [
    javadoc: object {
        names: array [string "jdk", string "jdk11"],
        link: string "http://localhost/docs/jdk11/index.html",
        actual_link: string "https://docs.oracle.com/en/java/javase/11/docs/api"
    }
]

• The names include anything that the javadoc should be referenced as. The usage here would be in the index route, with the javadoc parameter. e.g. javadoc=jdk, or javadoc=jdk11.
• The link should be a link to your locally hosted instance of the javadoc you're indexing. It's absolutely essential that you localhost the javadocs, otherwise your IP may be blacklisted for an attempted DOS attack. It also probably straight up won't work. Additionally, the link needs to refer to a "no frames" version of the javadoc. If you're not sure how to achieve this, simply click the no frames button on the javadoc page. It'll be near the top, next to FRAMES, NEXT, and PREV.
• The actual link is a publicly accessible version of the same javadoc that'll be used when linking to the object in the api. This should not point to a particular index file, but rather the webroot directory of the javadoc, such as in the example above.