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 ======= 1. Install the latest 64-bit version of the JDK (as of this writing, `jdk1.7.0_21 `_). It installs to: .. code-block:: shell-session C:\Program Files\Java\jdk1.7.0_21\ FYI - note that the Java **Virtual Machine** (**VM**) run-time executable file is: .. code-block:: shell-session 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*): .. code-block:: shell-session JAVA_HOME=C:\Program Files\Java\jdk1.7.0_21\jre 3. Path it: .. code-block:: shell-session ;%JAVA_HOME%\bin 4. Setup an Environment Variable for the JDK (use *JDK_HOME*): .. code-block:: shell-session 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" 5. Path it: .. code-block:: shell-session ;%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 ================== 1. Setup an Environment Variable for Eclipse called: .. code-block:: shell-session 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: .. code-block:: shell-session ;%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/ 3. 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. 4. 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". 5. Create a shortcut to eclipse.exe, and place it on your desktop. This gives you a handly launch point for Eclipse. 6. Right-click the shortcut, and click Properties. 7. Edit the Target field to add command line arguments that specify the Java VM to use. eclipse.exe -vm "%JAVA_HOME%\\bin\\javaw.exe" 8. Start Eclipse. 9. Accept (or set) the default Workspace (%USERPROFILE"%\\workspace). I used: C:\\Users\\Chris\\workspace 10. Check "Use this as the default and do not ask again". 11. 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". 12. 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. 1) 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. 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 ================================================= 1) 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 =============================================== 1) 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. Javadoc Command ^^^^^^^^^^^^^^^ %JDK_HOME%\\bin\\javadoc.exe Note: JDK_HOME = C:\Program Files\Java\jdk1.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 Files\Java\jdk1.7.0_21\bin\javadoc.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\\). Select Types for which Javadoc will be Generated ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Uncheck, and then re-check "src". This ensures that every subpackage is checked (just one subpackage is checked by default). Create Javadoc for Members with Visibility ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 the Standard Doclet ^^^^^^^^^^^^^^^^^^^^^^^ Use this option to generate the default doc style. Destination: C:\\Users\\Chris\\src\\java_telesign\\doc Use Custom Doclet ^^^^^^^^^^^^^^^^^ 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. Document Title ^^^^^^^^^^^^^^ Check this option. I used the title: TeleSign Java SDK Documentation Basic Options ^^^^^^^^^^^^^ I checked all of the options, except @deprecated. Select Referenced Archives and Projects to which Links Should be Generated ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. How to point to the online version of the Android SDK docs """""""""""""""""""""""""""""""""""""""""""""""""""""""""" 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 ``_. 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 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. Style Sheet ^^^^^^^^^^^ 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. Overview ^^^^^^^^ Check the Overview checkbox. Use the path: C:\\Users\\Chris\\src\\java_telesign\\overview.html VM Options ^^^^^^^^^^ As far as I can tell, you can leave this field blank. Extra Javadoc Options ^^^^^^^^^^^^^^^^^^^^^ -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#). JRE Source Compatibility ^^^^^^^^^^^^^^^^^^^^^^^^ 1.7 Save the settings of this Javadoc export as an Ant Script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ** 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 To run an Ant script '''''''''''''''''''' 1) 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. To View and Edit an Ant Script '''''''''''''''''''''''''''''' 1) 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 ==========
Open Generated index file in Browser ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 ============================ .. code-block:: java /** 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 */ 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/