javac - Java Compiler

• If the source code has a "package" statement (e.g. Foo.java contains "package com.abc.project1;")
  Place Foo.java in directory /junk/com/abc/project1
  javac com/abc/project1/Foo.java


  Use "\" in Windows
  javac com\abc\project1\Foo.java


• Specify where to start looking for .class files (and .java files if .class not found) if needed during compiling (-classpath) (default is the current working directory)
  javac -classpath /junk/someDir com/abc/project1/Foo.java


  Multiple paths
  javac -classpath /junk/someDir:/junk/someOtherDir com/abc/project1/Foo.java


  Use "\" and ";" in Windows
  javac -classpath \junk\someDir;\junk\someOtherDir com/abc/project1/Foo.java


  .class files embedded in .jar files
  javac -classpath /junk/someDir:/anywhere/myJar.jar:/elsewhere/yourJar.jar com/abc/project1/Foo.java


• Specify where to place generated .class files (-d)
  javac -d /junk/someDir -classpath /junk/someDir com/abc/project1/Foo.java

• Don't look in classpath for .java files if needed during compilation. Look in sourcepath
  javac -d /junk/someDir -classpath /junk/someDir -sourcepath /junk com/abc/project1/Foo.java

• By default, the compiled .class files will run in Java 1.1 also.
  
• By convention, .java (and the generated .class) file names start with an uppercase letter.

java - Run Java programs

• Run a program if its .class file is in the current working directory (Don't specify .class extension)
  java Foo
  Actual program execution starts with the first line in the "main" method.
• Run a program from anywhere by specifying -classpathor -cp. (Don't forget to include the current directory as "." if that's what you want!)
  java -classpath .:/junk/SomeDir Foo
java -cp .:/junk/SomeDir Foo
  
• Pass run time "strings" to the "main" method of the compiled program
  java -classpath /junk/SomeDir Foo myOption1 myOption2
  (Here, "main" method's args[0] will contain the string "myOption1", args[1] will contain the string "myOption2".)
• Run a program in a package (com.abc.project1)
  java -classpath /junk/SomeDir com.abc.project1.Foo
  
• Temporarily change Java's system environment (e.g., set the current working directory by setting "user.dir" to "/junk/someOtherDir")
  java -classpath /junk/SomeDir -Duser.dir=/junk/someOtherDir com.abc.project1.Foo
  
• Display what else is happening behind the scenes
  java -verbose -classpath /junk/SomeDir com.abc.project1.Foo
  
• Users can also run a Java program directly as a .jar file without knowing the "main" method class name. If Foo.class in myProgram.jar has the "main" method, then you must have modified the MANIFEST.MF file of the myProgram.jar file to include the following line (followed by a blank line):

  Main-Class: Foo

  Then, anybody can run the program with the following command java -jar myProgram.jar
java -jar myProgram.jar myOption1 myOption2
  Note that Java will ignore any classpath setting when searching for any program classes. All required files must be contained in the .jar file.

  In Windows, just double-click the .jar file. The application will run in the background. No MSDOS console will appear to show output or get input. Only if it is a Java Swing application, the swing window will appear as normal.
  

  In unix, set the execute permission on myProgram.jar with chmod 755 program.jar. Then, anybody should be able to run the program by simply issuing the command:
  myProgram.jar
myProgram.jar myOption1 myOption2
  

jar - Compress, Bundle-Up, and Extract Files

• Create the new .jar file in the specified dirctory
  jar cvf /junk/lib/myProgram.jar .
  
• Add new files or update existing files in a .jar file
  jar uvf myMore.jar Foo19.class
  
• Customize a .jar file's MANIFEST.MF file with contents from your manifest file (Make sure that your manifest file ends with a new line! Here, "manifest.text" is a text file containing lines such as

     Class-Path: myWhatever.jar jars/more.jar
     

  jar uvfm myProgram.jar manifest.text
  
• Create a new .jar file and customize its MANIFEST.MF file with contents from your manifest file
  jar cvfm myProgram myManifestFile *.class
  
• List .jar file contents (e.g. before extracting):
  jar tvf myProgram.jar
• Extract all files from a .jar file (Normally unnecessary because Java can automatically access the contents of a .jar file)
  jar xvf myProgram.jar
  
• Extract specific files from a .jar file
  jar xvf myProgram.jar Foo.class Foo2.class
  
• jar command usage is similar to the unix tar command.
• jar is short for the java archive.

appletviewer - to view applets without a browser

• In the applet's .java file, the class must extend JApplet:
  public class Foo extends javax.swing.JApplet{ . . . }
  
• The .java file must contain an "init" method. The first line of the "init" method is the entry point for applet execution. The browser or the appletviewer instantiates a nameless object of the Foo.class using the default constructor which can be empty. Then, the browser will call the "init" method. e.g. In applet Foo.java:
  

  
  public class Foo extends javax.swing.JApplet
  {
     private static Foo shark;
     public static void main(String args[])
        {shark = new Foo(); shark.init(); System.exit(0); }
     public void init(){  //Your Applet code here . . . }
  }
  

• These methods are also called automatically. You may not need to implement these methods.
  public void start(){ . . . }
public void stop(){ . . . }
public void destroy(){ . . . }

• Moreover, these methods in the applet's .java file are useful:
  public URL getCodeBase(){ . . . } // URL source directory for applet
public URL getDocumentBase(){ . . . } // URL source directory for html page
public String[][] getParameterInfo(){ . . . } // If implemented, parameters to be specified when calling this applet
public void showStatus(String message){ . . . } // Writes message to browser's status bar

• Example Foo.java applet code:
  

  import java.net.URL;
  
  public class Foo extends javax.swing.JApplet
  {
     private static Foo shark;
     public static void main(String args[])
        { shark = new Foo(); shark.init(); System.exit(0); }
     public void init()
     {
        //  These 10 system properties are always allowed to be read by an applet
        String[] keys = {"java.version", "java.vendor", "java.vendor.url",
                          "java.class.version", "os.name", "os.arch",
                          "os.version", "file.separator", "path.separator",
                          "line.separator"};
        java.util.Arrays.sort(keys);
        System.out.println(
           "***System Environment As Seen By A Java Applet***********");
        System.out.println(
           "***Format: PROPERTY = VALUE******************************");
        for (int i=0; i<keys.length; i++)
        {
           String key = (String)keys[i];
           System.out.println(key + " = " + System.getProperty(key));
        }
        System.out.println(
           "***End of System Environment As Seen By A Java Applet*****");
        try {
           showStatus("Where am I");
           URL coderoot = getCodeBase();
           URL docroot = getDocumentBase();
           System.out.println("Code root = " + coderoot
              + "\n\t(Protocol = " + coderoot.getProtocol()
              + ", Host = " + coderoot.getHost()
              + ", Port (-1 if none set) = " + coderoot.getPort()
              + ", File (address part after host name) = "
              + coderoot.getFile()
              + ", Ref (address part after file) = " + coderoot.getRef()
              + ")");
           System.out.println("Document root = " + docroot
              + "\n\t(Protocol = " + docroot.getProtocol()
              + ", Host = " + docroot.getHost()
              + ", Port (-1 if none set) = " + docroot.getPort()
              + ", File (address part after host name) = "
              + docroot.getFile()
              + ", Ref (address part after file) = " + docroot.getRef()
              + ")");
        } catch (Exception e) {
           System.out.println("Doesn't seem to be running as an applet!\n" + e);
        }
     }
  }
  

• Compile the .java file using javac.
• Create a .html file which should have the following HTML within the <OBJECT> . . . </OBJECT> tags in it for each applet that you want to run (e.g. Foo.class):
  

  <HTML>
  <HEAD><TITLE>Applet Example</TITLE></HEAD>
  <BODY>
  <h1>Applet Example</H1><p>
  
  <!-- Replace "Foo.class", "../classes", "trout", "myOption1", "salmon",
     and "myOption2" to reflect your applet's class, codebase,
     and runtime options -->
  
  <OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
     width="300"
     height="200"
     align="baseline"
     codebase=
     "http://java.sun.com/products/plugin/1.2/jinstall-12-win32.cab#Version=1,2,0,0"
  >
     <PARAM NAME="code" VALUE="Foo.class">
     <PARAM NAME="type" VALUE="application/x-java-applet;version=1.2">
     <PARAM NAME="codebase" VALUE="../classes">
     <PARAM NAME="trout" VALUE="myOption1">
     <PARAM NAME="salmon" VALUE="myOption2">
  
     <COMMENT>
        <EMBED type="application/x-java-applet;version=1.2"
           width="300"
           height="200"
           align="baseline"
           code="Foo.class"
           codebase="../classes"
           pluginspage=
              "http://java.sun.com/products/plugin/1.2/plugin-install.html"
           trout="myOption1"
           salmon="myOption2"
        ><NOEMBED>
     </COMMENT>
        The content at this location is a Java applet.  It requires at least
        Microsoft Internet Explorer ver. 4.0 OR Netscape Navigator ver. 4.0.
        In addition, please make sure that your browser is java-enabled!
        </NOEMBED></EMBED>
  </OBJECT>
  
  </BODY>
  </HTML>
  

  Here, "codebase" <PARAM> is optional. It specifies the directory where the browser will go to retrieve the applet class file as well as any additional class files that may be referenced by the applet class file. The directory should be in the form of a relative URL. When starting with a "/", it is relative to the main world wide web directory of the virtual server. Otherwise, it is relative to the location of the HTML file which contains the applet calling code.
  

  Parameter names are not case-sensitive (trout = Trout = tRout = TROUT). Except for code, codebase, type and version, all other parameter names are made available to the applet class file. e.g.String firstOption = getParameter("Trout"); statement in the applet's .java file will store the string "myOption1" in variable firstOption. Make sure that you check for null before using firstOption further along. The .html author may have forgotten to specify the parameter.

  So, for stand alone programs, the end user passes the runtime options on the command line after the class file name. The programmer accesses those runtime options via the "args" String array. For applets, the end user (which is the .html writer) passes the runtime options by specifying values of named parameters in the .html file. The programmer accesses those values by the always-available "getParameter" method. The programmer and the .html writer will have agreed in advance on the name of the parameter which is case-insensitive.

• View the applet from the local disk file with no server running (myApplet.html must contain <APPLET>, <OBJECT>, <EMBED> tag.)
  appletviewer myApplet.html
appletviewer file:///D:/junk/SomeHtmlDir/myApplet.html
  You can specify multiple .html files separated by spaces.
• View the applet from the local disk file with a server running locally
  appletviewer http://localhost/myApplet.html
  
• <APPLET> works in HTML 3.2 which has no plug-in support and therefore cannot use JApplet available only as a 1.1 or 1.2 plugin. <OBJECT> works in Microsoft Internet Explorer and uses java 1.1 or 1.2 plug-in. <EMBED> works in Netscape Navigator 4.x and also uses java 1.1 or 1.2 plug-in.
  
• You can also view the same applet in a browser. Enter, for example, "d:/junk/SomeHtmlDir/myApplet.html" in the browser's address/location bar and hit enter. The browser will not create a separate applet window as the appletviewer does. Also, "System.out.println( . . .)" statements will not print in the browser window as they do in the MSDOS console window when using appletviewer. So, you may have a difficult time debugging the applet.

  On MS Windows 95 and later, to be able to see the output from "System.out.println( . . .)" statements in your programs, you should install JDK 1.2.2 and above. JDK 1.2.2 installs a "Java Plug-In Control Panel" program in "Start->Programs" menu or Windows Control Panel folder. You then enable the "Show Java Console" checkbox in the "Java Plug-In Control Panel" application. Then, everytime you access any applet's HTML file through the browser, a separate window pops up which shows the output from the "System.out.println( . . .)" statements. It also shows all other error and exception information if necessary. (Enabling "java console" in Netscape and MSIE does not work as they can only display the output from the included 1.1.x Java program, not from the plugged-in Java program through the use of <EMBED> and <OBJECT> tags.)

javadoc - Automatic Java Documentation Generator

• Include comments starting with /** and ending with */ before each class, variable or method in the original source code. The comments can and should include standard HTML such as <TD>, <B> etc.
• Include @author, @version, @param, @return, @exception, @see, {@link}, @since, and @deprecated keywords.
• javadoc -verbose -private -d /junk/doc -classpath /junk/SomeDir -sourcepath /junk/src com.mypack com.mypack.util
  
• javadoc -verbose -private -d /junk/doc -classpath /junk/SomeDir -sourcepath /junk/src/com/mypack Foo.java *.java
  

keytool - Generate And Manage Security Keys

• Generate a key pair and the corresponding self-signed X.509 v1 certificate
  keytool -genkey -v -alias duke -validity 365
keytool -genkey -v -dname "CN=Your Name, OU=Purchasing Dept, O=ABC Corp., L=Los Angeles, S=California, C=US" -alias "mark" -validity 180
  To include a "," in text, use "\,"
  keytool -genkey -v -dname "cn=Mypeter schuster, o=Sun Microsystems\, Inc., o=sun, c=us" -alias mark
  
• List a specific key in ".keystore" file
  keytool -list -v -alias joe
  List all keys as text (cannot use -v with -rfc)
  keytool -list -rfc
  List all keys as binary (MD5 fingerprint)
  keytool -list
  List all keys in human-readable format
  keytool -list -v
  
• Export certificate to a text file (e.g. for e-mailing)
  keytool -export -v -rfc -alias jane -file janecertfile.cer
  Export certificate to a binary file
  keytool -export -v -alias jane -file janecertfile.cer
  
• Generate PKCS#10 Certificate Signing Request (CSR) to send to CA
  keytool -certreq -v -alias jane -file MarkJ.csr
  
• Display certificate from a certificate file (not keystore)
  keytool -printcert -v -file /tmp/someCertFile
  
• Trust and import somebody else's certificate from a file, including CA's reply
  keytool -import -alias joe -file jcertfile.cer
  Also verify using special file "cacerts" when importing
  keytool -import -trustcacerts -alias joe -file VSMarkJ.cer
  
• Change a key's password
  keytool -keypasswd -v -alias duke
  
• Change the keystore file's password
  keytool -storepasswd -v
  
• Delete a key from keystore file
  keytool -delete -v -alias sMiller
  
• Procedure to change X.500 distinguished name while keeping the old key pair
  
  1. First clone the key
     keytool -keyclone -v -alias sMiller -dest sMillerNew
     
  2. Replace the dname on the cloned key
     keytool -selfcert -v -alias sMillerNew -dname "cn=Susan Miller, ou=Accounting Department, o=BlueSoft, c=us"
     
  3. Generate a new certificate signing request to CA
     keytool -certreq -v -alias sMillerNew
     
  4. Import the CA's reply
     keytool -import -v -alias sMillerNew -trustcacerts -file VSSMillerNew.cer
     
  5. Delete the old key, if desired
     keytool -delete -v -alias sMiller
     
• JDK1.2 "keytool" replaced "javakey" of JDK 1.1.
• An "alias" functions as the name (or handle) for the key-pair for easier use. These aliases are NOT case-sensitive.
• Default file for storing keys is the ".keystore" file in "<user.home>" directory. ("System.out.println(System.getProperty("user.home");")
• Default file for storing trusted Certificate Authority certificates is the "cacerts" file in "<java.home>/lib/security" directory. Default password is "changeit". The default "cacerts" file that comes with Java already has five VeriSign certificates in it.
• Default values for some of the command line options are: -alias "mykey" -keyalg "DSA" -keysize 1024 -validity 90 -keystore <the file named .keystore in the user's home directory> -file <stdin if reading, stdout if writing>

jarsigner - Sign .jar Files Or Verify Their Signatures

• Replace a .jar file with its signed version
  jarsigner -verbose bundle.jar jane
  
• Specify a custom name for the .SF and .DSA files (converts to uppercase)
  jarsigner -verbose -sigfile TrustMe bundle.jar jane
jarsigner -sigfile TRUSTME bundle.jar jane
  
• Create a new "signed" .jar file from an existing .jar file
  jarsigner -verbose -signedjar sbundle.jar bundle.jar jane
  
• Use a non-default keystore for accessing signer's key
  jarsigner -verbose -keystore C:\working\mystore -signedjar sbundle.jar bundle.jar jane
jarsigner -keystore file:C:\working\mystore bundle.jar jane
jarsigner -keystore http://java.sun.com/keystore2 bundle.jar jane
  
• Verify a signed .jar file
  jarsigner -verify -verbose bundle.jar
  Also display verbose and certificate info from a non-default keystore
  jarsigner -keystore /working/mystore -verify -verbose -certs myTest.jar
  
• Digitally "signs" a .jar file with the signer's private key. Stores the corresponding "certificate" containing the signer's public key in the .DSA file which is added to the .jar file's "META-INF" directory.
• Can verify and re-sign .jar files signed with the JDK 1.1 "javakey" tool.
• Signing a .jar file does not encrypt its contents or change them in any way. Just two new .SF and .DSA files are added to "META-INF" directory inside the .jar file. By default, their file names are taken from up to first 8 characters of the alias name used to sign the .jar file.
• After signing, the default manifest file (MANIFEST.MF) contains the signature for each file included in the .jar file. The .SF file contains a signature for each "section" in the MANIFEST.MF file. The .DSA file contains the signature for the whole .SF file and the certificate authenticating the public key of the signer.
• What happens during -verify:
  1. Verify the .SF file using the certificate in the .DSA file.
  2. Verify the MANIFEST.MF file using the header in the .SF file.
  3. If the header verification fails, MANIFEST.MF file may have been modified by ADDING files to the .jar file which is fine. The "jarsigner" program will then only check the signed files to see if they have been modified since signing. This is done by verifying each section of the MANIFEST.MF file using the corresponding signature in the .SF file. All signatures in the .SF file must have the corresponding file section in the MANIFEST.MF file.
  4. Then, completely read each file whose signature appears in the .SF file. Verify each file's signature with the signature stored in the MANIFEST.MF file.