Module 3: Elementary Java, Part II

Methods (functions): a first look

• Some languages treat procedures (no return value) and functions separately.
• Java calls them both methods
• We will use both function as well as method.

• A Java method that returns nothing is declared to return void.

Consider a simple example: (source file)

public class UniformRandom {

    // "Global" variable - the seed, set to some 
    // arbitrary non-zero value.
    static long r_seed = 12345678L; 

    //---- No need to understand the technical details between HERE -----

    static final long m = 2147483647L;
    static final long a = 48271L;
    static final long q = 44488L;
    static final long r = 3399L;

    // Basic Lehmer generator - uniform[0,1] For more information see Knuth, Vol. II.
    public static double uniform ()
    {
        long hi = r_seed / q;
        long lo = r_seed - q * hi;
        long t = a * lo - r * hi;
        if (t > 0) {
            r_seed = t;
        }
        else {
            r_seed = t + m;
        }
        return ( (double) r_seed / (double) m );
    }

    //---- and HERE -----------------------------------------------------

    public static void main (String[] argv)
    {
        // Let's test the generator. The mean should be 0.5.
        double sum = 0;
        for (int i=1; i<=10000; i++) {
            sum += uniform ();
        }

        System.out.println ("Average of 10000 samples: " + sum/10000);
    }

}

Note:

• Return value of uniform() is a double.
• uniform() takes no parameters, but the parentheses are still required, both in declaration and call.
• r_seed is a sort-of global variable of type long.
• The return value of main is void.
• For more information about random number generators, see the material on random number generation in the appendix.

Let's modify the code so that the seed can be set via a method: (source file)

public class UniformRandom2 {
    
    // Same constants
    static long r_seed = 12345678L; 
    static final long m = 2147483647L;
    static final long a = 48271L;
    static final long q = 44488L;
    static final long r = 3399L;

    public static double uniform ()
    {
        // ... same as before ...
    }

     // Set the seed to any given value.
    public static void setSeed (long value)
    {
        r_seed = value;
    }

    public static void main (String[] argv)
    {
        // Let's test the generator again. The mean should be 0.5.
        setSeed (13579);
        double sum = 0;
        for (int i=1; i<=10000; i++) {
            sum += uniform ();
        }

        System.out.println ("Average of 10000 samples: " + sum/10000);
    }

}

Note:

• setSeed returns void.
• A parameter is declared the same way as a variable.
• The above parameter is a call-by-value parameter.

Exercise 3.1: Modify the above code to add a method that computes the area of a circle of given (parameter) radius. Then use the method to compute the mean area of a circle whose radius is uniformly distributed in the range (0,1). Thus, generate a number of circles randomly (according to the above distribution), compute the area of each and take the average. What is the theoretical answer?

Methods: passing parameters

We have already seen an example of passing parameters by value. What about call-by-reference?

All parameters in Java methods are passed by-value.
Thus, no "swap" method is possible in Java.

What happens if we try to implement "swap"? Let's see: (source file)

public class Swap {

    public static void swap (int a, int b)
    {
        int temp;
        temp = a;
        a = b;
        b = temp;
    }

    public static void main (String[] argv)
    {
        int i=5, j=6;
        swap (i,j);
        System.out.println ("i=" + i + "  j=" + j);
        // What gets printed out?
    }
}

Why didn't they provide call-by-reference in Java?

• Since Strings, arrays and objects are actually implemented via pointers, a method can modify these types of parameters.
• Allowing the pointers themselves to be modified would allow for bad code to destroy object references.
• Thus, one option would have been to allow call-by-reference only with basic types such as integers and reals. The designers chose not to do this.

What do you do when you want a method to modify a variable?

• If it's an object or an array, simply pass the object or array as a parameter.
• If it's a basic type (int, double, etc):
• If there's only one variable, have the method return value do the job:

       x = func (a,b,c);   // x gets modified
      

• If you want a method to modify several variables, consider packaging the variables into an object.
  (We will learn how to do this later).

Methods: overloading

Suppose we want to add the following methods to our uniform_random generator:

• A method that generates a uniform value in a given range.
• A method that generates a uniform integer value in a given range.

One option is to define methods as follows:

public class UniformRandom3 {

    static long r_seed = 12345678L; 
    static final long m = 2147483647L;
    static final long a = 48271L;
    static final long q = 44488L;
    static final long r = 3399L;

    public static double uniform ()
    {
        // ... same as before ... 
    }

    // U[a,b] generator
    public static double uniformRange (double a, double b)
    {
        // ... need code in here ... 
    }

    // Discrete Uniform random generator -
    returns an integer between a and b
    public static long discreteUniform (long a, long b)
    {
        // ... need code in here ... 
    }

    public static void main (String[] argv)
    {
        // ... use the methods ...
    }

}

Thus, instead of defining uniformRange and discreteUniform above, we could simply use uniform: (source file)

public class UniformRandom4 {

    static long r_seed = 12345678L; 
    static final long m = 2147483647L;
    static final long a = 48271L;
    static final long q = 44488L;
    static final long r = 3399L;

    public static double uniform ()
    {
        // ... 
    }

    // U[a,b] generator 
    public static double uniform (double a, double b)
    {
        if (b > a) {
           // Can you figure out why this works?
            return ( a + (b-a) * uniform() );
        }
        else { 
            System.out.println ("ERR in uniform(double,double):a="+a+"b="+b); 
            return 0;
        }
    }

    // Discrete Uniform random generator - returns an
    // integer between a and b
    public static long uniform (long a, long b)
    {
        if (b > a) {
            double x = uniform ();
            long c = ( a + (long) Math.floor((b-a+1)*x) );
            return c;
        }
        else if (a == b) {
            return a;     
        }
        else { 
            System.out.println ("ERR: in uniform(long,long):a="+a+"b="+b); 
            return 0;
        }
    }


    public static void main (String[] argv)
    {
        // Use the functions ...
        // Note: they have the same name.
        double x = uniform ();
        double y = uniform (2.718, 3.141);
        long i = uniform (7, 16);

        System.out.println ("x=" + x + " y=" + y + " i=" + i);
    }

}

Note:

• Three functions are called uniform.
• All three functions have a different signature:
• One has signature uniform().
• Another has signature uniform (double, double).
• The third has signature uniform (long, long).
• A function's signature is determined by:
• the function name,
• the number of arguments
• the types of the arguments,
• and the order of its arguments.
• Return values do not matter in determining signature. Thus the following will not compile:

class UniformRandom {
    public static double uniform (double a, double b)
    {
        // ... 
    }

    // This has the same signature.
    public static long uniform (double a, double b)
    {
        // ... 
    }
}

Exercise 3.2: Why does it make sense to bar the above from the language?

• Note: each parameter is declared separately in Java methods.
  The following does not compile:

public static double uniform (double a, b)

• Note that (apart from System.out.println), we are using a library function:
• The function is the floor() function in the java.lang.Math object of the java.lang library.
• The library objects in in java.lang are the only library objects that do not need to be import'ed.
• The statement

import java.lang.*;

even though not needed here, imports all classes in java.lang.
(We will see what this means later).

• Other libraries (packages) need to be import'ed.

Screen I/O

We have seen how to print stuff to the screen using System.out.print() or System.out.println().

We'll start by reading a single line from the screen. There are two ways to do this:

• First, let's look at the "old" way (Java 1.4 and earlier) - this way is longer but is worth learning because it ties in nicely with Java streams, which we will learn about later: (source file)

  
  import java.io.*;
  
  public class ScreenIO1 {
  
      public static void main (String[] argv)
      {
          // Put out a prompt.
          System.out.print ("Enter string: ");
  
          // We have to have a try clause because
          // the method readLine throws an exception.
          try {
              // These are the key steps in setting up the read operation.
              InputStreamReader isr = new InputStreamReader (System.in);
              LineNumberReader lr = new LineNumberReader (isr);
  
              // Now read the input line.
              String inputLine = lr.readLine ();
  
              // Echo it.
              System.out.println ("Echo: " + inputLine);
          }
          catch (IOException e) {
              // If there was a problem...
              System.out.println (e);
          }
      }
  }
  

• The simpler way is: source file

  
  import java.util.*;
  
  public class ScannerExample {
  
      public static void main (String[] argv)
      {
          Scanner scanner = new Scanner (System.in);
          System.out.print ("Enter string: ");
          String inputLine = scanner.nextLine ();
          System.out.println ("Echo: " + inputLine);
      }
  
  }
  

Again, for comparison, we'll look at two different ways to read a single integer from the screen:

• With the "old" way, we'll need to parse the input string: (source file)

  import java.io.*;
  
  public class ScreenIO2 {
  
      public static void main (String[] argv)
      {
          System.out.print ("Enter an integer: ");
  
          try {
              InputStreamReader isr = new InputStreamReader (System.in);
              LineNumberReader lr = new LineNumberReader (isr);
  
              String inputLine = lr.readLine ();
  
              // Parse for an integer.
              int i = 0;
              try {
                  i = Integer.parseInt (inputLine);
              }
              catch (NumberFormatException e) {
                  System.out.println ("Error in input");
                  System.exit (0);
              }
  
              // Echo it.
              System.out.println ("The integer you entered: " + i);
          }
          catch (IOException e) {
              System.out.println (e);
          }
      }
  
  }
  

• Using "scanner": (source file)

  
  import java.util.*;
  
  public class ScannerExample2 {
  
      public static void main (String[] argv)
      {
          Scanner scanner = new Scanner (System.in);
          System.out.print ("Enter an integer: ");
          int i = scanner.nextInt ();
          System.out.println ("The integer you entered: " + i);
      }
  
  }
  

Note:

• Integer is a Java class with some methods useful in handling int's.
• Integer is actually in the library java.lang.* which is the only library that does not need an import.
• parseInt is very unforgiving. For example, blanks on either side of the integer are unacceptable.
• Similar to Integer, there are Byte, Short, Long, Float and Double objects with parsing methods.
• The syntax new BufferedReader (System.in) is strange. It is our first look at a dynamic object and the new operator.
  ( We will understand this better when we cover objects.)

• We have used a

    try {
        //... some code
    }
    catch () {
        //... some other code
    }

statement. In these cases, we are forced to by the compiler since the methods we call throw exceptions.


• Finally, we have used the import statement to access library objects in the package java.io

 import java.io.*;
 

Screen I/O: formatting

• It would be logical to cover output formatting at this time (for example, how to fix the number of decimal places).
• However, formatting is easier understood after covering objects, so we will defer discussing formatting until after we've covered objects.
• If you are coming from C, you can use System.out.printf() - which has almost the same formatting rules as C.

File I/O: reading from a file

The Java approach to I/O in general is similar to that of C++:

• Each source of information is treated as in input stream.
• An input stream can be a file, the screen or something else, such as a program that produces data.
• Input streams can consist of ascii text data, raw bytes or some other encoding.
• Java provides an enormous variety of library objects to deal with different input streams.
• Some of these depend on the type of data ( byte vs. text).
• Others depend on the way in which reading is done ( with or without buffering, for example).

Since a file is just an input stream, reading from a file is similar to reading from the screen, provided the file is identified as an input stream.

The following example shows how to read a text file line-by-line: (source file )

import java.io.*;

public class FileIO1 {

    public static void main (String[] argv)
    {
        try {
            // These are the key steps in setting up the read operation.
            FileReader fr = new FileReader ("testdata");
            LineNumberReader lr = new LineNumberReader (fr);

            // Now read the input lines
            boolean over = false;         
            int i = 1;
            do {
                // Get a line from the file.
                String inputLine = lr.readLine ();
                if (inputLine != null) {
                    System.out.println ("Line " + i + ": " + inputLine);
                    i++;
                }
                else {
                    over = true;
                }
            } while (! over);

            // Done.
            lr.close();
        }
        catch (IOException e) {
            // If there was a problem...
            System.out.println (e);
        }
    
    }
}

Note:

• An exception will occur if the file is not found.
• readLine() returns a null if EOF is reached.
• The stream is closed after reading is complete.
• The above code works for text files. A different set of library objects is used for binary data.

Here's the same example with a (simpler) while-loop:

public static void main (String[] argv)
{
    try {
        FileReader fr = new FileReader ("testdata");
        LineNumberReader lr = new LineNumberReader (fr);

        // Using a while loop ...
        String inputLine = lr.readLine ();
        int i = 0;
        while (inputLine != null) {
            i ++;
            System.out.println ("Line " + i + ": " + input_line);
	    inputLine = lr.readLine ();
        }

        // Done.
        lr.close();
    }
    catch (IOException e) {
        // If there was a problem...
        System.out.println (e);
    }
    
}

File I/O: writing to a file

Similar to reading, writing is an output stream activity. By defining a file as an output stream, you can write to a file: ( source file )

import java.io.*;

public class FileIO2 {

    public static void main (String[] argv)
    {
        try {
            // Need to associate a file with a PrintWriter.
            FileWriter fr = new FileWriter ("testdata2");
            PrintWriter pw = new PrintWriter (fr);

            // Now we're ready for writing.
            pw.println ("Hello");
            pw.println ("Hello again");

            // Done.
            pw.close();
         }
         catch (IOException e) {
             System.out.println (e);
         }
     }
}

Note:

• The stream is closed after writing is complete.
• PrintWriter is used for text files.

File I/O: reading and writing to the same file

Reading and writing to the same file can be done in many ways. We will consider the following simple task:

• Read the file into memory.
• Change its contents.
• Write the new contents back to the same file.

Example: ( source file )

import java.io.*;

public class FileIO3 {

    public static void main (String[] argv)
    {
	String filename = "testdata3";
	int numLines = 0;
	String[] lineBuffer = null;
	
	// First, we read in the file to get the size.
	try {
	    FileReader fr = new FileReader (filename);
	    LineNumberReader lr = new LineNumberReader (fr);
	    
	    boolean over = false;         
	    numLines = 0;
	    do {
		String input_line = lr.readLine ();
		if (input_line != null)
		    numLines ++;
		else
		    over = true;
	    } while (! over);
	    
	    lr.close();
	}
	catch (IOException e) {
	    System.out.println (e);
	}

	// We have now counted the number of lines and
	// we will read the file into a buffer.
	try {
	    FileReader fr = new FileReader (filename);
	    LineNumberReader lr = new LineNumberReader (fr);
	    
	    // Allocate necessary space.
	    lineBuffer = new String[numLines];
	    
	    int i = -1;
	    boolean over = false;
	    do {
		String s = lr.readLine ();
		if (s == null) 
		    over = true;
		else 
		    lineBuffer [++i] = s;
	    } while (! over);
	    
	    lr.close();
	}
	catch (IOException e) {
	    System.out.println (e);
	}
	
	// Next, write the buffer out to the same file
	// with line numbers added.
	try {
	    // Open the file for writing
	    FileWriter fr = new FileWriter (filename);
	    PrintWriter pw = new PrintWriter (fr);
	    
	    // Write from buffer with line numbers:
	    for (int i=0; i<numLines; i++) 
		pw.println ("Line " + (i+1) + ": " + lineBuffer[i]);
	    
	    pw.close();
	}
	catch (IOException e) {
	    System.out.println (e);
	}
	
    }

}

File I/O: Appending to a file

To append to a file, simply use the appropriate arguments to FileWriter: include "true" to indicate appending.

Example: ( source file )

import java.io.*;

public class FileIOAppend {

    public static void main (String[] argv)
    {
	try {
	    // Using "true" as a second argument indicates "append"
	    // in FileWriter.
	    FileWriter fr = new FileWriter ("testdata_append", true);
	    PrintWriter pw = new PrintWriter (fr);

	    // Now we're ready for writing.
	    pw.println ("Hello");
	    pw.println ("Hello again");

	    // Done.
	    pw.close();
	}
	catch (IOException e) {
	    System.out.println (e);
	}
    }

}

Simple input parsing

Consider an input file that looks like this:

Circle:
  center.x=50
  center.y=60
  radius=20
Circle:
  center.x=320
  center.y=180
  radius=40
Rectangle: 
  topleft.x=50
  topleft.y=400
  bottomright.x=500
  bottomright.y=40

What we would like to do is to parse the input to extract the numbers.

• Reading multiple numbers (or even one number following a text string) is difficult in Java.

• Accordingly, let us develop a useful method to read a file in the above format -- a type of `properties' file.

• The library provides a StringTokenizer object that performs rudimentary lexical analysis.
• We will write a method to parse a single `property' string like "radius=9.5".

Here is how it can be done ( source file ):

// We need to import the StringTokenizer object in
// the java.util package:
import java.util.*;

public class FileIO4 {

    // Parameters:
    //   inString: the property string (e.g. "radius=0.9")
    //   property:  the property name (e.g., "radius")
    // The value is assumed to be a real number.

    public static double readProperty (String inString, String property)
    {
        // Obtain a copy of the StringTokenizer object.
	StringTokenizer st = new StringTokenizer (inString);
	
	// Get the first token, specifying the delimiter.
	String firstPart = st.nextToken ("=");
	
	// Trim whitespace on either side - a String function.
	firstPart = firstPart.trim ();
	
	System.out.println ("First part: " + firstPart);
	
	if (! firstPart.equals (property)){
	    System.out.println ("Improper string: " + inString);
	    System.exit (0);
	}
	
	// Get the next token, now allowing for end-of-line.
	String secondPart = st.nextToken (" =\t\n\r");
	
	// Trim whitespace.
	secondPart = secondPart.trim();
	
	System.out.println ("Second part: " + secondPart);
	
	// Read the number in the second part using the library's
	// Double object.
	try {
	    double d = Double.parseDouble (secondPart);
	    return d;
	}
	catch (NumberFormatException e) {
	    System.out.println ("Second part not a number: " + secondPart);
	    System.exit (0);
	}
	return 0;
    }

    public static void main (String[] argv)
    {
	// Test
	double d = readProperty ("x=5", "x");
	System.out.println (d);
	
	d = readProperty ("center.x=5", "center.x");
	System.out.println (d);
	
	d = readProperty ("center.x=5   ", "center.x");
	System.out.println (d);
	
	d = readProperty (" center.x = 5   ", "center.x");
	System.out.println (d);
	
    }

}

Note:

• We have used that strange new operator again to create a StringTokenizer.
• The string to be parsed is fed into this object in the new statement.
• The object so created has a nextToken() method that returns tokens, one at a time.
• A String object has a trim() method that trims off whitespace, returning the result as a String.
• Once we have a real number in a String, use the parseDouble in Double to extract the value.
• Finally, we have import'ed a library object (StringTokenizer by importing the package (java.util) containing it:

 import java.util.*;
 

Exercise 3.3: Use the above method, and the methods for reading to a file for the following task. Suppose we want to extract information from a file containing a description of a circle. For example (source file):

Circle:
  center.x=50
  center.y=60
  radius=20

Encapsulation: single file

Since the above methods of reading an integer etc are useful, let's a create a program unit or module to contain these methods.

We will rewrite these methods in the file ReadGeodata.java

import java.io.*;
import java.util.*;

class UsefulIO {

    // Read a string from the screen.
    public static String readString (String prompt)
    {
        // .... 
    }

    // Parse a string for a property.
    public static double readProperty (String inString, String property)
    {
        // .... 
    }


} // End of class UsefulIO


public class ReadGeoData {

    public static void main (String[] argv)
    {
	// Get file name
	String filename = UsefulIO.readString ("Enter filename: ");
	
	try {
	    // ... Now read the input lines and process them ... 
	}
	catch (IOException e) {
	    System.out.println (e);
	}
	
    }
    
} // End of ReadGeoData

Note:

• The useful methods are placed in a class called UsefulIO.

• The class UsefulIO is not a public class.

• To access methods in UsefulIO from another class, the class name is used (UsefulIO) along with the method name, with a period, as in:

  
     filename = UsefulIO.readString ("Enter filename: ");
  

• Both class'es are in the same text file (ReadGeodata.java).

• Only one class in a file can be public:
  • This class must have a main method.
  • Execution starts in this main method.
  • This class (ReadGeodata) must have the same name as the file (ReadGeodata.java) without the .java extension.

• Each class is compiled to a separate object file:
  • On compiling ReadGeodata.java, you get two files: ReadGeodata.class and UsefulIO.class.

• It logically organizes the code into readable/manegeable units.

• Data common to an encapsulated unit can be shielded from the outside.
  (Here we didn't have any data).

• Units can be tested in isolation.

• Units can be re-used.

Encapsulation: multiple files

To make a collection of methods truly useful, the encapsulation should be placed in a separate file.

We will place our I/O methods in the file UsefulIO.java :

import java.io.*;
import java.util.*;

public class UsefulIO {

    // Read a string from the screen.

    public static String readString (String prompt)
    {
        // ... 
    }

    // Parse a string for a property.
    
    public static double readProperty (String inString, String property)
    {
        // ... 
    }

    // ... Other useful methods ...

}

Next, these methods will be used in the file ReadGeodata2.java:

import java.io.*;

public class ReadGeoData2 {

    public static void main (String[] argv)
    {
	// Get file name:
	String filename = UsefulIO.readString ("Enter filename: ");

        // ... rest of code not shown ...
    }	
    
}

Note:

• The file UsefulIO.java is currently in the same directory as read_geodata3.java
• This need not be the case, as Java searches subdirectories when directed.

Packages

To help programmers and programming teams manage files, Java provides the ability to package related code.

Consider the following example:

• Create the file ReadGeodata3.java as follows:

  
  // Notice the import:
  import useful_io_pack.*;
  
  public class ReadGeoData3 {
  
      public static void main (String[] argv)
      {
          // Get file name:
  	String filename = UsefulIOSubunit.readString ("Enter filename: ");
  
          // ... rest of code not shown ...
      }	
      
  }
  

• Next, create the subdirectory useful_io_pack:

  
      mkdir useful_io_pack
  

• In this subdirectory, place the file UsefulIOSubunit.java :

  
  package useful_io_pack;
  // Must be the first statement in the file.
  
  import java.io.*;
  import java.util.*;
  
  public class UsefulIOSubunit {
  
      // Read a string from the screen.
      public static String read_string (String prompt)
      {
           // ... code not shown ... 
      }
  
      // Parse a string for a property.
      public static double read_property (String inString, String property)
      {
           // ... code not shown ...
      }
  
  } 
  

• Now compile ReadGeodata3.java.

What is going on?

• The compiler sees the import useful_io_pack statement in ReadGeodata3.java and looks for the package.

• A package is assumed to be available in some subdirectory off of the CLASSPATH.

• Finding the subdirectory useful_io_pack, the compiler looks for class'es inside and finds UsefulIOSubunit.

• You set your CLASSPATH to any list of directories that you want, to get the compiler to search those directories.

• Packages can have sub-packages, as long as the sub-packages are found in similarly-named subdirectories of the main package.