View source for Java Programming/Understanding a Java Program

{{Java Programming/GettingStartedTopic/Nav}}

This article presents a small Java program which can be run from the console.
It computes the distance between two points on a plane. 
You need not understand the structure and meaning of the program
just yet; we will get to that soon. Also, because the program
is intended as a simple introduction, it has some room
for improvement, and later in the module we will show
some of these improvements. But let's not get too far ahead
of ourselves!

== The Distance Class: Intent, Source, and Use ==

This class is named ''Distance'', so using your favorite editor or Java IDE,
first create a file named <code>Distance.java</code>,
then copy the source below and paste it into the file and save
the file.
<source lang="java">
 public class Distance
 {
   private java.awt.Point point0, point1;
 
   public Distance(int x0, int y0, int x1, int y1)
   {
     point0 = new java.awt.Point(x0, y0);
     point1 = new java.awt.Point(x1, y1);
   }
 
   public void printDistance()
   {
     System.out.println("Distance between " + point0 + " and " + point1 
                     + " is " + point0.distance(point1));
   }
 
   public static void main(String[] args)
   {
     Distance dist = new Distance(
              intValue(args[0]), intValue(args[1]),
              intValue(args[2]), intValue(args[3]));
     dist.printDistance();
   }
 
   private static int intValue(String data)
   {
     return Integer.parseInt(data);
   }
 }
</source>
At this point, you may wish to review the source to see how much
you might be able to understand. While perhaps not being the most literate
of programming languages, someone with understanding of other procedural
languages such as C, or other OO languages such as C++ or C#, will be able
to understand most if not all of the sample program.

Once you save the file, [[Java Programming/Compilation|compile]]
the program:
 javac Distance.java
(If the <code>javac</code> command fails, review the [[Java Programming/Installation|Java installation instructions]].)

To run the program, you supply it with the ''x'' and ''y'' coordinates
of two points on a plane. (For this version of Distance, only integer points
are supported.) The command sequence is
 java Distance ''x<sub>0</sub> y<sub>0</sub> x<sub>1</sub> y<sub>1</sub>''
to compute the distance between the points
(''x<sub>0</sub>, y<sub>0</sub>'') and (''x<sub>1</sub>, y<sub>1</sub>'')

For example, the command
 java Distance 0 3 4 0
will compute the distance between the points (0,3) and (4,0) and print the following:
 Distance between java.awt.Point[x=0,y=3] and java.awt.Point[x=4,y=0] is 5.0
The command
 java Distance -4 5 11 19
will compute the distance between the points (-4,5) and (11,19):
 Distance between java.awt.Point[x=-4,y=5] and java.awt.Point[x=11,y=19] is 20.518284528683193

We'll explain this strange looking output,
and also show how to improve it, later.

== Detailed Program Structure and Overview ==

As promised, we will now provide a detailed description of
this Java program. We will discuss the syntax and structure
of the program and the meaning of that structure.

=== Introduction to Java Syntax ===

The ''syntax'' of a Java class is the characters and symbols
and their structure used to code the class using Unicode characters. 
A fuller treatment of the syntax elements of Java may be found
at [[Java Programming/Syntax|Syntax]]. We will provide here only
enough description of the syntax to grasp the above program.

Java programs consist of a sequence of tokens. There are different kinds of
tokens. For example, there are word tokens such as <code>class</code>
and <code>public</code> which represent ''[[Java Programming/Keywords|keywords]]'' - special words
with reserved meaning in Java. Other words (non keywords such as
<code>Distance</code>, <code>point0</code>, <code>x1</code>, and <code>printDistance</code>) are 
''identifiers''. Identifiers have
many different uses in Java but primarily they are used as names.
Java also has tokens to represent numbers, such as <code>1</code>
and <code>3</code>; these are known as ''[[Java Programming/Literals|literals]]''.
''[[Java Programming/String Literals|String literals]]'', 
such as  <code>"Distance between "</code>, consist of
zero or more characters embedded in double quotes,
and ''[[Java Programming/Operators|operators]]'' 
such as <code>+</code> and <code>=</code>
are used to express basic computation such as addition or
String concatenation or assignment.
There are also left and right braces (<code>{</code>
and <code>}</code>) which enclose ''[[Java Programming/Blocks|blocks]]''.
The body of a class is
one such block. Some tokens are punctuation, such as periods
<code>.</code> and commas <code>,</code> and semicolons <code>;</code>.
You use ''[[Java Programming/Whitespace|whitespace]]'' such as spaces,
tabs, and newlines, to separate tokens. For example, whitespace
is required between keywords and identifiers: <code>publicstatic</code>
is a single identifier with twelve characters, not two Java keywords.

=== Declarations and Definitions ===

Sequences of tokens are used to construct the next building blocks
of Java classes: declarations and definitions. A class declaration
provides the name and visibility of a class. For our example,
 public class Distance
is the class declaration. It consists (in this case) of two keywords,
<code>[[Java Programming/Keywords/public|public]]</code> and 
<code>[[Java Programming/Keywords/class|class]]</code> followed by the identifier
<code>Distance</code>. 

This means that we are definining a class named <code>Distance</code>.
Other classes, or in our case, the command line, can refer to the
class by this name. The <code>public</code> keyword
is an [[Java Programming/Access Modifiers|access modifier]]
which declares that this class and its members may be accessed from other classes.
The <code>class</code> keyword, obviously, identifies this
declaration as a class. Java also allows declarations
of ''[[Java Programming/Interfaces|interfaces]]''
and (as of Java 5) ''[[Java Programming/Annotations|annotations]]''.

The class declaration is then followed by a block
(surrounded by curly braces) which provides the class's definition.
The definition is the implementation of the class - the declaration
and definitions of the class's members.  This class contains
exactly six members, which we will explain in turn.
# Two field declarations, named <code>point0</code> and <code>point1</code>
# A constructor declaration
# Three method declarations

==== Example: Instance Fields ====

The declaration
 private java.awt.Point point0, point1;
declares two ''[[Java Programming/Instance Fields|instance fields]]''.
Instance fields represent named values that are allocated whenever
an instance of the class is constructed. When a Java program
creates a <code>Distance</code> instance, that instance will contain space for 
<code>point0</code> and <code>point1</code>. When another
<code>Distance</code> object is created, it will contain space
for its ''own'' <code>point0</code> and <code>point1</code> values.
The value of <code>point0</code> in the first <code>Distance</code> object
can vary independently of the value of <code>point0</code>
in the second <code>Distance</code> object.

This declaration consists of:
<ol>
<li>The <code>[[Java Programming/Keywords/private|private]]</code> access modifier,
which means these instance fields are not visible to other classes.
<li>The type of the instance fields. In this case, the type is <code>java.awt.Point</code>.
This is the class <code>Point<code> in the <code>java.awt</code> package.
<li>The names of the instance fields in a comma separated list.
</ol>

These two fields could also have been declared with
two separate but more verbose declarations,

 private java.awt.Point point0;
 private java.awt.Point point1;

Since the types of these fields is a reference type (i.e. 
a field that ''refers to'' or can hold a ''reference to'' an object value),
Java will implicitly initialize the values of <code>point0</code> 
and <code>point1</code> to null
when a <code>Distance</code> instance is created. The null value means
that a reference value does not refer to an object. The special Java literal,
<code>null</code> is used to represent the null value in a program.
While you can explicitly assign null values in a declaration, as in 

 private java.awt.Point point0 = null;
 private java.awt.Point point1 = null;

it is not necessary and most programmers omit such default assignments.

==== Example: Constructor ====

A ''[[Java Programming/Methods#Special method, the Constructor|constructor]]'' is a special method
in a class which is used to construct an instance of the class.
The constructor can perform initialization for the object,
beyond that which the Java VM does automatically. For example,
Java will automatically initialize the fields <code>point0</code>
and <code>point1</code> to null.

Below is the constructor for this class.
It consists of five parts:
<ol>
<li>The optional [[Java Programming/Access Modifiers|access modifier(s)]].
    In this case, the constructor is declared <code>public</code>
<li>The constructor name, which must match the class name exactly: <code>Distance</code> 
    in this case.
<li>The constructor [[Java Programming/Parameters|parameters]].
    The parameter list is required. Even if a constructor
    does not have any parameters, you must specify the empty list <code>()</code>.
    The parameter list declares the type and name of each of the method's parameters.
<li>An optional {{java:throws}} clause which declares the   
    exceptions that the constructor may throw. This constructor does not declare any exceptions.
<li>The constructor body, which is a Java [[Java Programming/Blocks|block]] 
    (enclosed in <code>{}</code>. 
    This constructor's body contains two statements.
</ol>

<code>
   public Distance(int x0, int y0, int x1, int y1)
   {
      point0 = new java.awt.Point(x0, y0);
      point1 = new java.awt.Point(x1, y1);
   }
</code>
This constructor accepts four parameters, named <code>x0, y0, x1</code> and <code>y1</code>.
Each parameter requires a parameter type declaration, which in this example is 
<code>{{java:int}}</code> for all four parameters. 
Java integer values are signed, 32 bit twos complement integers.
The parameters in the parameter list are separated by commas.

The two assignments in this constructor use Java's ''{{java:new}} operator'' to allocate two <code>java.awt.Point</code> objects. The first allocates
an object represeting the first point, <code>(x0, y0)<code>, 
and assigns it to the <code>point0</code>
instance variable (replacing the null value that the instance variable was initialized to).
The second statement allocates a second two <code>java.awt.Point</code> instance with 
<code>(x1, y1)<code> and assigns it to the <code>point1</code>
instance variable.

This is the constructor for the Distance class. Distance implicitly extends
from <code>java.lang.Object<code>. Java inserts a
call to the super constructor as the first executable statement of the constructor
if there is not one explicitly coded.
The above constructor body is equivalent to the following
body with the explicit super constructor call:

   {
      super();
      point0 = new java.awt.Point(x0, y0);
      point1 = new java.awt.Point(x1, y1);
   }

While it is true that this class could be implemented in other ways,
such as simply storing the coordinates of the two points and computing
the distance as 
<math>\sqrt{(x_1-x_0)^2 + (y_1-y_0)^2}</math>,
this class instead uses the existing <code>java.awt.Point</code> class.
This choice matches the abstract definition of this class:
to print the distance bewteen two points
on the plane. We take advantage of existing behavior already implemented
in the Java platform rather than implementing it again.
We will see later how to make the program more flexible
without adding much complexity, because we choose to use object abstractions
here. However, the key point is that this class uses information
hiding. That is, ''how'' the class stores its state or how it
computes the distance is hidden. We can change this implementation
without altering how clients use and invoke the class.

==== Example: Methods ====

Methods are the third and most important type of class member.
This class contains three ''methods'' in which the behavior of the Distance class
is defined: <code>printDistance()</code>, <code>main()</code>,
and <code>intValue()</code>

==== The printDistance() method ====

The <code>printDistance()</code> method prints the distance between the
two points to the standard output (normally the console).
   public void printDistance()
   {
      System.out.println("Distance between " + point0
                         + " and " + point1
                         + " is " + point0.distance(point1));   }
   }

This ''[[Java Programming/Instance Methods|instance method]]''
executes within the context of an implicit <code>Distance<code> object.
The instance field references, <code>point0</code> and <code>point1<code>,
refer to instance fields of that implicit object.
You can also use the special variable <code>this</code>
to explicitly reference the current object. 
Within an instance method, Java binds the
name <code>this</code> to the object on which the method
is executing, and the type of <code>this</code> is that of
the current class.
The body of the <code>printDistance</code> method could also be coded as
      System.out.println("Distance between " + this.point0
                         + " and " + this.point1
                         + " is " + this.point0.distance(this.point1));   }

to make the instance field references more explicit.

This method both computes the distance and prints it in one statement.
The distance is computed with <code>point0.distance(point1)</code>; <code>distance()</code>
is an instance method of the <code>java.awt.Point</code> class (of which <code>point0</code>
and <code>point1</code> are instances. The method operates on <code>point0</code> (binding
<code>this</code> to the object that <code>point0</code> refers to during the execution
of the method) and acceping another Point as a paramemer. (Actually, it is
slightly more complicated than that, but we'll explain later.)
The result of the <code>distance()</code> method is a double precision
floating point number.

This method uses the syntax

 "Distance between " + this.point0
 + " and " + this.point1
 + " is " + this.point0.distance(this.point1)

to construct a String to pass to the <code>System.out.println()</code>.
This expression is a series of ''[[Java Programming/String Concatenation|String concatenation]]'' methods which concatenates Strings or the String representation
of primitive types (such as doubles) or objects, and returns a long string.
For example, the result of this expression for the points (0,3) and (4,0) is
the String
 "Distance between java.awt.Point[x=0,y=3] and java.awt.Point[x=4,y=0] is 5.0"
which the method then prints to <code>System.out</code>. 

In order to print, we invoke the <code>println()</code>. This is an instance
method from <code>java.io.PrintStream</code>, which is the type of the
static field <code>out</code> in the class <code>java.lang.System</code>.
The Java VM binds <code>System.out</code> to the standard output stream
when it starts a program.

==== The main() method ====

The <code>main()</code> method is the main entry point which
Java invokes when you start a Java program from the command
line. The command
 java Distance 0 3 4 0
instructs Java to locate the Distance class, put the four
command line arguments into an array of String values,
then pass those arguments the <code>public static main(String[])</code>
method of the class. (We will introduce arrays shortly.)
Any Java class that you want to invoke from
the command line or desktop shortcut must have a main method
with this signature.
   public static void main(String[] args)
   {
      Distance dist = new Distance(
            intValue(args[0]), intValue(args[1]),
            intValue(args[2]), intValue(args[3]));
      dist.printDistance();
   }
The <code>main()</code> method invokes the final method, <code>intValue()</code>,
four times. The <code>intValue()</code> takes a single string parameter
and returns the integer value represented in the string. For example,
<code>intValue("3")</code> will return the integer 3.

==== The <code>intValue()</code> method ====

The <code>intValue()</code> method delegates its job to the <code>Integer.parseInt()</code>
method. The main method could have called <code>Integer.parseInt()</code> 
directly; the <code>intValue()</code> method simply makes the <code>main()</code> method
slightly more readable. 

   private static int intValue(String data)
   {
      return Integer.parseInt(data);
   } 

This method is 
<code>[[Java Programming/Keywords/private|private]]</code>
since, like the fields <code>point0</code> and <code>point1</code>,
it is part of the internal implementation of the class
and is not part of the external
programming interface of the <code>Distance</code> class.

==== Static vs. Instance Methods ====

Both the <code>main()</code> and <code>intValue()</code> methods are
''[[Java Programming/Static Methods|static methods]]''. The static keyword tells the compiler to create a single memory space associated with the class.  Each individual object instantiated has its own private state variables and methods but use the same <b>static</b> methods and members common to the single class object created by the compiler when the first class object is instantiated or created.  This means that
the method executes in a static or non-object context - there is no
implicit separate instance available when the static methods run from various objects,
and the special variable <code>this</code> is not available. 
As such, static methods
cannot access instance methods or instance fields (such as <code>printDistance()</code>) or <code>point0</code>) directly. 
The <code>main()</code> method can only invoke the instance method
<code>printDistance()</code> method via an instance reference such as
<code>dist</code>.

=== Data Types ===

Most declarations have a data type. Java has several categories
of data types: reference types, primitive types, array types,
and a special type, void.

==== Reference Types ====

A ''reference type'' is a Java data type
which is defined by a Java class or interface. Reference types derive this
name because such values ''refer to'' an object or contain a ''reference to''
an object. The idea is similar to pointers in other languages like C.

Java represents sequences of character data, or
''[[Java Programming/API/java.lang.String|String]]'', with the
reference type <code>java.lang.String</code> which is most
commonly referred to as <code>String</code>.
''String literals'', 
such as  <code>"Distance between "</code> are constants
whose type is String.

This program uses three separate reference types:
# java.lang.String (or simply String)
# Distance
# java.awt.Point

For more information see chapter : [[Java Programming/Classes, Objects and Types]].

==== Primitive Types ====

In addition to object or reference types, Java supports 
''[[Java Programming/Primitive Types|primitive types]]''.
The primitive types are used to represent Boolean, character, and numeric
values. This program uses only one primitive type explicitly,
<code>''{{java:int}}''</code>,
which represents 32 bit signed integer values.
The program also implicitly uses 
<code>''{{java:double}}''</code>,
which is the return type of the <code>distance()</code>
method of <code>java.awt.Point</code>.
<code>double</code> values are 64 bit IEEE floating point values.
The <code>main()</code> method uses integer values 0, 1, 2, and 3
to access elements of the command line arguments.
The <code>Distance()</code> constructor's four parameters
also have the type <code>int</code>.
Also, the <code>intValue()</code> method has a return type
of <code>int</code>. This means a call to
that method, such as <code>intValue(args[0])</code>,
is an expression of type <code>int</code>. This helps explain
why the main method cannot call
 new Distance(args[0], args[0], args[0], args[0]) // this is an error
Since the type of the <code>args</code> array element is
String, and our constructor's parameters must be <code>int</code>,
such a call would result in an error because Java cannot automatically
convert values of type String into <code>int</code> values.

Java's primitive types are
<code>''{{java:boolean}}''</code>,
<code>''{{java:byte}}''</code>,
<code>''{{java:char}}''</code>,
<code>''{{java:short}}''</code>,
<code>''{{java:int}}''</code>,
<code>''{{java:long}}''</code>,
<code>''{{java:float}}''</code> and
<code>''{{java:double}}''</code>,
each of which are also Java language keywords.

==== Array Types ====

Java supports ''[[Java Programming/Arrays|arrays]]'', 
which are aggregate types which have
a fixed element type (which can be any Java type) and an integral
size. This program uses only one array, <code>String[] args</code>.
This indicates that <code>args</code> has an array type and
that the element type is <code>String</code>. The Java VM
constructs and initializes the array that is passed to the
<code>main</code> method. See ''[[Java Programming/Arrays|arrays]]''
for more details on how to create arrays and access their size.

The elements of arrays are accessed with integer indices. The first element
of an array is always element 0. This program accesses the first four
elements of the <code>args</code> array explicitly with the indices
0, 1, 2, and 3. (This program does ''not'' perform any input validation,
such as verifying that the user passed at least four arguments
to the program. We will fix that later.)

==== void ====

''[[Java Programming/Keywords/void|void]]''
is not a type in Java; it represents the absence of a type.
Methods which do not return values are declared as <code>void</code>
methods.

This class defines two <code>void</code> methods:

 public static void main(String[] args) { ... }
 public void printDistance()  { ... }

{{Java Programming}}

[[Category:Java Programming]]