3.1. The problem

• Books teaching programming often initially avoid use of GUIs.
• Instead, a book will usually use some statement to read a value
  from the keyboard attached to a command shell window.
• This approach is adopted for two reasons:
  • the number of new ideas involved is smaller;
  • the amount of code needed is smaller.
• But in Java it has not been easy to read a value from the keyboard.

• My book on Java tries to introduce keyboard input as early as possible.
• The technical preface says ‘the horrors of Java's keyboard input are introduced early (Chapter 4):

  0008:       BufferedReader tKeyboard =0009:             new BufferedReader(new InputStreamReader(System.in));0010:       System.out.print("Type in your first number: ");0011:       String tFirstString = tKeyboard.readLine();0012:       double tFirst = Double.parseDouble(tFirstString);

  Note the use of both instance methods and class methods and the need to use the wrapper classes of the primitive types.’

• The code is horrible, and there are too many new ideas to explain.
• Whoops, there is another bit of hassle.
• The technical preface failed to mention yet another gotcha: the need for a throws clause forjava.io.IOException:

  0006:    public static void main(String[] pArgs) throws IOException

• Often a book introduces its own class for keyboard input in order to avoid these complications.
• I don't think it is not a good idea for a book to produce its own class.
• However, we need not go into the reasons here, as it's easy to do keyboard input in Java 5.

3.2. Simple uses of the Scanner class

• Java 5 provides a class calledScanner (in thejava.util package).
• This can be used for keyboard input.
• It allows you to write code like:

  0026:       Scanner tScanner = new Scanner(System.in);0027:       System.out.print("Type in your first number: ");0028:       double tFirst = tScanner.nextDouble();

• Note that you do not have to handlejava.io.IOException.

• Here is a complete program using this class:

  0021: import java.util.Scanner;                                 // SumProgNew.java0022: public class SumProgNew 0023: {0024:    public static void main(String[] pArgs)0025:    {0026:       Scanner tScanner = new Scanner(System.in);0027:       System.out.print("Type in your first number: ");0028:       double tFirst = tScanner.nextDouble();0029:       System.out.print("Type in your second number: ");0030:       double tSecond = tScanner.nextDouble();0031:       double tSum = tFirst + tSecond;0032:       System.out.println("The sum of " + tFirst + 0033:                          " and " + tSecond + " is " + tSum);0034:    }0035: }

• This program produces a dialogue like the following:

  0036: Type in your first number: 270037: Type in your second number: 420038: The sum of 27.0 and 42.0 is 69.0

3.3. Other details about the Scanner class

The classScanner allows you easily to associate a variable with one of a number of different input streams such as the keyboard, a file or a string:

0047:       Scanner tScannerKeyboard   = new Scanner(System.in);0048:       Scanner tScannerInputFile  = new Scanner(new File("input.txt"));0049:       Scanner tScannerSomeString = new Scanner(tSomeString);

You can then apply methods such asnextInt to read a value from the input stream. Here, an unchecked exceptionjava.util.InputMisMatchException will be thrown if the next token is not an int.

To avoid the possibility of this exception occurring, a method likehasNextInt can be used to determine if the next value is an int, as shown in this program:

0067: import java.util.Scanner;                                    // Analyse.java0068: public class Analyse0069: {0070:    public static void main(String[] pArgs)0071:    {0072:       Scanner tScanner = new Scanner(System.in);0073:       System.out.print("Type in a value: ");0074:       if (tScanner.hasNextInt()) {0075:          int tFirst = tScanner.nextInt();0076:          System.out.println("Got an int: " + tFirst);0077:       }0078:       else if (tScanner.hasNextDouble()) {0079:          double tFirst = tScanner.nextDouble();0080:          System.out.println("Got a double: " + tFirst);0081:       }0082:       else {0083:          String tFirst = tScanner.nextLine();0084:          System.out.println("Got a string: " + tFirst);0085:       }0086:    }0087: }

3.4. Reading more than one value from a line

TheScanner class also helps when you want the user to be able to type more than one value on a line. Suppose we want to read in an age, a height and the number of children. So the data might be something like:

42 1.85 2

0100:       String tLine = tKeyboard.readLine();0101:       StringTokenizer tTokens = new StringTokenizer(tLine);0102:       String tAgeString = tTokens.nextToken();0103:       int tAge = Integer.parseInt(tAgeString);0104:       String tHeightString = tTokens.nextToken();0105:       double tHeight = Double.parseDouble(tHeightString);0106:       String tNumberOfChildrenString = tTokens.nextToken();0107:       int tNumberOfChildren = Integer.parseInt(tNumberOfChildrenString);

However, thenextXXX methods of theScanner class can cope with several items being on the same line. So the data:

42 1.85 2

0120:       int tAge = tScanner.nextInt();0121:       double tHeight = tScanner.nextDouble();0122:       int tNumberOfChildren = tScanner.nextInt();

By default, tokens are assumed to be separated by whitespace. However, you can easily arrange for the scanner to use delimiters other than whitespace.

3.5. More about the Scanner class

• The API documentation for theScanner class contains a lot of easy-to-understand useful detail.

4.1. Details about the change

• Suppose we have an array such as:

  0132:       int[ ] tMonthStarts = 0133:             { 1,32,60,91,121,152,182,213,244,274,305,335 };0134:       System.out.println(Arrays.toString(tMonthStarts));

• One pattern of code we will frequently write involves looking at each element of the array:

  0136:       for (int tMonthNumber = 0; 0137:                tMonthNumber<tMonthStarts.length; tMonthNumber++)0138:       {0139:          System.out.println(tMonthStarts[tMonthNumber]);0140:       }

• Java 5 has an enhanced for statement that enables us to write this more succinctly:

  0141:       for (int tMonthStart : tMonthStarts)0142:       {0143:          System.out.println(tMonthStart);0144:       }

• This variant of the for statement is sometimes called aforeach loop or afor-in loop.

• The designers were not very adventurous with the syntax: they did not add any new keywords ...
• as they were worried that existing code might already be usingforeach orin as identifiers.

4.2. When can you use it?

• The new variant has the form:

  for ( decl : expr )

• expr has to deliver a value of the typeIterable.
• Iterable is an interface type declared as follows:

  0148: package java.lang;                                          // Iterable.java0149: import java.util.Iterator;0150: public interface Iterable 0151: {0152:    public Iterator iterator();0153: }

• Obviously, from the above example, arrays implement this interface.
• As we shall see later, we can also use foreach loops with the Collection classes as they also implement this interface.
• And, if we provide our own class that implements theIterable interface, we could also use a foreach loop with an object of that class.
• There are many situations where the traditional code for looking at each element will still have to be used, ...
• e.g., if you wish to know the element number containing the largest value of an array.

5.1. Using an ArrayList

• Java has a number of Collection classes.
• One of these isArrayList.
• It allows you to represent anarray whose size grows as you add more objects to it.
• There are a few classes similar toArrayList, all of which satisfy theList interface.

• Here is how you might add an element to anArrayList:

  0161:       List tList = new ArrayList();0162:       tList.add("Hello world");

• This results in aString being stored in the first element of theArrayList.
• Here is how you might later retrieve it:

  0163:       String tNewString = (String)tList.get(0);0164:       System.out.println(tNewString.substring(0, 5));

• You can store objects of any class in anArrayList.
• Usually, the objects you store in anArrayList will all be of the same class: this is called ahomogeneous list.
• However, occasionally you will want a mix.
• So let us add aDate object to thisArrayList:

  0165:       Date tDate = new Date();0166:       tList.add(tDate);

• You can do this becauseadd has a parameter of typeObject.

• The return type ofget is also of typeObject.
• For this reason, you will (probably) want to cast the result:

  0167:       Date tNewDate = (Date)tList.get(1);0168:       System.out.println(tNewDate.getMonth());

5.2. Storing an int in an ArrayList

• Suppose you want to store integers in anArrayList.
• Values of typeint are not objects.
• So, until now, it has been more tricky to storeints in aList.
• You can create an object of typejava.lang.Integer from anint and use that:

  0169:       int tNumber = 123;0170:       Integer tWrapper = new Integer(tNumber);0171:       tList.add(tWrapper);

• This process is known asboxing.

• The same sort of shenanigans take place on retrieval:

  0172:       Integer tNewWrapper = (Integer)tList.get(2);0173:       int tNewNumber = tNewWrapper.intValue();0174:       System.out.println(tNewNumber);

• This transfer of a value from an object into a variable is calledunboxing.
• You can do similar things for any of the primitive types ...
• because each primitive type (e.g.,double) has an associated class type called itswrapper type (e.g.,java.lang.Double).

5.3. Java 5 provides autoboxing and auto-unboxing

• It is a tedious to have to write this code.
• And with Java 5 we do not have to.
• Java 5 permits us to write:

  0175:       int tValue = 123;0176:       tList.add(tValue);0177:       int tNewValue = (Integer)tList.get(3);0178:       System.out.println(tNewValue);

• Behind the scenes, the boxing and unboxing still take place.
• So this is calledautoboxing andauto-unboxing.

5.4. Avoiding overuse of autoboxing and auto-unboxing

• It is probably not a good idea to overuse this new freedom.
• Consider the following program, and work out how much boxing/unboxing is happening:

  0182: public class Integers                                       // Integers.java0183: {0184:    public static void main(String[] pArgs)0185:    {0186:       Integer tWrapper = 127;0187:       Integer tNewWrapper = tWrapper + tWrapper;0188:       System.out.println(tNewWrapper);0189:       if (tWrapper<tNewWrapper)0190:       {0191:          System.out.println(tWrapper + " is less than " + tNewWrapper);0192:       }0193:       tNewWrapper = 127;0194:       if (tWrapper==tNewWrapper)0195:          System.out.println(tWrapper + " is equal to " + tNewWrapper);0196:       else0197:          System.out.println(tWrapper + " differs from " + tNewWrapper);0198:       tWrapper = 128;0199:       tNewWrapper = 128;0200:       if (tWrapper==tNewWrapper)0201:          System.out.println(tWrapper + " is equal to " + tNewWrapper);0202:       else0203:          System.out.println(tWrapper + " differs from " + tNewWrapper);0204:    }0205: }

• The above program produces the following output:

  0206: 2540207: 127 is less than 2540208: 127 is equal to 1270209: 128 differs from 128

• The last two lines of output need some explanation.
• Brett McLaughlin and David Flanagan have produced an excellent book on Java 5 ([21]).
• In it, they say that ‘the Java specification indicates that certain primitives are always to be boxed into the same immutable wrapper objects. These objects are then cached and reused, with the expectation that these are commonly used objects. These special values are theboolean valuestrue andfalse, allbyte values,short andint values between -128 and 127, and anychar in the range\u0000 to\u007F.’
• So you may get surprising results from using the equality operator.
• McLaughlin and Flanagan conclude: ‘you have to watch out for this, as it can result in some very tricky, hard-to-find bugs’.

6.1. The problem

• Suppose we want a method that performs some operation on a collection of values.
• We could get the caller of the method to store these values in an array ...
• and get that passed as an argument to the method.
• However, suppose instead we want to write a method that can handle any number of arguments.
• This is possible in Java 5.

6.2. The details of the change

Suppose there is a method callediEvaluate that expects as arguments adouble and any number ofints. Here are some examples of a call of this method:

0214:       double tResult = iEvaluate(2.7, 25, 2, -5, 42, -10);0215:       System.out.println(tResult);0216:       tResult = iEvaluate(4.2, 42);0217:       System.out.println(tResult);0218:       tResult = iEvaluate(4.2);0219:       System.out.println(tResult);

And here is a possibleiEvaluate method:

0221:    private static double iEvaluate(double pFactor, int... pValues)0222:    {0223:       int tSum = 0;0224:       for (int tValue : pValues)0225:          tSum += tValue;0226:       return tSum/pFactor;      0227:    }

Theint... signifies that the remaining arguments areints. Within the method, this parameter behaves like an array and so the method can use a foreach loop.

7.1. A new class for formatted printing

Java 5 introduces a new class calledjava.util.Formatter. The API documentation for this class is at [31]. It says: ‘Formatted printing for the Java language is heavily inspired by C's printf. Although the format strings are similar to C, some customizations have been made to accommodate the Java language and exploit some of its features. Also, Java formatting is more strict than C's; for example, if a conversion is incompatible with a flag, an exception will be thrown. In C inapplicable flags are silently ignored. The format strings are thus intended to be recognizable to C programmers but not necessarily completely compatible with those in C.’

7.2. Some examples of the use of printf

Here are some examples of the use ofprintf:

0242:       System.out.printf("%3d %1.2f%n%d%n", 0243:                         tAge, tHeight, tNumberOfChildren);0244:       String tFormat = 0245:             "Age is %d, height is %f%nNo. of children is %d%n";0246:       System.out.printf(tFormat, tAge, tHeight, tNumberOfChildren);0247:       Calendar tNow = Calendar.getInstance();0248:       System.out.printf("%tT%n", tNow);  0249:       System.out.printf("%tY-%tm-%td%n", tNow, tNow, tNow);0250:       System.out.printf("%tH:%<tM:%<tS%n", tNow);

The above code produces output like the following:

0253:  42 1.850254: 20255: Age is 42, height is 1.8500000256: No. of children is 20257: 08:03:390258: 2004-08-120259: 08:03:39

Theprintf method used above is from thejava.io.PrintStream package.

8.1. The problem

• Suppose we have a class that can represent two-dimensional shapes:

  0260: public class Shape                                             // Shape.java0261: {0262:    private int iX, iY;0263:    public Shape(int pX, int pY)0264:    {0265:       iX = pX; iY = pY;0266:    }0267:    public int getX()0268:    {0269:       return iX;0270:    }0271:    public int getY()0272:    {0273:       return iY;0274:    }0275:    public Shape translate(int pX, int pY)0276:    {0277:       return new Shape(iX + pX, iY + pY);0278:    }0279:    public boolean equals(Object pObject)0280:    { 0281:       return iX==((Shape)pObject).iX && iY==((Shape)pObject).iY;0282:    }0283:    public String toString()0284:    {0285:       return iX + ":" + iY;0286:    }0287: }

• You will see that this class has nosetXXX methods.
• So, when an object of this class has been created, it cannot then be changed.
• The objects of this class are said to beimmutable.
• However, the class does provide a method calledtranslate.
• When applied to some Shape, it produces a new Shape that is (pX,pY) away from the first Shape:

  Shape tShape = new Shape(100, 200);Shape tNewShape = tShape.translate(1, 2);System.out.println(tNewShape);

• Suppose we now want a type for special 2D shapes that are circles.
• We could represent circles by using a class calledCircle that is derived fromShape.
• Besides theiX andiY fields thatShapes have,Circles also need aniRadius field:

  0288: public class Circle extends Shape                             // Circle.java0289: {0290:    private int iRadius;0291:    public Circle(int pX, int pY, int pRadius) {0292:       super(pX, pY);0293:       iRadius = pRadius;0294:    }0295:    public int getRadius()0296:    {0297:       return iRadius;0298:    }0299:    public Shape translate(int pX, int pY)0300:    {0301:       return new Circle(getX() + pX, getY() + pY, iRadius);0302:    }0303:    public boolean equals(Object pObject)0304:    { 0305:       return super.equals(pObject) &&0306:                 iRadius==((Circle)pObject).iRadius;0307:    }0308:    public String toString()0309:    {0310:       return super.toString() + ":" + iRadius;0311:    }0312: }

• Note that thetranslate method creates aCircle object.
• In Java 1.4, the method has to have a return type ofShape:

  0299:    public Shape translate(int pX, int pY)

• Because it returns aShape, a client will have to cast if it wants to get aCircle:

  0331:                Circle tCircle = new Circle(x, y, radius);0332:                Circle tNewCircle = (Circle)tCircle.translate(1, 2);0333:                System.out.println(tNewCircle.getRadius());

• Suppose instead you declaretranslate with a return type ofCircle:

  0367:    public Circle translate(int pX, int pY)

• A Java 1.4 compiler will produce:

  0381: Circle.java:12: translate(int,int) in Circle cannot 0382: override translate(int,int) in Shape; attempting to use 0383: incompatible return type0384: found   : Circle0385: required: Shape0386:    public Circle translate(int pX, int pY)0387:                  ^

• This is saying this is an incorrect overriding ofShape'stranslate method.

8.2. Java 5 introduces covariant return types

• With Java 5 this has changed: Java 5 permitscovariant return types.
• This means that Java 5 does not insist that the return type of an overriding method is the same type as the return type of the method in the superclass: it can be a subclass of that return type.
• So, in Java 5,Circle'stranslate method can have the header:

  0367:    public Circle translate(int pX, int pY)

• And the call of this method can then be simplified to:

  0406:                Circle tCircle = new Circle(x, y, radius);0407:                Circle tNewCircle = tCircle.translate(1, 2);0408:                System.out.println(tNewCircle.getRadius());

8.3. Changes to the clone method

• This also brings one benefit to classes that provide aclone method that overridesObject'sclone method: ...
• such classes no longer have to declare theirclone method with a return type ofObject.
• Suppose a program contains the code:

  Shape tShape = new Shape(100, 200);Shape tShapeSame = tShape;

  then bothShape variables point to the same object.
• Suppose the classShape provides aclone method that overridesObject'sclone method.
• Prior to Java 5, this would have to be declared as:

  public Object clone(){   ...}

• And the caller would have to cast the result of the call ofclone:

  Shape tShape = new Shape(100, 200);Shape tShapeCopy = (Shape)tShape.clone();

• In Java 5,Shape can declare itsclone method using:

  public Shape clone(){   ...}

• The call can then be simplified to:

  Shape tShape = new Shape(100, 200);Shape tShapeCopy = tShape.clone();

9.1. The problem

• Some objects are associated with a small set of values.
• And names are associated with each of the possible values.
• Suppose we are representing a piece of four part harmony.
• We want to refer to the four parts assoprano,alto,tenor andbass.
• Some programming languages provide a means for declaring types
  that represent a small number of values.
• Such types areenumeration types,enumerated types orenum types.
• First language: Pascal. Later: Modula-2, Ada, C, C++ and C#.
• Notable exception (until now): Java.

9.2. Java 5 has enumeration types

• In Java 5, an enum type is produced using anenum declaration.
• This lists the constants that denote the values of the type:

  0432:    private enum Day0433:    {0434:       Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday0435:    }

• Note: althoughforeach andin have not been added to the language, the keywordenum has.
• http://java.sun.com/developer/technicalArticles/J2SE/google/limoore.html gives an interview with Li Moore, software engineer at Google, about his company's switch from J2SE version 1.4 to 5.0. Li says ‘ We've wanted enums and generics at Google for years. ...we ran into the same problem that everyone does: enum is now a reserved word. That's an easy, if tedious, one to fix.’

• One of the documents supporting the introduction of enum types says: ‘Theenum declaration is a special kind of class declaration. Anenum type has public, self-typed members for each of the namedenum constants. All enum classes have high-qualitytoString,hashCode andequals methods.’
• On the next screen, there is a program that uses the typeDay.
• Hidden in this code is a call of thetoString method.

• 0430: public class SimpleDayProg                             // SimpleDayProg.java0431: {0432:    private enum Day0433:    {0434:       Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday0435:    }0436:    public static void main(String[] pArgs)0437:    {0438:       Day tToday = Day.Wednesday;   System.out.println(tToday);0439:    }0440: }

• This program outputs:

  0441: Wednesday

9.3. The methods provided by java.lang.Enum

• As mentioned earlier,
  each enum type hastoString,hashCode andequals methods.
• This is because each enum type extends the typejava.lang.Enum.
• Besides those methods,java.lang.Enum also declares methods calledcompareTo,valueOf,values andordinal.

• Here is some code illustrating the use of some of these methods:

  0452:       Scanner tScanner = new Scanner(System.in);0453:       String tInputString = tScanner.next();0454:       Day tInputDay = Day.valueOf(tInputString);0455:       switch (tInputDay)0456:       {0457:          case Sunday:   System.out.println("wash car");   break;0458:          case Saturday: System.out.println("do nothing"); break;0459:          default:       System.out.println("go to work"); break;0460:       }0461:       for (Day tDay : Day.values())0462:       {0463:          System.out.println(tDay + " " + tDay.ordinal());0464:       }

• This code produces the following dialogue:

  0500: Sunday0501: wash car0502: Sunday 00503: Monday 10504: Tuesday 20505: Wednesday 30506: Thursday 40507: Friday 50508: Saturday 6

9.4. The classes EnumSet and EnumMap

You can use the new classjava.util.EnumSet to create a set of enums and the new classjava.util.EnumMap to create a map that uses enums as keys.

Here is some code illustrating two uses ofEnumSet:

0472:       Day tToday = Day.Wednesday;0473:       Day[] tDayValues = Day.values();0474:       for (int tDayNumber = Day.Tuesday.ordinal();0475:                tDayNumber<=Day.Thursday.ordinal(); tDayNumber++)0476:       {0477:          Day tDay = tDayValues[tDayNumber];0478:          System.out.println(tDay + " " + tDay.compareTo(tToday));0479:       }0480:       for (Day tDay : EnumSet.range(Day.Tuesday, Day.Thursday))0481:       {0482:          System.out.println(tDay + " " + tDay.compareTo(tToday));0483:       }0484:       for (Day tDay : Day.values())0485:       {0486:          if (tDay.toString().length()==6)0487:          {0488:             System.out.println(tDay + " is a 6 letter day");0489:          }0490:       }0491:       for (Day tDay : Day.values())0492:       {0493:          if (EnumSet.of(Day.Sunday, Day.Monday, Day.Friday).contains(tDay))0494:          {0495:             System.out.println(tDay + " is a 6 letter day");0496:          }0497:       }

The above code produces the output:

0511: Tuesday -10512: Wednesday 00513: Thursday 10514: Tuesday -10515: Wednesday 00516: Thursday 10517: Sunday is a 6 letter day0518: Monday is a 6 letter day0519: Friday is a 6 letter day0520: Sunday is a 6 letter day0521: Monday is a 6 letter day0522: Friday is a 6 letter day

9.5. Providing fields and methods in an enum type

• An enum declaration can also supply fields and methods.
• These can be used on values of the enum type.
• Above the enum declaration was declared inside a class declaration.
• When enum declarations become more complicated, they are best stored in a separate file.

• Suppose the fileDay.java contains:

  0523: public enum Day                                                  // Day.java0524: {0525:    Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday;0526:    public String toString()0527:    {0528:       return super.toString().substring(0, 3);0529:    }0530:    private static Day[] iDayValues = Day.values();0531:    public static Day getFirst()0532:    {0533:       return iDayValues[0];0534:    }0535:    public boolean isLast()0536:    {0537:       return this==iDayValues[iDayValues.length - 1];0538:    }0539:    public Day getNext()0540:    {0541:       int tNewPos = ordinal() + 1;0542:       if (tNewPos==iDayValues.length)0543:          return iDayValues[0];0544:       else0545:          return iDayValues[tNewPos];0546:    }0547: }

• The above enum type could then be used in the following way:

  0548: public class DayProg                                         // DayProg.java0549: {0550:    public static void main(String[] pArgs)0551:    {0552:       System.out.println("getFirst: " + Day.getFirst());0553:       Day tToday = Day.Wednesday;0554:       System.out.println("tToday.isLast: " + tToday.isLast());0555:       System.out.println("Day.Saturday.isLast: " + Day.Saturday.isLast());      0556:       for (Day tDay : Day.values())0557:       {0558:          System.out.print(tDay.getNext() + " ");0559:       }0560:       System.out.println();0561:    }0562: }

• The above code outputs:

  0563: getFirst: Sun0564: tToday.isLast: false0565: Day.Saturday.isLast: true0566: Mon Tue Wed Thu Fri Sat Sun

9.6. Associating values with each enum value

• Each value of an enum type can have associated values.
• The enum type needs an appropriate constructor:

  0567: public enum ShopDay                                          // ShopDay.java0568: {0569:    Sunday   (new Time("10:00"), new Time("16:00")),0570:    Monday   (new Time("08:00"), new Time("17:30")),0571:    Tuesday  (new Time("08:00"), new Time("17:30")),0572:    Wednesday(new Time("08:00"), new Time("17:30")),0573:    Thursday (new Time("08:00"), new Time("17:30")),0574:    Friday   (new Time("08:00"), new Time("17:30")),0575:    Saturday (new Time("09:00"), new Time("12:30"));0576:    private Time iStartTime;0577:    private Time iFinishTime;0578:    private ShopDay(Time pStartTime, Time pFinishTime)0579:    {0580:       iStartTime = pStartTime;0581:       iFinishTime = pFinishTime;0582:    }0583:    public Time getStartTime()0584:    {0585:       return iStartTime;0586:    }0587:    public Time getFinishTime()0588:    {0589:       return iFinishTime;0590:    }0591: }

• 0592: public class Time                                               // Time.java0593: {0594:    private String iString;0595:    public Time(String pString)0596:    {0597:       iString = pString;0598:    }0599:    public String toString()0600:    {0601:       return iString;0602:    }0603: }

• 0604: public class ShopDayProg                                 // ShopDayProg.java0605: {0606:    public static void main(String[] pArgs)0607:    {0608:       for (ShopDay tShopDay : ShopDay.values())0609:       {0610:          System.out.println(tShopDay + " " + tShopDay.getStartTime() +0611:                                        " " + tShopDay.getFinishTime());0612:       }0613:    }0614: }

• The above program produces the output:

  0615: Sunday 10:00 16:000616: Monday 08:00 17:300617: Tuesday 08:00 17:300618: Wednesday 08:00 17:300619: Thursday 08:00 17:300620: Friday 08:00 17:300621: Saturday 09:00 12:30

9.7. Is an enum type a class type?

• In other languages, a unique int is associated with each enum value.
• If a variable that is of enum type is assigned a value, the appropriate integer value is stored in the variable.
• However, the literature about Java 5 refers to an enum declaration as being aspecial kind of class declaration.
• Probably the case that each enum value has an associated object.
• When an enum variable is assigned an enum value, a pointer to the appropriate enum object is assigned to the enum variable.
• So,== operator gives same result as theequals method.

9.8. Differences from C#

• There are two main differences from C#:
  1. In C#, you can use the relational operators (<,<=,> and>=):

     tDay1<=tDay2

     This is not possible in Java 5. Instead you could write:

     tDay1.compareTo(tDay2)<=0

  2. In C#, it is not possible to declare constructors, fields and methods in an enum declaration.

9.9. More about enumeration types

• See Item 21 of [2], page 13 of [24] or pages 485 to 496 of [6] for details about how to mimic enumeration types in Java 1.4 (or earlier).
• See [28], [29], [30], [21], [18] and [23] for other information about the enumeration types of Java 5.

10.1. Adding annotations to programs

• Java 5 allows you to annotate elements of a program:

  0633:    @NeedsFurtherTesting0634:    private static double iGetDouble(String pLabel)0635:    {0636:       System.out.print("Type in your " + pLabel + " number: ");0637:       Scanner tScanner = new Scanner(System.in);0638:       return tScanner.nextDouble();0639:    }0640:    @NeedsFurtherTesting0641:    @ToDo(programmer="Barry Cornelius",0642:          importance=ToDo.Importance.High,0643:          deadline="2004-08-31")0644:    private static double iFindSum(double pLHS, double pRHS)0645:    {0646:       return pLHS + pRHS;0647:    }

• Besides methods, you can also annotate other declarations.
• These annotations need not affect a program's semantics.
• Instead, tools can read these annotations and process them.
• Javadoc comments and the@deprecated tag could now be replaced.
• In some situations, you need to provide stylised Java source code, code that always takes a particular form.
• By introducing an annotation, you could shorten the amount of code you write and get a tool to generate the real Java source code for you from your template.
• The Java 5 release provides such a tool: it is calledapt.

10.2. Declaring annotation types

• To use an annotation, you will need to declare anannotation type:

  0649: public @interface NeedsFurtherTesting            // NeedsFurtherTesting.java0650: {0651: }

  0652: public @interface ToDo                                          // ToDo.java0653: {0654:    public enum Importance {VeryHigh, High, Medium, Low};0655:    public String programmer();0656:    public Importance importance();0657:    public String deadline();0658: }

• An annotation type declaration looks very much like an interface type declaration.

10.3. The use of java.lang.Override

• The APIs of Java 5 provide seven annotation types.
• There are three injava.lang:
  Deprecated,Override andSuppressWarnings.
• And four injava.lang.annotation:
  Documented,Inherited,Retention andTarget.
• I just want to look at one of these:
  java.lang.Override.

• This annotation type is documented in the API documentation as:

  java.langAnnotation Type Override@Target(value=METHOD)@Retention(value=SOURCE)public @interface OverrideIndicates that a method declaration is intended to override amethod declaration in a superclass. If a method is annotatedwith this annotation type but does not override a superclassmethod, compilers are required to generate an error message.

• The declaration ofOverride is itself annotated with two annotations:
  aTarget annotation and aRetention annotation.
• TheTarget indicates thatOverride can only be used to annotate method declarations.
• TheRetention indicates thatOverride does not have to be passed into the.class file that the compiler is generating.

• Suppose a classShape includes the declarations:

  0682:    public int hashcode()0683:    {0684:       return 0;0685:    }0686:    public String toString(String pString)0687:    {0688:       return iX + ":" + iY;0689:    }

• Herehashcode is not overridingObject'shashCode ...
  Similarly,toString is not overridingObject'stoString method ...

• The above code is legal, but is not doing what you intended.
• When you come to use these methods,
  you will get a result different from what you expected. For example:

  0725:          Shape tShape = shapes[shapeNumber];0726:          System.out.println(tShape);

  will use thetoString method from the classObject.
• The above is so typical of what happens: it is so easy to get the wrong spelling or the wrong parameters.

• If you are using Java 5, always use@Override when overriding:

  0753:    @Override0754:    public int hashcode()0755:    {0756:       return 0;0757:    }0758:    @Override0759:    public String toString(String pString)0760:    {0761:       return iX + ":" + iY;0762:    }

• A Java 5 compiler will produce two compilation errors saying:

  method does not override a method from its superclass

• In my opinion, it would be better to force you to document overriding.
• This is what is done in C# (and in Eiffel).

10.4. Annotations for Web Services

• One of the fads during the last couple of years has been the creation ofWeb Services.
• In its simplest form, this is the ability for the code of a method to use the HTTP protocol to call a method executed by a web server at a WWW site somewhere in the world.
• The Java Community Process (JSR 181) has produced a set of annotation types for Web Services.

• So, when you are providing a Web Service, you are able to write:

  0764: import javax.jws.WebMethod;                        // HelloWorldService.java0765: import javax.jws.WebService;0766: @WebService0767: public class HelloWorldService0768: {0769:    @WebMethod0770:    public String helloWorld()0771:    {0772:       return "Hello World!";0773:    }0774: }

• The@WebService says that this class is providing methods that we would like programs running elsewhere to be able to execute.
• And the@WebMethod says that this is one of the methods that we are happy for programs to execute.

• The actual services that are offered by a Web Service are documented using an XML notation known as theWeb Services Description Language orWSDL ([22]).
• The developers of JSR 181 ensured that its design makes it easy to write tools to produce WSDL documents from Java source code and vice versa.
• See [17] for more details of JSR 181.

10.5. Other annotations

The Java Community Process (JSR 250) has also produced ‘annotations for common semantic concepts in the J2SE and J2EE platforms that apply across a variety of individual technologies. With the addition of JSR 175 ... we envision that various JSRs will use annotations to enable a declarative style of programming’. See [34] for more details of JSR 250.

11.1. The problem

• List and its supporting classes (such asArrayList) can be used to manipulate lists of objects of any classes.
• We can have a list of strings, a list of people, a list of shapes, ...
• This is possible because the interface and the classes are written in terms of the classObject.
• It is possible to add objects of many different classes to a list.
• Most of the time we will not want to do this.
• If we do it inadvertently, this error will not be detected at compilation time as what we have written is allowed.

• For example, suppose we have aList:

  0781:        List tList = new ArrayList();

  in which we are storingShapes, i.e., we normally do something like:

  0782:        Shape tShape = new Shape(100, 200);0783:        tList.add(tShape);

  or:

  0784:        Circle tCircle = new Circle(100, 200, 10);0785:        tList.add(tCircle);

• We can retrieve elements as follows:

  0786:        Shape tShapeGet0 = (Shape)tList.get(0); 0787:        System.out.println(tShapeGet0);0788:        Shape tShapeGet1 = (Shape)tList.get(1); 0789:        System.out.println(tShapeGet1);

  and this code produces the output:

  0795: 100:2000796: 100:200:10

• Suppose our code adds a value of some other type to this list:

  0790:        tList.add("hello world");

• When we come to retrieve this value:

  0791:        Shape tShapeGet2 = (Shape)tList.get(2); 0792:        System.out.println(tShapeGet2);

  our program will collapse with aClassCastException:

  0797: Exception in thread "main" java.lang.ClassCastException0798:         at ListShape.main(ListShape.java:17)

• Unless we detect this when testing, our program embarassingly crashes when someone uses it.

11.2. Java 5 provides parameterized types

• Java 5 permits the declaration of aparameterized type (also known as ageneric type).
• This is a class type or an interface type that is written in terms of some unspecified type.
• Some of the Java 5 APIs have parameterized types.
• In particular, the Collection classes have been rewritten so that they are parameterized types.

• For example, the Java 5 API documentation says:

  Class ArrayList<E>

• Similarly, the interface typeList is now documented as:

  Interface List<E>

• When we come to use these types, we indicate the type we want to use instead ofE:

  0805:        List<Shape> tList = new ArrayList<Shape>();

• The code of theadd method has been altered. Instead of:

  public boolean add(Object o)

  theadd method is now documented as:

  public boolean add(E o)

• So, we can add elements as before:

  0806:        Shape tShape = new Shape(100, 200);0807:        tList.add(tShape);0808:        Circle tCircle = new Circle(100, 200, 10);0809:        tList.add(tCircle);

• However, if our code inadvertently adds a value of the wrong type:

  0814:        tList.add("hello world");

• then that statement will fail to compile:

  0819: ListShape.java:16: cannot find symbol0820: symbol  : method add(java.lang.String)0821: location: interface java.util.List<Shape>0822:        tList.add("hello world");0823:             ^

• This is a lot better than crashing with aClassCastException.

• There is one other benefit.get has been changed from:

  public Object get(int index)

  to:

  public E get(int index)

• Because of this, we can retrieve a value without having to use a cast:

  0810:        Shape tShapeGet0 = tList.get(0); 0811:        System.out.println(tShapeGet0);0812:        Shape tShapeGet1 = tList.get(1); 0813:        System.out.println(tShapeGet1);

• When a compiler compiles code containing the use of a parameterized type,erasure takes place.
• This means that the intermediate code generated for lines 805 to 813 is the same as that generated for lines 781 to 789.

  0805:        List<Shape> tList = new ArrayList<Shape>();0806:        Shape tShape = new Shape(100, 200);0807:        tList.add(tShape);0808:        Circle tCircle = new Circle(100, 200, 10);0809:        tList.add(tCircle);0810:        Shape tShapeGet0 = tList.get(0); 0811:        System.out.println(tShapeGet0);0812:        Shape tShapeGet1 = tList.get(1); 0813:        System.out.println(tShapeGet1);

  0781:        List tList = new ArrayList();0782:        Shape tShape = new Shape(100, 200);0783:        tList.add(tShape);0784:        Circle tCircle = new Circle(100, 200, 10);0785:        tList.add(tCircle);0786:        Shape tShapeGet0 = (Shape)tList.get(0); 0787:        System.out.println(tShapeGet0);0788:        Shape tShapeGet1 = (Shape)tList.get(1); 0789:        System.out.println(tShapeGet1);

11.3. Using a parameterized type for a parameter

The typeList<Shape> can be used just like any other type. So we can produce methods that have this as their return type, or a method that has this as the type of one of its parameters:

0860:    private static void printList1(List<Shape> pList)0861:    {0862:       Iterator<Shape> tIterator = pList.iterator();0863:       while (tIterator.hasNext())0864:       {0865:          Shape tShape = tIterator.next();0866:          System.out.println("X is " + tShape.getX());0867:       }0868:    }

However, with Java 5, many of the uses ofIterator should be replaced by a foreach statement. So the above can be simplified to:

0869:    private static void printList2(List<Shape> pList)0870:    {0871:       for (Shape tShape : pList)0872:       {0873:          System.out.println("X is " + tShape.getX());0874:       }0875:    }

Things get interesting when you want to write a method that works for any homogeneous list: a list of shapes, a list of strings, and so on. The new notation:

List<?>

0876:    private static void printList3(List<?> pList)0877:    {0878:       Iterator<?> tIterator = pList.iterator();0879:       while (tIterator.hasNext())0880:       {0881:          Object tObject = tIterator.next();0882:          System.out.println(tObject);0883:       }0884:    }

Once again, this can be simplified to:

0885:    private static void printList4(List<?> pList)0886:    {0887:       for (Object tObject : pList)0888:       {0889:          System.out.println(tObject);0890:       }0891:    }

Suppose instead you want to provide a method that works only for aList where the element type is the typeShape or any of its subclasses. You may be tempted to use one of the methods given earlier, a method that has a parameter of typeList<Shape>. However, a class that implements the interfaceList<Circle> cannot be used as an argument to this method. Instead we can use:

0892:    private static void printList5(List<? extends Shape> pList)0893:    {0894:       for (Shape tShape : pList)0895:       {0896:          System.out.println("X is " + tShape.getX());0897:       }0898:    }

11.4. Java 5 also has parameterized methods

Besides parameterized interface types and parameterized class types, Java 5 also permits parameterized methods. So the last two examples can be rewritten as:

0899:    private static <GType> void printList6(List<GType> pList)0900:    {0901:       for (GType tGType : pList)0902:       {0903:          System.out.println(tGType);0904:       }0905:    }0906:    private static <GShape extends Shape> void printList7(List<GShape> pList)0907:    {0908:       for (GShape tGShape : pList)0909:       {0910:          System.out.println("X is " + tGShape.getX());0911:       }0912:    }

11.5. Defining our own parameterized type

Besides using the parameterized types that are in the APIs, we could define our own parameterized type. Suppose we want a collection object that remembers seven things: as soon as you add more than seven items, it forgets about something that has already been stored. Below there is a class calledLimitedMemory that can be used to represent such an object.

It is assumed that all the objects that are to be stored in aLimitedMemory object are all of the same type. For this reason, it is written as a parameterized class type. Rather than useE, I have chosen to use the nameGType.

One other thing: it is also assumed that each object has a value, and so each object is of a class that implements theValuable interface. The code below introduces one type that meets these constraints; it is the typeName.

0914: public interface Valuable                                   // Valuable.java0915: {0916:    public int value();0917: }

0918: public class Name implements Valuable                           // Name.java0919: {0920:    private String iString;0921:    public Name(String pString)0922:    {0923:       iString = pString;0924:    }0925:    public String toString()0926:    {0927:       return iString;0928:    }0929:    public int value()0930:    {0931:       return iString.length();0932:    }0933: }

0934: import java.util.ArrayList;                            // LimitedMemory.java0935: import java.util.Iterator;0936: import java.util.Random;0937: public class LimitedMemory <GType extends Valuable> 0938:       implements Iterable<GType>0939: {0940:    private static final int iCapacity = 7; 0941:    private ArrayList<GType> iArrayList;0942:    private Random iRandom;0943:    public LimitedMemory()0944:    {0945:       iArrayList = new ArrayList<GType>(iCapacity);0946:       iRandom = new Random();0947:    }0948:    public void add(GType pGType)0949:    {0950:       if (iArrayList.size()<iCapacity)0951:          iArrayList.add(pGType);0952:       else0953:          iArrayList.set(iRandom.nextInt(iCapacity), pGType);0954:    }0955:    public String toString()0956:    {0957:       return iArrayList.toString();0958:    }0959:    public int value()0960:    {0961:       int tSum = 0;0962:       for (GType tGType : iArrayList)0963:       {0964:          tSum += tGType.value();0965:       }0966:       return tSum;0967:    }0968:    public Iterator<GType> iterator()0969:    {0970:       return iArrayList.iterator();0971:    }0972: }

Here are two fragments of code that use aLimitedMemory object:

0978:       LimitedMemory<Name> tLimitedMemory = new LimitedMemory<Name>();0979:       tLimitedMemory.add(new Name("jim"));0980:       tLimitedMemory.add(new Name("bert"));

1031:       iMyPrintln(tLimitedMemory);1032:       System.out.println(" " + tLimitedMemory.value());1033:       LimitedMemory<Name> tLimitedMemory2 = new LimitedMemory<Name>();1034:       tLimitedMemory2.add(new Name("jim"));1035:       tLimitedMemory2.add(new Name("bert"));1036:       tLimitedMemory2.add(new Name("jill"));1037:       System.out.println(iBiggestCost(tLimitedMemory, tLimitedMemory2));

The above code uses the following subsidiary methods:

1039:    private static void iMyPrintln(LimitedMemory<Name> pLimitedMemory)1040:    {1041:       System.out.print("+");1042:       for (Name tName : pLimitedMemory)1043:       {1044:          System.out.print(tName + "+");1045:       }1046:       System.out.println();1047:    }1048:    private static 1049:       <GType1 extends Valuable, GType2 extends Valuable> 1050:          int iBiggestCost(1051:             LimitedMemory<GType1> pLimitedMemory1,1052:             LimitedMemory<GType2> pLimitedMemory2)1053:    {1054:       return Math.max(pLimitedMemory1.value(), pLimitedMemory2.value());1055:    }

11.6. More about parameterized types and methods

See [5], [21], [1], [11], [12] and [16] for other information about parameterized types and methods.