add wrapper types and change interface a bit

Author: forax

README.md

@@ -7,25 +7,29 @@ A guide to modern Java (Java 17)
 1. [basictypes.md](guide/chapter01-basictypes.md)
 2. [methods.md](guide/chapter02-methods.md)
 3. [jshellvsjava.md](guide/chapter03-jshellvsjava.md)
-4. [controlflow.md](guide/chapter04-controlflow.md)
-5. [numbers.md](guide/chapter06-numbers.md)
+4. [numbers.md](guide/chapter04-numbers.md)
+5. [controlflow.md](guide/chapter05-controlflow.md)
 6. [interface.md](guide/chapter07-interface.md)
 7. [lambda.md](guide/chapter08-lambda.md)
 8. [listandmap.md](guide/chapter09-listandmap.md)
 9. [stringformatting.md](guide/chapter10-stringformatting.md)
-10. [exception.md](guide/chapter11-exception.md)
-11. [encapsulation.md](guide/chapter12-encapsulation.md)
+10. [encapsulation.md](guide/chapter11-encapsulation.md)
+11. [equals_hashCode_toString.md](guide/chapter12-equals_hashCode_toString.md)
 12. [contract.md](guide/chapter13-contract.md)
-13. [nullandoptional.md](guide/chapter14-nullandoptional.md)
-14. [inheritance.md](guide/chapter15-inheritance.md)
-15. [internalclass.md](guide/chapter17-internalclass.md)
-16. [generics.md](guide/chapter20-generics.md)
-17. [wrapper.md](guide/chapter21-wrapper.md)
-18. [variance.md](guide/chapter22-variance.md)
-19. [stream.md](guide/chapter25-stream.md)
-20. [collector.md](guide/chapter26-collector.md)
-21. [datastructure.md](guide/chapter30-datastructure.md)
-22. [sort.md](guide/chapter31-sort.md)
+13. [modifable_vs_mutalble.md](guide/chapter13-modifable_vs_mutalble.md)
+14. [nullandoptional.md](guide/chapter14-nullandoptional.md)
+15. [inheritance.md](guide/chapter15-inheritance.md)
+16. [exception.md](guide/chapter16-exception.md)
+17. [enum.md](guide/chapter17-enum.md)
+18. [internalclass.md](guide/chapter18-internalclass.md)
+19. [implementing_interface.md](guide/chapter19-implementing_interface.md)
+20. [generics.md](guide/chapter20-generics.md)
+21. [wrapper.md](guide/chapter21-wrapper.md)
+22. [variance.md](guide/chapter22-variance.md)
+23. [stream.md](guide/chapter25-stream.md)
+24. [collector.md](guide/chapter26-collector.md)
+25. [datastructure.md](guide/chapter30-datastructure.md)
+26. [sort.md](guide/chapter31-sort.md)
 
 
 ## Using Java Shell (jshell)

chapter06-numbers.jsh renamed to chapter04-numbers.jsh

@@ -8,7 +8,7 @@
 // Once you start to want to mix several records, you need to declare
 // common type between records, such type are known as interface
 
-// ### The problem
+// ## The problem
 // let say we have a Square and Rectangle, and both have a method `area()`
 record Square(int side) {
   public double area() {
@@ -33,13 +33,21 @@ var figures = List.of(new Square(2), new Rectangle(3, 4));
 // and find that they are java.lang.Object, and Object has no method area()
 // so it doens't compile
 
-// the idea is to introduce a type Figure has a common type for Square and Rectangle
+
+// ### Interface and abstract method
+// The idea is to introduce a type Figure has a common type for Square and Rectangle.
+// In Java, we use the keyword `interface` for that.
+
+// The method `area()` in Figure is not a classical method with some code because
+// the code is defined in Square and Rectangle. It's an `abstract` method.
+// The definition of the method is present but the code has to be implemented by the
+// records that implement the interface
 interface Figure {
-  public double area();
+  public abstract double area();
 }
 
 // and declare that a Square and a Rectangle are a kind of Figure
-// using the keyword 'implements'
+// using the keyword `implements`
 record Square(int side) implements Figure {
   public double area() {
     return side * side;
@@ -51,9 +59,9 @@ record Rectangle(int width, int height) implements Figure {
   }
 }
 
-// Now, the list is correctly typed as a list of figure (List<Figure>)
-// so looping over the figures to call area() works
-var figures = List.of(new Square(2), new Rectangle(3, 4));
+// Now, the list is correctly typed as a list of figure (`List<Figure>`)
+// so looping over the figures to call `area()` works
+List<Figure> figures = List.of(new Square(2), new Rectangle(3, 4));
 for(var figure: figures) {
   System.out.println(figure.area());
 }
@@ -63,50 +71,53 @@ for(var figure: figures) {
 // At runtime, when you call a method of the interface, the interpreter calls
 // the correct implementation (this is called polymorphism)
 
-// Technically, we have already used interfaces, List is an interface too
 
+// ## Static method
+// Like a record, an interface can have `static` methods
+interface Figure {
+  public abstract double area();
+  
+  public static Figure createASquare(int side) {
+    return new Square(side);
+  }
+}
+var aSquare = Figure.createASquare(3);
+System.out.println(aSquare);
 
-// ## Implementing an interface
-// In Java, not only record can implement an interface, 
-// you have three other syntax
-// - anonymous class
-// - lambda
-// - method reference
 
-// ### Anonymous class
-var anotherFigure = new Figure() {
-  public double area() {
-    return 4;
+// ## Default method
+// Inside an interface, the instance methods are implicitly abstract,
+// if we want to declare a method with some code in it, we have to use
+// the keyword `default`.
+// By example, we can write a method `isBig` that is true if the area is big enough.
+interface Figure {
+  public abstract double area();
+  
+  public default boolean isBig() {
+    return area() >= 10;
   }
-};
-
-// An anonymous class allow you to only provide the code of the methods of the interface
-// note that the syntax is a little weird because you may call new on a Figure but infact,
-// you ask to create something that implements Figure not a figure by itself.
+}
+System.out.println(new Square(2).isBig());
+System.out.println(new Rectangle(3, 4).isBig());
 
-// you may think that this syntax is useless because you can not have the area computed
-// from the values of some components like with a record, but if you create an anonymous class
-// inside a method you can use the parameters of the method inside the anonymous class
-Figure rectangularTriangle(int width, int height) {
-  return new Figure() {
-    public double area() {
-      return width * height / 2.0;
-    }
-  };
-};
+// Because a default method is declared on the interface, all records that
+// implement that interface will have that method. Default methods are named like this
+// because if the record doesn't define the method itself, the method will be provided
+// by default. 
 
-var figures = List.of(new Square(2), rectangularTriangle(3, 4));
-for(var figure: figures) {
-  System.out.println(figure.area());
-}
 
+// ## Functional interface
+// An interface with only one abstract method is equivalent to a function type.
+// We name this kind of interfaces, _functional_ interfaces.
+// They can be implemented by supplementary constructs.
 
 // ### Lambda
-// In case of the interface is itself an interface with only one abstract method,
-// we calls that interface a functional interface, you have even a shorter syntax
+// The parameter are declared in between the parenthesis and the body of the method
+// is declared after the arrow (like the expression switch).
 Figure anotherFigure = () -> 4;
 
-// and rewrite the method rectangularTriangle() like this
+// and rewrite the method rectangularTriangle()
+// You can notice that a lambda can access to the parameter `width` and `height`
 Figure rectangularTriangle(int width, int height) {
   return () -> width * height / 2.0;
 }

chapter04-controlflow.jsh renamed to chapter05-controlflow.jsh

@@ -2,6 +2,8 @@
 // then cut and paste the following lines to see how it works
 // To exit jshell type /exit
 
+// # Class and encapsulation
+
 // Let's say i want to create a library of books,
 // so we need a record Book and a record Library that stores the books has a list
 record Book(String title, String author) { }
@@ -24,15 +26,26 @@ System.out.println(library);
 // an object has an effect to another object.
 
 
+// ## Encapsulation principle
 // The encapsulation principle: the only way to change the value of an object
 // is to use one of the methods of this object.
 
-// To avoid the issue above, we have to make the list of books of the Library
-// separated from the list of books taken as parameter to initialize the Library
+// In Java, the way to ensure the encapsulation principle is based on
+// separating the API part (what the user code can use) from the implementation part
+// (how the class is implemented).
+
+// This separation is done by using a special syntax named __class__ that allow
+// to precisely control what is part of the API and what is part of the impelemntation.
 
-// We have to use a new syntax, a class that unlike a record allows
-// to separate the external API (the one users see) from the internal API
-// (how things are implemented)
+// ## Class
+// A class defines
+// - a field (books) that is like a record component but not necessarily visible by the user code
+// - a constructor (Library), that guarantee that any objects will be correctly initialized
+// - fields and methods have a visibility (public/private) so it's easy to control
+//   what is visible from the outside and what is not.
+
+
+// ### Unmodifiable class
 class Library {
   private final List<Book> books;
 
@@ -44,63 +57,87 @@ class Library {
     return "Library " + books.toString();
   }
 }
-
-// A class defines
-// - a field (books) that is like a record component but not necessarily visible by the user
-// - a constructor (Library), a special method used to initialize the library
-// - fields and methods have a visibility (public/private) so it's easy to control
-//   what is visible from the outside and what is not.
-// Unlike a record, the method equals/hashCode() and toString() are not provided and has
-// to be hand written.
-
 var library = new Library(books);
 System.out.println(library);
 
-// and changing the list of books has no effect on the library
+// Now changing the list of books has no effect on the library
+// because the field `books` and the argument of the constructor `books` are different references
 books.remove(new Book("DaVinci Code", "Dan Brown"));
 System.out.println(library);
 
 // You can notice that the constructor has no return type, it's because it's always void.
+
 // The field 'books' is declared final which means must be initialized
 // in the constructor (and not changed afterward) so we are sure that in toString(),
 // the field 'books' has been initialized.
 
+// Unlike a record, the method equals/hashCode() and toString() are not provided and has
+// to be hand written. We will see how to implement them later.
 
-// Writing equals()/hashCode()
-// If we want to be able to use Library with data structures like list or map,
-// We must write equals() and hashCode()
-// - equals() has to return false if it's not the right class, and
-//   use the fields to see if their values are equals
-// - hashCode() has to use the same fields to compute a hash value
-class Library {
-  private final List<Book> books;
+
+// ### Modifiable class
+// The code above is an unmodifiable implementation of Library
+// that can be used as element of list or map.
+// We can also write a mutable version with the caveat that using it
+// as element of a list or a map is not recommended
+class ModifiableLibrary {
+  private final ArrayList<Book> books;
 
-  public Library(List<Book> books) {
-    this.books = List.copyOf(books);
+  public ModifiableLibrary() {
+    books = new ArrayList<>();
+  }
+  
+  public void add(Book book) {
+    Objects.requireNonNull(book);
+    books.add(book);
+  }
+  
+  public String toString() {
+    return "ModifiableLibrary " + books.toString();
   }
+}
+var library = new ModifiableLibrary();
+library.add(new Book("DaVinci Code", "Dan Brown"));
+System.out.println(library);
+library.add(new Book("Effective Java", "Joshua Bloch"));
+System.out.println(library);
+
+
+// ### Modifiable class and accessor
+// An error sometime seen is to add a method to get the content of the library
+// and forget that it may expose the private list of books
+class ModifiableLibrary {
+  private final ArrayList<Book> books;
 
-  public boolean equals(Object o) {
-    return o instanceof Library library &&
-      books.equals(library.books);
+  public ModifiableLibrary() {
+    books = new ArrayList<>();
   }
 
-  public int hashCode() {
-    return books.hashCode();
+  public void add(Book book) {
+    Objects.requireNonNull(book);
+    books.add(book);
+  }
+  
+  public List<Book> getBooks() {
+    return books;
   }
 
   public String toString() {
-    return "Library " + books.toString();
+    return "ModifiableLibrary " + books.toString();
   }
 }
 
-var library1 = new Library(books);
-var library2 = new Library(books);
-System.out.println(library1.equals(library2));
+// The following code breaks the encapsulation because you can 
+// modify the library without calling a method of the Library
+// (add is done on the List<Book> not on the Library)
+var library = new ModifiableLibrary();
+var books = library.getBooks();
+books.add(new Book("DaVinci Code", "Dan Brown"));
 
-// The code above is an unmodifiable implementation of Library
-// that can be used as element of list or map.
-// We can also write a mutable version with the caveat that using it
-// as element of a list or a map is not recommended
+// One solution is to return a copy, or better a non modifiable view
+// of the internal list of books
+// The best solution being to not have a method `getBook()` at all,
+// the less code you write the less bug you have.
 class ModifiableLibrary {
   private final ArrayList<Book> books;
 
@@ -112,29 +149,29 @@ class ModifiableLibrary {
     books.add(book);
   }
 
+  public List<Book> getBooks() {
+    return Collections.unmodifiableList(books);
+  }
+  
   public String toString() {
     return "ModifiableLibrary " + books.toString();
   }
 }
 var library = new ModifiableLibrary();
-library.add(new Book("DaVinci Code", "Dan Brown"));
-System.out.println(library);
-library.add(new Book("Effective Java", "Joshua Bloch"));
-System.out.println(library);
+var books = library.getBooks();
+books.add(new Book("DaVinci Code", "Dan Brown"));
 
 
-// Record constructor
-// Records also provides a way to change the constructor used to initialize
-// a record called the 'canonical constructor'.
+// ## Record constructor
+// Records also provides ways to customize the code to respect the
+// encapsulation principle
+// Here, we only need to change the canonical constructor 
 record Library(List<Book> books) {
   public Library(List<Book> books) {
     this.books = List.copyOf(books);
   }
 }
 
-// In this example, it's enough to make the implementation of Library
-// to be compatible with the encapsulation principle
-
 
 // To summarize, a class is a general mechanism to describe how things
 // are implemented and make a separation between what is publicly visible