Cleaned up code examples from Chapter 8 (Methods)

Author: jbloch

src/effectivejava/chapter8/item50/Attack.java renamed to src/effectivejava/chapter8/item50/Attacks.java

@@ -1,17 +1,17 @@
 package effectivejava.chapter8.item50;
 import java.util.*;
 
-// Two attacks on the internals of an "immutable" period
-public class Attack {
+// Two attacks on the internals of an "immutable" period (232-3)
+public class Attacks {
     public static void main(String[] args) {
-        // Attack the internals of a Period instance  (page 232)
+        // Attack the internals of a Period instance  (Page 232)
         Date start = new Date();
         Date end = new Date();
         Period p = new Period(start, end);
         end.setYear(78);  // Modifies internals of p!
         System.out.println(p);
 
-        // Second attack on the internals of a Period instance
+        // Second attack on the internals of a Period instance  (Page 233)
         start = new Date();
         end = new Date();
         p = new Period(start, end);

src/effectivejava/chapter8/item50/Period.java

@@ -1,7 +1,7 @@
 package effectivejava.chapter8.item50;
 import java.util.*;
 
-// Broken "immutable" time period class - Page 231-3
+// Broken "immutable" time period class (Pages 231-3)
 public final class Period {
     private final Date start;
     private final Date end;
@@ -31,7 +31,7 @@ public String toString() {
         return start + " - " + end;
     }
 
-//    // Repaired constructor - makes defensive copies of parameters
+//    // Repaired constructor - makes defensive copies of parameters (Page 232)
 //    public Period(Date start, Date end) {
 //        this.start = new Date(start.getTime());
 //        this.end   = new Date(end.getTime());
@@ -40,7 +40,7 @@ public String toString() {
 //            throw new IllegalArgumentException(
 //                    this.start + " after " + this.end);
 //    }
-
+//
 //    // Repaired accessors - make defensive copies of internal fields (Page 233)
 //    public Date start() {
 //        return new Date(start.getTime());

src/effectivejava/chapter8/item52/Champagne.java

@@ -1,5 +1,6 @@
 package effectivejava.chapter8.item52;
 
+// Classification using method overrriding (Page 239)
 class Champagne extends SparklingWine {
     @Override String name() { return "champagne"; }
 }

src/effectivejava/chapter8/item52/CollectionClassifier.java

@@ -26,9 +26,4 @@ public static void main(String[] args) {
         for (Collection<?> c : collections)
             System.out.println(classify(c));
     }
-       // Repaired  static classifier method. (Page 240)
-//    public static String classify(Collection<?> c) {
-//        return c instanceof Set  ? "Set" :
-//                c instanceof List ? "List" : "Unknown Collection";
-//    }
 }

src/effectivejava/chapter8/item52/FixedCollectionClassifier.java

@@ -0,0 +1,23 @@
+package effectivejava.chapter8.item52;
+
+import java.math.BigInteger;
+import java.util.*;
+
+// Repaired  static classifier method. (Page 240)
+public class FixedCollectionClassifier {
+    public static String classify(Collection<?> c) {
+        return c instanceof Set  ? "Set" :
+                c instanceof List ? "List" : "Unknown Collection";
+    }
+
+    public static void main(String[] args) {
+        Collection<?>[] collections = {
+                new HashSet<String>(),
+                new ArrayList<BigInteger>(),
+                new HashMap<String, String>().values()
+        };
+
+        for (Collection<?> c : collections)
+            System.out.println(classify(c));
+    }
+}

src/effectivejava/chapter8/item52/Overriding.java

@@ -2,6 +2,7 @@
 
 import java.util.List;
 
+// Classification using method overrriding (Page 239)
 public class Overriding {
     public static void main(String[] args) {
         List<Wine> wineList = List.of(

src/effectivejava/chapter8/item52/SetList.java

@@ -1,7 +1,7 @@
 package effectivejava.chapter8.item52;
 import java.util.*;
 
-// What does this program print? - Page 241
+// What does this program print? (Page 241)
 public class SetList {
     public static void main(String[] args) {
         Set<Integer> set = new TreeSet<>();

src/effectivejava/chapter8/item52/SparklingWine.java

@@ -1,5 +1,6 @@
 package effectivejava.chapter8.item52;
 
+// Classification using method overrriding (Page 239)
 class SparklingWine extends Wine {
     @Override String name() { return "sparkling wine"; }
 }

src/effectivejava/chapter8/item52/Wine.java

@@ -1,5 +1,6 @@
 package effectivejava.chapter8.item52;
 
+// Classification using method overrriding (Page 239)
 class Wine {
     String name() { return "wine"; }
 }

src/effectivejava/chapter8/item53/Varargs.java

@@ -2,23 +2,17 @@
 
 import java.util.stream.IntStream;
 
-// Sample uses of varargs
+// Sample uses of varargs (Pages 245-6)
 public class Varargs {
-
-    // Simple use of varargs - Page 245
+    // Simple use of varargs (Page 245)
     static int sum(int... args) {
         int sum = 0;
         for (int arg : args)
             sum += arg;
         return sum;
     }
 
-    // Simple use of varargs - Page 197
-    static int sum2(int... args) {
-        return IntStream.of(args).sum();
-    }
-
-//    // The WRONG way to use varargs to pass one or more arguments!  - Page 245
+//    // The WRONG way to use varargs to pass one or more arguments! (Page 245)
 //    static int min(int... args) {
 //        if (args.length == 0)
 //            throw new IllegalArgumentException("Too few arguments");
@@ -29,7 +23,7 @@ static int sum2(int... args) {
 //        return min;
 //    }
 
-    // The right way to use varargs to pass one or more arguments   - Page 246
+    // The right way to use varargs to pass one or more arguments (Page 246)
     static int min(int firstArg, int... remainingArgs) {
         int min = firstArg;
         for (int arg : remainingArgs)
@@ -38,7 +32,6 @@ static int min(int firstArg, int... remainingArgs) {
         return min;
     }
 
-
     public static void main(String[] args) {
         System.out.println(sum(1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
         System.out.println(min(1, 2, 3, 4, 5, 6, 7, 8, 9, 10));

src/effectivejava/chapter8/item55/Max.java

@@ -2,9 +2,9 @@
 
 import java.util.*;
 
-// Optionals     (P. 248) OK (Checked)
+// Using Optional<T> as a return type (Pages 249-251)
 public class Max {
-//    // Returns maximum value in collection - throws exception if empty
+//    // Returns maximum value in collection - throws exception if empty (Page 249)
 //    public static <E extends Comparable<E>> E max(Collection<E> c) {
 //        if (c.isEmpty())
 //            throw new IllegalArgumentException("Empty collection");
@@ -17,7 +17,7 @@ public class Max {
 //        return result;
 //    }
 
-//    // Returns maximum value in collection as an Optional<E>
+//    // Returns maximum value in collection as an Optional<E> (Page 250)
 //    public static <E extends Comparable<E>>
 //    Optional<E> max(Collection<E> c) {
 //        if (c.isEmpty())
@@ -31,7 +31,7 @@ public class Max {
 //        return Optional.of(result);
 //    }
 
-    // Returns max val in collection as Optional<E> - uses stream
+    // Returns max val in collection as Optional<E> - uses stream (Page 250)
     public static <E extends Comparable<E>>
     Optional<E> max(Collection<E> c) {
         return c.stream().max(Comparator.naturalOrder());
@@ -40,7 +40,9 @@ Optional<E> max(Collection<E> c) {
     public static void main(String[] args) {
         List<String> words = Arrays.asList(args);
 
-        // Using an optional to provide a chosen default value
+        System.out.println(max(words));
+
+        // Using an optional to provide a chosen default value (Page 251)
         String lastWordInLexicon = max(words).orElse("No words...");
         System.out.println(lastWordInLexicon);
     }

src/effectivejava/chapter8/item55/ParentPid.java

@@ -2,15 +2,17 @@
 
 import java.util.Optional;
 
-//    Page 250
+// Avoiding unnecessary use of Optional's isPresent method (Page 252)
 public class ParentPid {
     public static void main(String[] args) {
         ProcessHandle ph = ProcessHandle.current();
 
+        // Inappropriate use of isPresent
         Optional<ProcessHandle> parentProcess = ph.parent();
         System.out.println("Parent PID: " + (parentProcess.isPresent() ?
                 String.valueOf(parentProcess.get().pid()) : "N/A"));
 
+        // Equivalent (and superior) code using orElse
         System.out.println("Parent PID: " +
             ph.parent().map(h -> String.valueOf(h.pid())).orElse("N/A"));
     }

src/effectivejava/chapter8/item56/DocExamples.java

@@ -0,0 +1,97 @@
+package effectivejava.chapter8.item56;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.lang.annotation.ElementType;
+
+// Documentation comment examples (Pages 255-9)
+public class DocExamples<E> {
+    // Method comment (Page 255)
+    /**
+     * Returns the element at the specified position in this list.
+     *
+     * <p>This method is <i>not</i> guaranteed to run in constant
+     * time. In some implementations it may run in time proportional
+     * to the element position.
+     *
+     * @param  index index of element to return; must be
+     *         non-negative and less than the size of this list
+     * @return the element at the specified position in this list
+     * @throws IndexOutOfBoundsException if the index is out of range
+     *         ({@code index < 0 || index >= this.size()})
+     */
+    E get(int index) {
+        return null;
+    }
+
+    // Use of @implSpec to describe self-use patterns & other visible implementation details. (Page 256)
+    /**
+     * Returns true if this collection is empty.
+     *
+     * @implSpec This implementation returns {@code this.size() == 0}.
+     *
+     * @return true if this collection is empty
+     */
+    public boolean isEmpty() {
+        return false;
+    }
+
+    // Use of the @literal tag to include HTML and javadoc metacharacters in javadoc comments. (Page 256)
+    /**
+     * A geometric series converges if {@literal |r| < 1}.
+     */
+    public void fragment() {
+    }
+
+    // Controlling summary description when there is a period in the first "sentence" of doc comment. (Page 257)
+    /**
+     * A suspect, such as Colonel Mustard or {@literal Mrs. Peacock}.
+     */
+    public enum FixedSuspect {
+        MISS_SCARLETT, PROFESSOR_PLUM, MRS_PEACOCK, MR_GREEN, COLONEL_MUSTARD, MRS_WHITE
+    }
+
+
+    // Generating a javadoc index entry in Java 9 and later releases. (Page 258)
+    /**
+     * This method complies with the {@index IEEE 754} standard.
+     */
+    public void fragment2() {
+    }
+
+    // Documenting enum constants (Page 258)
+    /**
+     * An instrument section of a symphony orchestra.
+     */
+    public enum OrchestraSection {
+        /** Woodwinds, such as flute, clarinet, and oboe. */
+        WOODWIND,
+
+        /** Brass instruments, such as french horn and trumpet. */
+        BRASS,
+
+        /** Percussion instruments, such as timpani and cymbals. */
+        PERCUSSION,
+
+        /** Stringed instruments, such as violin and cello. */
+        STRING;
+    }
+
+    // Documenting an annotation type (Page 259)
+    /**
+     * Indicates that the annotated method is a test method that
+     * must throw the designated exception to pass.
+     */
+    @Retention(RetentionPolicy.RUNTIME)
+    @Target(ElementType.METHOD)
+    public @interface ExceptionTest {
+        /**
+         * The exception that the annotated test method must throw
+         * in order to pass. (The test is permitted to throw any
+         * subtype of the type described by this class object.)
+         */
+        Class<? extends Throwable> value();
+    }
+}
+