Java Cookbook¶

Java Language Features¶

Packages¶

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¶

Classes¶

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.

JRE¶

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.

JDK¶

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.

Install¶

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
Setup an Environment Variable for the Java Runtime Environment (the Java_Home):
JAVA_HOME=C:\Program Files\Java\jdk1.7.0_21\jre
Path it:
;%JAVA_HOME%\bin
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”

Path it:
;%JDK_HOME%\\bin

IDE¶

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¶

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...
Path it:
;%JAVAHOME%\\bin

Install point:

Update: There is now an SR2 release. I therefore downloaded: eclipse-jee-juno-SR2-win32-x86_64.zip

..note::: You can also FTP to it: ftp://ftp.osuosl.org/pub/eclipse//technology/epp/downloads/release/

Unzip eclipse-jee-juno-SR1-win32-x86_64.zip 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.
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”.
Create a shortcut to eclipse.exe, and place it on your desktop. This gives you a handly launch point for Eclipse.
Right-click the shortcut, and click Properties.
Edit the Target field to add command line arguments that specify the Java VM to use.

eclipse.exe -vm “%JAVA_HOME%\bin\javaw.exe”
Start Eclipse.
Accept (or set) the default Workspace (%USERPROFILE”%\workspace). I used: C:\Users\Chris\workspace
Check “Use this as the default and do not ask again”.
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”.

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

;%ANT_HOME%\bin

Eclipse Ant Editor and Ant Viewer¶

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

In Eclipse, click Window > Show View > Ant.
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.”

To fix this, in Eclipse, navigate to Windows > Preferences > Ant > Runtime > Classpath > Global Entries.
Click “Add external Jars...”.
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.

Download Apache Ant, and extract the zip file to C:\. It’ll end up with in C:\apache-ant-1.9.1.
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¶

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

Using Ant to build the docs from the Run dialog¶

Open the Run dialog by pressing the Windows Key + R (on the Kenesis Advantage keyboard, that’s Right Alt + R).
Paste the following command line into the Open field, and the click OK.

%ANT_HOME%\bin\ant -F %USERHOME%\src\java_telesign\javadoc.xml
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.

%JDK_HOME%\bin\javadoc.exe

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.

See: http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#linkoffline

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 http://developer.android.com/reference. Therefore the “approach -link http://developer.android.com/reference 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 http://developer.android.com/reference/ 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.

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

1.7

** 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

In Eclipse, Window > Open View > Other > Ant.
Drag & drop the Ant build file from the Project Explorer into this Ant View pane.
In the Ant view pane, double-click the target script.

In Eclipse, in the Project Explorer, right-click the Ant build file (build.xml or javadoc.xml).
Click Open in...
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: http://ant.apache.org/manual/Tasks/javadoc.html –> <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”/>

</path>

<target name=”init” description=”Ant build project setup.”>

<tstamp>

<format property=”doc_build.time_stamp” pattern=”EEEE MMMM dd, yyyy ‘at’ h:mm:ss a z” />

</tstamp>

</target>

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

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

<javadoc

classpath=”C:Androidsdkplatformsandroid-19android.jar;C:Androidsdkextrasandroidsupportv7appcompatlibsandroid-support-v4.jar”

access=”public” additionalparam=”-bootclasspath C:Androidsdkplatformsandroid-19android.jar -noqualifier java.lang:java.io” 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=”http://download.oracle.com/javase/7/docs/api/“/> <link offline=”true” href=”http://developer.android.com/reference/” packagelistloc=”C:/Android/sdk/docs/reference”/> <header><![CDATA[${javadoc.header}]]></header> <footer><![CDATA[${javadoc.footer}]]></footer> <bottom><![CDATA[${javadoc.bottom}]]></bottom>

</javadoc>

</target>

</project>

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¶

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    PhoneID.java
 * @author     jweatherford
 * @copyright  Copyright © 2013, TeleSign Corporation.
 * @license    http://opensource.org/licenses/mit-license.php The MIT License (MIT).
 * @version    1.0
 * @maintainer Humberto Morales
 * @link       https://github.com/TeleSign/java_telesign
 * @email      Support <support@telesign.com>
 */

Notes¶

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: http://download.oracle.com/javase/7/docs/api/

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: http://commons.apache.org/proper/commons-codec//javadocs/api-release/ gson-2.2.2.jar: http://google-gson.googlecode.com/svn/trunk/gson/docs/javadocs/