Eclipse Java

Windows Path Statement

I’ll use my path statement to demonstrate a path statement for a typical Eclipse installation.

%SystemRoot%;%SystemRoot%\system32;%SystemRoot%\System32\Wbem;%SYSTEMROOT%\System32\WindowsPowerShell\v1.0;C:\Androidsdk\platform-tools;%JDK_HOME%\bin;%JAVA_HOME%\bin;%PYTHON_HOME%;%PYTHON_HOME%\Scripts;C:\Program Files (x86)\Gitcmd;C:\Program Files (x86)\Gitbin;%MinGW_HOME%/bin;%MERGEHOME%\%ANT_HOME%\bin;X:\JGSoft\Tools\HTML Tidy and XML Tidy;C:\Program Files\InteliCLS\Client;C:\Program Files (x86)\InteliCLS\Client;C:\Program Files\Intel\Intel(R) Management Engine Components/DAL;C:\Program Files\Intel\Intel(R) Management Engine Components\IPT;C:\Program Files (x86)\Intel\Intel(R) Management Engine Components\DAL;C:\Program Files (x86)\Intel\Intel(R) Management Engine Components\IPT;C:\Program Files (x86)\Windows Kits\8.0\Windows Performance Toolkit;C:\Program Files\Microsoft SQL Server\100\Tools\Binn;C:\Program Files\Microsoft SQL Server\100\DTS\Binn;C:\Program Files (x86)\Microsoft SQL Server\100\Tools\Binn;C:\Program Files (x86)\ATI Technologies\ATI.ACECore-Static;%OXYGEN_HOME%;X:\FCIV;C:\Program Files (x86)\QuickTime\QTSystem;C:\Perl64bin;C:\Perl64\site\bin


Apache Ant Java

Apache Ant Cookbook

Apache Ant is a software tool for automating software build processes (like GNU Make). I used Ant to build the Adroid version of a doc set from within the Eclipse IDE.

Note: The name Ant is an acronym that stands for Another Neat Tool.

Installation and setup

The oXygen XML Editor uses it’s own version of Ant. To get oXygen to work properly, you have to make it’s Ant installation the primary Ant installation located in C:\opt\eclipseplugins\com.oxygenxml.editor_16.1.0.v2014102117\tools\ant.

  1. Delete the standalone Ant in: C:\apache-ant-1.9.2.
  2. There’s another standalone version located in: C:\Users\Chris\.ant. Delete it.
  3. Leave Eclipse Ant in: C:\opt\eclipseplugins\org.apache.ant_1.9.2.v201404171502. You should leave this so you can set controls for it (i.e., set preferences in Eclipse). You can set it up to use oXygen’s Ant installation.

Set the environment variable

In Windows

  1. Create the new environment variable ANT_HOME=C:\opt\eclipseplugins\com.oxygenxml.editor_16.1.0.v2014102117\tools\ant.
  2. Add it to the path statement: ;%ANT_HOME%/bin.

In Eclipse

  1. In Eclipse, navigate to: Windows > Preferences > Ant > Runtime.
  2. Click Ant Home….
  3. Navigate to C:\opt\eclipseplugins\com.oxygenxml.editor_16.1.0.v2014102117\tools\ant.
  4. Click Ok, then click Apply, and then click OK.

Update the Ant installation with the latest libraries and dependencies

Open a command prompt window (with Administrative privileges), and execute the following command:

ant -f fetch.xml -Ddest=system

Note: ant.bat is the batch file that serves as the wrapper script for Windows.

Ant script structure

Ant scripts have the following structure:


Doc build timestamp

I wanted each doc build to include the time that I generated the docs. For more information, see the documentation for tstamp. To accomplish this, you use the TODAY property in your Ant project, but first you need to initialize it. You do this by adding the following statement to your Ant project.


This sets the standard DSTAMPTSTAMP, and TODAY properties according to the default formats. I added it to the init target to make its use obvious.

<target name="init" description="Ant build project setup.">
                <format property="doc_build.time_stamp" pattern="EEEE MMMM dd, yyyy 'at' h:mm:ss a z" />

Notice that I created my own property called doc_build.time_stamp.


I use my new doc build timestamp property inside the target that I created for building the HTML docs.

<property name="javadoc.footer" value="&lt;strong&gt;Built:&lt;/strong&gt;&#09;${doc_build.time_stamp}." />


build.xml is the default name used by Ant for the Ant project file.

My build.xml

Here’s the XML in my build.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<project name="3rdParty Mobile SDK" default="HTML Docs" basedir=".">

        <property name="src.dir"        value="${basedir}/src"/>
        <property name="dest.dir"       value="${basedir}/doc"/>
        <property name="lib.dir"        value="${basedir}/lib"/>

        <path id="classpath">
                <fileset dir="${lib.dir}" includes="**/*.jar"/>

        <target name="init" description="Ant build project setup.">
                        <format property="doc_build.time_stamp" pattern="EEEE MMMM dd, yyyy 'at' h:mm:ss a z" />

        <target name="HTML Docs" depends="init" description="Compile the HTML version of the docs.">
                <property name="javadoc.header" value="&lt;strong&gt;3rdParty Mobile SDK&lt;/strong&gt;&#09;v1.0" />
                <property name="javadoc.footer" value="&lt;strong&gt;Built:&lt;/strong&gt;&#09;${doc_build.time_stamp}." />
                <property name="javadoc.bottom" value='Copyright &amp;copy; 2013 - &lt;script&gt; var currYear=new Date(); document.write(currYear.getFullYear()); &lt;/script&gt;, 3rdParty Corp., All rights reserved.' />

                  additionalparam=" -noqualifier "
                  doctitle="3rdParty Mobile SDK Documentation"
                  windowtitle="3rdParty Mobile SDK for Android"
                        <link href=""/>



JavaDoc Generation


In Eclipse, run the Generate Javadoc command (Project > Generate Javadoc).

When you run the Javadoc Generator in Eclipse, a Wizard walks you through setting-up the job.

The Wizard consists of three pages.

Online Docs for the Javadoc Wizard

Javadoc Generator Settings

Note: I recommend that you use Eclipse’ Javadoc generator (Project > Generate Javadocs), and enable the option for it to automatically create a build.xml ant build file. Then open that build file in EditPad Pro, and customize it to your needs. See the build file in the java_3rdParty project for a prototype example.


Note: JDK_HOME = C:Program FilesJavajdk1.7.0_21

Make sure the Windows Environment Variable PATH contains the directory that contains the javadoc.exe executable file (i.e., %JDK_HOME%bin).

This expands to: C:Program FilesJavajdk1.7.0_21binjavadoc.exe

Note: This won’t expand in the Generate Javadoc dialog box, but you can click Configure, and get the path to expand (%JAVA_HOME%\bin\).

Uncheck, and then re-check “src”. This ensures that every subpackage is checked (just one subpackage is checked by default).

Each option (Private, Packatge, Protected, and Public) is a superset of the options to its right. So select Private, and you get Package, Protected, and Public.

I like this option because it’s nice to see explanations for the private helper methods.

Use this option to generate the default doc style.

Destination: C:\Users\Chris\src\java_3rdParty\doc

Choose this option to generate docs using a different document generation algorithm. For example, you can specify a doclet that generates the docs in PDF form.

See the doclets available for download.

JELDoclet is a doclet that exports the contents of the Javadoc system as XML instead of HTML.

** See if you can create as XSLT with oXygen XML Editor, to generate a custom version of the docs.

Check this option.

I used the title: 3rdParty Java SDK Documentation

I checked all of the options, except @deprecated.

When you set this up properly, it makes your docs more user friendly, I turns all of the data types in your docs into hyperlinks to the external Javadocs for each particular referenced API.

Ideally, you want all of these checked. For the ones that are unchecked (and are labelled “not configured”), search the Internet for the name of the jar. One of the hits will contain the URL for the Javadocs generated for the API. Enter that URL, minus the terminating html file, into the Browse dialog, and click Validate. If it validates successfully, then click OK, and then check the check box beside the archive item.


Javadoc relies on a file called package-list to identify the location of Javadocs – beneath a given directory. For some reason, such a file is missing for Therefore the “approach -link doesn’t work (you get a warning that the package-list could not be retrieved and no links are generated into your docs). Note that the checkboxes in that 2nd eclipse dialog just assemble -link parameters for you, so that doesn’t really make any difference.

However, Javadoc offers the -linkoffline parameter as a workaround for this situation. It allows you to link to online Javadoc documentation, that you can’t access at the time of generating your own docs. Here’s how it works: While -link takes only one parameter (the URL of the JavaDoc docs you want to link to), -linkoffline takes a second one – the location of the package-list file.

So, to link to the online Android reference documentation, you should not select any checkboxes in the 2nd eclipse dialog, but instead add

-linkoffline file://C:/opt/android-sdks/docs/reference

in the Extra Javadoc options in the 3rd dialog.

That way you use the package-list of your locally installed Android docs, but the links in your generated Javadoc will actually point to the online version.

I guess this must be where you can apply your custom stylesheet to the docs.

Experiment with this. Try opening the docset in Dreamweaver, and then adding your own style sheet on top of the default one.

Check the Overview checkbox.

Use the path: C:\Users\Chris\src\java_3rdParty\overview.html

As far as I can tell, you can leave this field blank.

This truncates the full path names of the io members, leaving just the class name (like the using statemenmt in C#).


** When you use this option, the settings are stored in an Ant script named javadoc.xml, that you can resuse to perform the specified Javadoc export without the need to use the wizard.

Existing Ant script can be modified with this wizard (Use Open Javadoc wizard’ from the context menu on the generated Ant script)

Ant Script: C:\Users\Chris\src\java_3rdParty\javadoc.xml

  1. In Eclipse, Window > Open View > Other > Ant.
  2. Drag & drop the Ant build file from the Project Explorer into this Ant View pane.
  3. In the Ant view pane, double-click the target script.
  1. In Eclipse, in the Project Explorer, right-click the Ant build file (build.xml or javadoc.xml).
  2. Click Open in…
  3. Select the XML Editor.

This gives you two views into the Ant script.


Ant Script

<?xml version=”1.0″ encoding=”UTF-8″?>

<!– For info about what these attributes mean, see: –>

<project name=”3rdParty SDK for Android” default=”HTML Docs” basedir=”.”>

<property name=”src.dir” value=”${basedir}/src”/>

<property name=”dest.dir” value=”${basedir}/doc”/>

<property name=”lib.dir” value=”${basedir}/lib”/>

<path id=:classpath”>

<fileset dir=”${lib.dir}” includes=”





<target name=”init” description=”Ant build project setup.”>
<format property=”doc_build.time_stamp” pattern=”EEEE MMMM dd, yyyy ‘at’ h:mm:ss a z” />



<target name=”HTML Docs” depends=”init” description=”Compile the HTML version of the docs.”>

<property name=”javadoc.header” value=”&lt;strong&gt;3rdParty SDK for Android&lt;/strong&gt;&#09;v1.0” /> <property name=”javadoc.footer” value=”&lt;strong&gt;Last updated on:&lt;/strong&gt;&#09;${doc_build.time_stamp}.” /> <property name=”javadoc.bottom” value=’Copyright &amp;copy; 2013 – &lt;script&gt; var currYear=new Date(); document.write(currYear.getFullYear()); &lt;/script&gt;, 3rdParty Corp., All rights reserved.’ />


access=”public” additionalparam=”-bootclasspath C:Androidsdkplatformsandroid-19android.jar -noqualifier” author=”true” destdir=”${dest.dir}” doctitle=”3rdParty SDK for Android” windowtitle=”3rdParty SDK for Android” nodeprecated=”true” nodeprecatedlist=”true” noindex=”false” nonavbar=”false” notree=”false” overview=”${basedir}/overview.html” packagenames=”com.3rdParty.sdk” source=”7” sourcepath=”${src.dir}” splitindex=”true” use=”true” version=”true”>

<link href=”“/> <link offline=”true” href=”” packagelistloc=”C:/Android/sdk/docs/reference”/> <header><![CDATA[${javadoc.header}]]></header> <footer><![CDATA[${javadoc.footer}]]></footer> <bottom><![CDATA[${javadoc.bottom}]]></bottom>




Check this checkbox to see the doc web page in its own window inside Eclipse.

If you already have a browser instance open – displaying the docs from the last export, then don’t check this checkbox. Simply refresh the page displayed in the browser.


First-time Generation of the Docs

  1. In Eclipse, click Project > Generate Javadoc. Run Javadoc using the defaults for Destination: “C:\Users\Chris\src\java_3rdParty\doc”.
  • Javadoc command: ;%JDK_HOME%\bin\javadoc.exe.
  • For the types for which Javadoc will be generated, check everything under “src”. I.e., deselect everyting under “test”.

Customizing the Docs

The Javadoc tool generates output originating from four different types of source files:

Java language source files for classes Package comment files Overview comment files Miscellaneous unprocessed files

Sample Javadoc comment block

/** 3rdParty Java SDK
 * This Java package wraps the 3rdParty web service.
 * @package
 * @author     cboorman
 * @copyright  Copyright © 2020, 3rdParty Corporation.
 * @license The MIT License (MIT).
 * @version    1.0
 * @maintainer Git Administrator
 * @link
 * @email      Support <>


Apache Ant Java

Apache Ant

ANT is the Java equivalent of Make. Once you create a javadoc.xml file, you can use it to generate the Javadocs instead of having to go through the Javadoc Gererating Wizard in Eclipse.

Environment Variable and PATH for Eclipse’s version of Ant

ANT_HOME=C:\Program Files\eclipse\plugins\org.apache.ant_1.8.3.v20120321-1730

Eclipse Ant Editor and Ant Viewer

Eclipse has two very cool features for building and running Ant files.

  1. In Eclipse, click Window > Show View > Ant.
  2. In the new Ant window, right-click on the root folder item, and click open in XML Editor. Eclipse’s built-in XML Editor displays syntax-formatted XML, and has a cool Design tab feature that allows you to manipulate the entities.

The Latest Version of Ant

You don’t have to download and install Ant. It’s bundled with Eclipse (albeit, its an not the latest version of Ant – v1.7). At the time of this writing, the latest version of Ant is v1.8.4.

If you install it, you’ll get a warning message when you try to change the Ant configuration in Eclipse (Windows > Preferences > Ant > Runtime > Ant Home…) – to point to the new ANT_HOME. Apparently the new installation is missing “tools.jar”, which Eclipse needs.

In Eclipse, Windows > Preferences > Ant; “Some tasks, such as “javac”, require the tools.jar library to be on the Ant runtime classpath to execute successfully.”

  1. To fix this, in Eclipse, navigate to Windows > Preferences > Ant > Runtime > Classpath > Global Entries.
  2. Click “Add external Jars…”.
  3. Type “C:\Program Files\Java\jdk1.7.0_21\lib\tools.jar”, and click “Open”.

Download and Install

At the time of this writing, the latest version of Ant is apache-ant-1.9.1.

  1. Download Apache Ant, and extract the zip file to C:\. It’ll end up with in C:\apache-ant-1.9.1.
  2. Set the “ANT_HOME” environment variable to “C:\apache-ant-1.9.1”.
  3. Path ;%ANT_HOME%\bin Make sure that you also the JAVA_HOME environment variable set to the JDK. This is required for running Ant. ..Note: You’d think that JAVA_HOME should point to the JRE, not to the JDK, but apparently that’s not the case. It should point to the JDK.
  4. Check your installation by opening a command line and typing “ant -version” into the commend line. The system should find the command ant and show the version number of your installed Ant.

I did this, and I got the following error:

“C:\Users\Chris>ant -version
Unable to locate tools.jar. Expected to find it in %JDK_HOME%\lib\tools.jar Apache Ant(TM) version 1.9.1 compiled on May 15 2013”

I fixed it by simply copying C:\Program Files\Java\jdk1.7.0_21\lib\tools.jar to C:\Program Files\Java\jre7\lib\.

Using Ant to build the docs from the Command Line

  1. Open a command prompt.
  2. Type: C:\Users\Chris\src\java_3rdParty>ant -f javadoc.xml

Using Ant to build the docs from the Run dialog

  1. Open the Run dialog by pressing the Windows Key + R (on the Kinesis Advantage keyboard, that’s Right Alt + R).

  2. Paste the following command line into the Open field, and the click OK.

    %ANT_HOME%\bin\ant -F %USERHOME%\src\java_3rdParty\javadoc.xml

  3. When the Permission dialog appears, just click OK.


Eclipse – the Java IDE

Installing Eclipse

  1. Setup an Environment Variable for Eclipse called:

    JAVAHOME=C:\\Program Files\\Java\\jdk1.7.0_21.

    I noticed that this points to the JDK, although the name insinuates that it points to the JRE home. Strange…

  2. Path it:


Install point:

Update: There is now an SR2 release. I therefore downloaded:

Note: You can also FTP to it:

  1. Unzip to C:\Program files\. The executable will then be: “C:\Program Files\eclipse\eclipse.exe”

Note: Just click unzip, and point to C:\Program Files, and Winzip properly extracts it into an \eclipse sub directory.

  1. Right-click the executable file eclipse.exe, and click Properties > Compatibility > Change settings for all users, and set the Privilege Level to “Run this program as an administrator”.

  2. Create a shortcut to eclipse.exe, and place it on your desktop. This gives you a handy launch point for Eclipse.

  3. Right-click the shortcut, and click Properties.

  4. Edit the Target field to add command line arguments that specify the Java VM to use.

    eclipse.exe -vm “%JAVA_HOME%\bin\javaw.exe”
  5. Start Eclipse.

  6. Accept (or set) the default Workspace (%USERPROFILE”%\workspace). I used: C:\Users\Chris\workspace

  7. Check “Use this as the default and do not ask again”.

  8. Create a new project – using the files from the repo java_3rdParty. Note: refresh the repo to pickup any new changes. File > New > Java Project. To get Eclipse to automatically incorporate the repo files into a proper Eclipse project (so you can run Javadoc):

  • You should see a note near the bottom of the New Java Project dialog that informs you that Eclipse will see the existing file structure and automatically create the appropriate project structure based on it.
  • Name the new project java_3rdParty (the same name used for the repo).
  • Use the location “C:\Users\Chris\src”.
  • JRE: “Use an execution environment JRE: JavaSE-1.7”.
  • Project Layout: “Create separate folders for sources and class files”.
  1. Click Finish (i.e., skip right to the end, without clicking Next).

Java Symbols in the Type Hierarchy View

Look in Preferences > Java > Appearance > Members Sort Order



This is the Java Platform Development Kit. You want the JDK that targets Java Standard Edition.

I used the 64-bit versions in all cases.


  1. Install the latest 64-bit version of the JDK (as of this writing, jdk1.7.0_21).

    It installs to:

    C:\Program Files\Java\jdk1.7.0_21\

    FYI – note that the Java Virtual Machine (VM) run-time executable file is:

    C:\Program Files\Java\jdk1.7.0_21\jre\bin\javaw.exe
  2. Setup an Environment Variable for the Java Runtime Environment (the Java_Home):

    JAVA_HOME=C:\Program Files\Java\jdk1.7.0_21\jre
  3. Path it:

  4. Setup an Environment Variable for the JDK (use JDK_HOME):

    JDK_HOME=C:\\Program Files\\Java\\jdk1.7.0_21

Note: The version number will be highter. E.g., “C:\Program Files\Java\jdk1.7.0_21”

  1. Path it:



The Java Run-time Environment, aka Java Virtual Machine (VM).

This is automatically installed when you install the JDK.

It’s bits are installed in the \jre directory inside the jdkx.x.x_xx directory.


Java Cookbook

Java Language Features


Packages work like Namespaces do in C++.

Packages provide an elegant way to name groups of related classes, and the classes within a package have package-private access by default (i.e., visibility scoped to the package level).

Default Visibility


Default: package-private.

To get a class to appear in the docs (using JavaDoc), you must make it public (explicitly).

Class Members

Default: package-private.

public: The member can be accessed

private: The member can be accessed from within its own class only.

protected: The member can be accessed from within a subclass in another package.