Code Samples

The code sample set for this tutorial is massive. Almost every snippet of code from the tutorial can be found in the downloadable source code (http://www.oracle.com/catalog/hardcorejv). However, without a guide, you could get lost quickly when surfing through the examples. Regarding the code itself, I will frequently snip out pieces you would need to get the code to compile and run. Copying this infrastructure code in the tutorial would add unnecessary bulk and potentially cloud the issue being discussed. Since I assume you are experienced in Java, I will also assume you know the housekeeping procedures used to implement pertinent concepts. One other tactic that I commonly use is to append a number to the name of a class or method. This is designed to show successive versions of the same class or method. The goal is to emphasize the development while allowing the user to look up the old version and play with it if he chooses. For example, you should read Country4 as Country. Finally, the code samples are very well-documented. However, for brevity's sake, I will usually slice out this documentation when presenting code examples. Although I firmly believe that good Javadoc documentation is important to good development, in this tutorial such documentation would needlessly increase the page count without adding to the discussion. One other thing to note about the examples is that you will often see the comment //$NON-NLS-1$ imbedded within the code. This is merely a flagging comment that tells Eclipse not to internationalize a particular String. I have snipped these comments from the book, as they aren't relevant to the discussions.

Locating an Example in the Downloadable Code

Each example cited in the tutorial is formatted as:

package oracle.hcj.review;
public class PointersAndReferences {
 public static void someMethod(Vector source) {
 Vector target = source;
 target.add("Swing");
 }
}


The emphasized lines show that you can find this code in the package oracle.hcj.review and the class PointersAndReferences. However, be aware that the code example cited may be embedded with other examples that are not relevant to that particular topic. In fact, I frequently combine several examples from a single subject into one class file to reduce the housekeeping code needed to run the sample. Doing a search on the method name will quickly locate the cited example.

Categories of Examples

The examples themselves can be divided into three categories. Each of these categories has a different usage paradigm that you should be aware of.

Syntax checkers

These are methods and snippets that were written solely for the purpose of checking my syntax in the book. To check my syntax, I leverage the features of Eclipse 3.0M4. However, be aware that the syntax checker examples will often be mixed with other examples in the same class file.

Demonstrators

These examples demonstrate a specific concept but are not executed. They often take the form of methods, which take a certain input and produce a certain output. Mixed in with these samples, you will occasionally find little main( ) methods. I use these simply to test things. If you want to play with them, feel free to do so; however, I do not discuss them in the tutorial. Some of the demonstrators are also used to demonstrate compiler errors when using certain techniques. To use these examples, you can try changing the files and rebuilding to demonstrate the concept. To compile a single file, there is a special Ant target named compile_example. To use the target, simply pass the filename you want to compile in the property example:

>ant -Dexample=oracle/hcj/review/RTTIDemo.java compile_example
Buildfile: build.xml init:
compile_example:
 [javac] Compiling 1 source file to C:\dev\hcj\bin
 [javac] C:\dev\hcj\src\oracle\hcj\review\RTTIDemo.java:54: incompatible types
 [javac] found : oracle.hcj.review.RTTIDemo.A
 [javac] required: oracle.hcj.review.RTTIDemo.B
 [javac] b = (A)a1; // compiler error: a1 is not a B.
 [javac] ^
 [javac] C:\dev\hcj\src\oracle\hcj\review\RTTIDemo.java:55: inconvertible types
 [javac] found : oracle.hcj.review.RTTIDemo.C
 [javac] required: oracle.hcj.review.RTTIDemo.B
 [javac] b = (B)c; // compiler error: c is not a B.
 [javac] ^
 [javac] 2 errors


Executables

Unlike demonstrators, executables are intended to be run and the output examined to demonstrate a concept or prove a point to a skeptical audience. When one of these programs is introduced, I will show you how to run it using Ant:

>ant -Dexample=oracle.hcj.review.ObjectIsGod run_example
run_example:
 [java] class oracle.hcj.review.ObjectIsGod$SomeClass --|> class java.lang.Object
 [java] class oracle.hcj.review.ObjectIsGod$SomeOtherClass --|> class java.lang.Object


The emphasized line gives you the command needed to run the example after the prompt (>). The command is identical in most cases. The only difference is the name of the property example that you pass to the run_example target. While we are on the subject of running the sample code, there is one thing to note about the output. Since all of the examples are run with Ant to get the classpath and other housekeeping done, the actual output from the command will be much longer:

>ant -Dexample=oracle.hcj.review.ObjectIsGod run_example
Buildfile: build.xml
init:
run_example:
 [java] class oracle.hcj.review.ObjectIsGod$SomeClass --|> class java.lang.Object
 [java] class oracle.hcj.review.ObjectIsGod$SomeOtherClass --|> class java.lang.Object
BUILD SUCCESSFUL
Total time: 1 second


Although this is the actual output, most of it is trivial and common to every use of Ant. Therefore, I snip out all of this housekeeping for the sake of brevity. The emphasized lines will be taken out when the run is presented in the tutorial. Therefore, when you run the examples, be aware that Ant is a bit more verbose than I am.
      
Comments