Java Cookbook

Java Language Features


Work like Namespaces in C++.

Pacakges 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.


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 jdk1.7.0_xx directory.


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
The version number will be highter. E.g., “C:\Program Files\Java\jdk1.7.0_21”
  1. Path it:



The TeleSign developer working on the project (Humberto) first told you he was using NetBeans for his IDE. Later, he appologized and said it was Eclipse.

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:

You can also FTP to it:
  1. Unzip to C:\Program files\. The executable will then be: “C:\Program Files\eclipse\eclipse.exe”


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

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

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

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

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

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

  6. Start Eclipse.

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

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

  9. Create a new project - using the files from the repo java_telesign. 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 stucture and automatically create the appropriate project structure based on it.
  • Name the new project java_telesign (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

Apache Ant

This 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. Exlipse’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 (albiet, 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 libratry 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”.

#) 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.

#) 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_telesign>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 Kenesis 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_telesign\javadoc.xml

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

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_telesign 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_telesign\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: TeleSign 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_telesign\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_telesign\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=”TeleSign AuthID 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=”**/*.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;TeleSign AuthID 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;, TeleSign Corp., All rights reserved.’ />


access=”public” additionalparam=”-bootclasspath C:Androidsdkplatformsandroid-19android.jar -noqualifier” author=”true” destdir=”${dest.dir}” doctitle=”TeleSign AuthID SDK for Android” windowtitle=”TeleSign AuthID SDK for Android” nodeprecated=”true” nodeprecatedlist=”true” noindex=”false” nonavbar=”false” notree=”false” overview=”${basedir}/overview.html” packagenames=”com.telesign.authid.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_telesign\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”.

FYI - Humberto used the command: johnw@weatherford-linux:~$ javadoc -d /tmp/javadoc -sourcepath /home/johnw/code/java_telesign/src -subpackages com, Where -d is your destination, and sourcepath is the source path.

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

/** TeleSign Java SDK
 * This Java package wraps the TeleSign PhoneID web service.
 * @package
 * @author     jweatherford
 * @copyright  Copyright © 2013, TeleSign Corporation.
 * @license The MIT License (MIT).
 * @version    1.0
 * @maintainer Humberto Morales
 * @link
 * @email      Support <>


Notes for Redesigning the TeleSign Java SDK

Factor out:

customer_id secret_key base

Eclipse Shortcuts

Ctrl+Space: Show Autocomplete list.

Configure Javadoc Location

JRE System Library:

You can use the JRE System Library URL for the following optional libraries:

Library Description
lib/charsets.jar Character conversion classes
lib/ext/sunjce_provider.jar The SunJCE provider for Java Cryptography APIs
localedata.jar Contains many of the resources needed for non US English locales
ldapsec.jar Contains security features supported by the LDAP service provider
dnsns.jar For the InetAddress wrapper of JNDI DNS provider
bin/rmid Java RMI Activation System Daemon
bin/rmiregistry Java Remote Object Registry
bin/tnameserv Java IDL Name Server
bin/keytool Key and Certificate Management Tool
bin/kinit Used to obtain and cache Kerberos ticket-granting tickets
bin/klist Kerberos display entries in credentials cache and keytab
bin/ktab Kerberos key table manager
bin/policytool Policy File Creation and Management Tool
bin/orbd Object Request Broker Daemon
bin/servertool Java IDL Server Tool
bin/javaws, lib/javaws/ and lib/javaws.jar Java Web Start

jce.jar jfr.jar jsse.jar rt.jar access-bridge-64.jar

commons-codec-1.7.jar: gson-2.2.2.jar: