DEV Community: Ashkan Entezari

Effective Java —Chapters 10 to 12

Ashkan Entezari — Mon, 04 Nov 2019 14:44:35 +0000

Introduction

This the final part of the summary of this book. In part one I summarized chapters 2 to 5 and in part two I summarized chapters 6 to 9. In this final part, we will have the summary of remainder of the book, chapters 10 to 12. If you found issues with any part of the summary or if you have suggestions to make them better or more understandable, please let me know and I will be updating them.

10 Exceptions

Item 69

Use exceptions only for exceptional conditions
we should not use them for ordinary conditional flow like this:

try {
    int i = 0;
    while (true) {
        range[i++].climb();
    }
} catch (ArrayIndexOutOfBoundsException e) {}

this approach of using exceptions is wrong on different levels:
- it is confusing as it's not the intention of the exceptions
- JVM will not optimize these (compared to when we use Arrays.length() for instance)
- we may catch an actual exception here unintentionally without realizing it
a well designed API must not force its clients to use exceptions for ordinary workflow
- e.g. Iterator has hasNext() which you can use before calling next(), so you don't need try/catch here
- in general, when a method is state-dependant, we should have a state-testing method to call before calling our method to make sure we can safely call it.

Item 70

Use checked exceptions for recoverable conditions and runtime exceptions for programming errors
Java provides three kinds of throwables:
1. checked exceptions
2. when we declare a method throws an exception
3. the caller needs to catch it and resolve it or propagate it upwards
4. they are meant to be used in conditions from which the caller can reasonably be expected to recover
5. it is a bad idea to just catch these exceptions and ignore them.
6. provide methods on checked exceptions to aid in recovery. e.g. we have a payment w/ credit card method that throws exception if funds are not sufficient. We can provide an accessor method to query the amount of shortfall. This enables the caller to relay the amount to the shopper
7. runtime exceptions
8. these exceptions are usually result of precondition violation which is client failure to adhere to the contract established by the API specifications
9. they are result of programming errors
10. e.g. the contract for array access specifies the indices to be between 0 and array's length minus 1, using something outside this range will throw ArrayIndexOutOfBoundsException
11. errors
12. there is a strong convention that errors are reserved for use by the JVM
13. such as OutOfMemoryError, ThreadDeath, etc.
14. all the unchecked exceptions you implement should subclass RuntimeException

Item 71

Avoid unnecessary use of checked exceptions
when used sparingly they increase reliability of programs, when overused, they make APIs painful to use
we need to use them when we believe user can recover the situation when getting the exception
- if they just log the stack trace or ignore it (as in like they can do nothing else) it doesn't make sense to make it a checked exception. This just makes it harder to use as you have to use a try/catch or propagate it outward!

Item 72

Favor the use of standard exceptions
Java libraries provide a set of exceptions that covers most of exception throwing needs of most APIs
we should try to use standard and appropriate exception types which makes our code cleaner and easier to read and understand
the most commonly reused exceptions are:
- IllegalArgumentException: non-null parameter value is inappropriate
- like passing a negative number to an argument expecting number of elements
- IllegalStateException: Object state is inappropriate for method invocation
- like Object is not initialized
- NullPointerException: parameter value is null where prohibited
- IndexOutOfBoundException: index parameter value is out of range
- ConcurrentModificationException: concurrent modification of object has been detected where it is prohibited
- UnsupportedOperationException: object does not support method

Item 73

Throw exceptions appropriate to the abstraction
when exceptions propagate outward, we may get one that has no apparent connection to the task that it performs.
to avoid this problem we can do exception translation which is basically catching the exception (when appropriate) and throwing a more relevant exception to the higher level instead
this is an example from AbstractSequentialList:

public E get(int index) {
    ListIterator<E> i = listIterator(index);
    try {
        return i.next();
    } catch (NoSuchElementException e) {
        throw new IndexOutOfBoundsException("Index: " + index);
    }
}

a special form of exception translation is called exception chaining which is when lower level exception might be useful to someone debugging the higher level exception. in this case, we pass the lower level exception to the higher level exception:

try {
    ...
} catch (LowerLevelException cause) {
    throw new HigherLevelException(cause);
}

most standard exceptions have chaining-aware constructors which pass the "cause" to a higher level constructor which can be accessed later.
for exceptions, we can use Throwable's initCause method which later can be accessed using getCause

Notes

while exception translation is superior to mindless propagation of exceptions from lower layers, it should not be overused

Item 74

Document all exceptions thrown by each method
always declare checked exceptions individually and document precisely the conditions under which each one is thrown
use JavaDoc's @throws tag
it is also a good practice to document unchecked exceptions that the method can throw. These unchecked exceptions are usually programmer's error and doing this, they will know what to expect and how to properly use that method or interface.

Item 75

Include failure-capture information in detail messages
to capture a failure, the detail message of an exception should contain all the values for all the parameters and fields that contributed to the exception
- e.g. if we get IndexOutOfBoundException, it would be very helpful to have the index value as well as the lower bound and upper bound
- an exception to this (for security purposes) is passwords, encryption keys and the like which we don't wanna include in the detail message

Item 76

Strive for failure atomicity
it means a failed method invocation should leave the object in the state that it was in prior to the invocation
there are different ways to achieve this goal. For example in stack implementation from before:

public Object pop() {
    if (size == 0) {
        throw new EmptyStackException();
    }
    Object result = elements[--size];
    ...
}

so here we check the size first and throw exception instead of making size -1 and then wait for the exception to be thrown when accessing elements[-1]

another way to accomplish failure atomicity is to change the order of the computations if possible, so the part that may cause exception comes first.
Another approach is to perform operations on a copy of the object and then if everything was successful apply them back to the original
it should be mentioned that failure atomicity is not always achievable (like to threads without proper synchronization modify something) or sometimes making something atomic will hugely complicate the code. In these cases we should mention it in the API documentation that what is the broken state that may happen by a method invocation for example

Item 77

Don't ignore exceptions
an empty catch block defeats the purpose of exceptions. We should always take proper actions to address exceptions
in some rare cases it might be ok to ignore them, in which case we should put a comment in catch block with explanations:

int numColors = 4; // Default
try {
    numColors = getNumColors();
} catch (ExecutionException | TimedoutException ignored) {
    // in this case just use default value
}

11 Concurrency

Item 78

Synchronize access to shared mutable data
it is better not to share mutable data between multiple threads and share only immutable data.
if we have a mutable object, we can share it with only one thread
if we have to share mutable data, we should use Synchronize which guarantees that no method will ever observe the object in an inconsistent state.
- the language specification guarantees that read/write is atomic unless variable is long or double (there is AtomicLong that we can use)
one example of using synchronization:

public class StopThread() {
    private static boolean stopRequested;

    private static synchronized void requestStop() {
        stopRequested = true;
    }

    private static synchronized boolean stopRequested() {
        return stopRequested;
    }

    public static void main(String[] args) {
        Thread backgroundThread = new Thread(() -> {
            int i = 0;
            while ( !stopRequested() ) {
                i++;
            }
        });
        backgroundThread.start();

        TimeUnit.SECONDS.sleep(1);
        requestStop();
    }
}

synchronization can be used for:
- 'communication': if we remove synchronization code above, our thread won't have access to updated value of stopRequested, so we should use it to make sure it does get the updated value as we expect it
- 'mutual exclusion': so we won't have race condition or having one thread reading value while the other is writing a new value to it.
in the above example, since synchronization is only used fo 'communication', we can remove the synchronized methods for read and write and instead declare the variable like this: private static volatile boolean stopRequested; this will make the thread check for the updated value every time it reads it.
synchronization is not guaranteed unless both read/write methods are synchronized.

Item 79

Avoid excessive synchronization
inside a synchronized method or block, never cede control to the client
- like calling a method that is designed to be overridden
- or calling a method provided by the client
- from the perspective of the class with the synchronized region, these methods are called alien
we may get unwanted exceptions or deadlocks
as a rule, we should do as little work as possible inside synchronized regions
over-synchronization can have its own issues

Item 80

Prefer executors, tasks, and streams to threads
java.util.concurrent package contains Executor Framework which is a flexible interface-based task execution facility. Instead of creating a work queue to execute tasks asynchronously and handling that queue manually, it is better to use this framework:

ExecutorService exec = Executors.newSingleThreadExecutor();
// submitting a runnable for execution:
exec.execute(runnable);
// terminating executor gracefully:
exec.shutdown();

you can do many more with this service. You can wait for all the tasks or a particular task to complete, you can retrieve results of tasks as they complete, you can schedule them to run at a particular time or to run periodically, and so on.
in essence, Executor Framework does for execution what Collections Framework did for aggregation.

Item 81

Prefer concurrency utilities to wait and notify
the higher level utilities in java.util.concurrent fall into three categories:
1. Executor Framework
2. concurrent collections
3. synchronizers
concurrent collections are high-performance concurrent implementation of standard collection interfaces such as List, Queue and Map (like ConcurrentHashMap)
Synchronizers are objects that enable threads to wait for one another, allowing them to coordinate their activities. the most common ones are CountDownLatch and Semaphore and the most powerful one is Phaser.
quick explanation of CountDownLatch: it has a constructor that gets an int which is number of times the countDown method must be invoked on it before all waiting threads can proceed:

CountDownLatch latch = new CountDownLatch(2);
latch.await();
System.out.println("done!");

so here if in another thread for example we invoke latch.countDown two times, the above code will proceed and print "done!"

in summary, this item (and the previous one) introduced us to three main utilities of java.util.concurrent. There are old alternatives for each of them that require lots of code and maintenance (for #2 above, there are Synchronized Collections that are slower. For #3 there is wait and notify/notifyAll which is messy and needs more handling). These last two items introduce these new alternatives and encourage us to use them instead. There are lots of details for each of them and if we need them, we should study them in more depth.

Item 82

Document thread safety
How a class behaves when its methods are called concurrently is an important part of its API contract
to enable safe concurrent use, a class must clearly document its level of thread safety:
- Immutable: Instances are constant, no external synchronization is necessary
- Unconditionally thread-safe: instances of this class are mutable but the class has sufficient internal synchronization
- Conditionally thread-safe: like previous one but some of its methods need external synchronization
- Not thread-safe: to use them safely, client must surround each method invocation with external synchronization
- Thread hostile: unsafe for concurrent use even if everything is surrounded by synchronization. This usually results from modifying static data without internal synchronization, external synchronization won't help here!
lock fields should always be declared final:

    private final Object lock = new Object();

    public void foo() {
        synchronized(lock) {
            ...
        }
    }

Item 83

Use lazy initialization judiciously
Lazy initialization: the act of delaying the initialization of a field until its value is needed
as is the case for most optimizations, don't do it unless you need to
if a field is only accessed on a fraction of the instances and it's costly to initialize it, it's better to lazily initialize it
normal lazy initialization which needs to be synchronized:

private FieldType field;
private synchronized FieldType getField() {
    if (field == null) {
        field = computeFieldValue();
    }
    return field;
}

lazy initialization holder class idiom, to use on a static field:

private static class FieldHolder {
    static final FieldType field = computeFieldValue(); // this will be ignored until accessor is called
}
private static FieldType getField() {
    return FieldHolder.field;
}

to use lazy initialization for performance on an instance field, use the double-check idiom:

    private volatile FieldType field;

    private FieldType getField() {
        FieldType result = field;
        if (result == null) { // first check, no locking
            synchronized(this) {
                if (field == null) { // second check with locking
                    field = result = computeFieldValue();
                }
            }
        }
    }

Item 84

Don't depend on the thread scheduler
when there are many runnable threads at the same time, thread scheduler determines which one gets to run for how long and this can be different in different systems. Any program that relies on thread scheduler for correctness and performance is likely to be nonportable.
threads should not run if they are not doing useful work (like waiting for something)
resist the temptation to use Thread.yield or thread priorities which are among least portable features of Java

12 Serialization

Item 85

Prefer alternatives to Java serialization
There are many security risks in serialization. the best way to avoid serialization exploits is to never deserialize anything
there is no reason to use Java serialization in any new code you write
two good alternatives is to use JSON or protobuf as a cross platform structured data representation

Item 86

Implement Serializable with a great caution
you can simply make any class to implement Serializable but there are a few things to be aware of
- it decreases class's flexibility to change once it has been released. basically the byte stream of its internals are now part of the exported API
- it increases the likelihood of bugs and security holes
- it increases the testing burden. It should be possible to serialize the old version of a class and deserialize it using its new version and vice versa. These should be all tested
- Classes designed for inheritance should rarely implement Serializable and interfaces should rarely extend it
- inner classes should not implement Serializable
when you make a serializable class, if you don't declare a static final long field called serialVersionUID, the system automatically generates it at runtime

Item 87

Consider using a customer serialized form
Do not accept default serialized form without considering whether it is appropriate or not.
default serialization is an efficient encoding of the physical representation of the object graph
if this physical representation is identical to its logical content, then it is appropriate to use the default serialization. The following class is an example:

public class Name implements Serialization {
    /**
    * Last name, must be non-Null
    * @serial
    */
    private final String lastName;

    /**
    * First name, must be non-Null
    * @serial
    */
    private final String firstName;

    /**
    * Middle name, or null if there is none
    * @serial
    */
    private final String middleName;
}

even if you decide that the default serialized form is appropriate, you often must provide a readObject method
On the other end of the spectrum, here is a terrible candidate for default serialization:

public final class StringList implements Serializable {
    private int size = p;
    private Entry head = null;

    private static class Entry implements Serializable {
        String data;
        Entry next;
        Entry previous;
    }
    //...
}

logically speaking, this class represents a sequence of strings but physically it is a sequence of doubly linked list. A reasonable serialization form of this class is simply a number, representing number of strings in the list, followed by the strings themselves:

public final class StringList implements Serializable {
    private transient int size = 0;
    private transient Entry head = null;

    private static class Entry {
        String data;
        Entry next;
        Entry previous;
    }

    // appends the specified string to the list
    public final void add(String s) {...}

    /**
    * Serialize this {@code StringList} instance
    *
    * @serialData The size of the list (the number of strings it contains) is
    * emitted ({@code int}), followed by all of its elements (each a {@code String}
    * ), in the proper sequence
    */
    private void writeObject(ObjectOutputStream s) throws IOException {
        s.defaultWriteObject();
        s.writeInt(size);

        // write out all elements in the proper order
        for (Entry e = head; e != null; e = e.next) {
            s.writeObject(e.data);
        }
    }

    private void readObject(ObjectInputStream s) throws IOException {
        s.defaultReadObject();
        int numElements = s.readInt();

        // read in all elements and insert them in list
        for (int i = 0; i < numElements; i++) {
            add((String) s.readObject());
        }
    }

    // remainder omitted
}

Item 88

Write readObject methods defensively
default serialization and deserialization of classes can be overridden using readObject and writeObject methods.
these can be used for different scenarios, for example initializing transient (non-serializable) fields once we deserialized the object
another use case which is the topic of this item is protecting immutable classes when we deserialize them
as a reminder, for classes that have modifiable objects, we make them immutable by making them private final and also defensively copying them everywhere:

public final class Period {
    private final Date start;
    private final Date end;

    public Period(Date start, Date end) {
        this.start = new Date(start.getTime());
        this.end = new Date(end.getTime());
        if (this.start.compareTo(this.end) > 0) {
            throw new IllegalArgumentException();
        }
    }

    // getters and no setters
}

other than defensive copying, we check for validations as well to make sure state is valid.

This item explains that readObject is effectively another public constructor which demands all of the same care as any other constructor
- there are a few examples in the book that modifies the serialized byte stream to break things that are normally not possible on the above Period class. (examples are for when we make Period to implement Serializable and we don't provide a proper readObject)
- in short, the proper readObject should defensively copy the fields and check for the validations
- here is a proper implementation of it:

  private void readObject(ObjectInputStream is) throws IOException, ClassNotFoundException {
      is.defaultReadObject();

      start = new Date(start.getTime());
      end = new Date(end.getTime());

      if (start.compareTo(end) > 0) {
          throw new InvalidObjectException();
      }
  }

note that here we have to make the fields non-final to be able to make a defensive copy right after deserialization.

same as immutable classes, these readObject methods should not invoke overridable methods

Item 89

For instance control, prefer enum types to readResolve
another risk with using serialization is singleton classes. They look like this:

public class Elvis {
    public static final Elvis INSTANCE = new Elvis();
    private Elvis() {...}
}

if we make it to implement serializable, it no longer will be a singleton.

As a fix we can use readResolve method. This method takes object after deserialization and the object returned by this method is the final deserialized object (so we can replace the serialized object or modify it however we want before it gets to the client). The fix using readResolve will look something like this:

private Object readResolve() {
    // return the only instance of Elvis and garbage collector will take care of
    // the deserialized Elvis impersonator which will be ignored here:
    return INSTANCE;
}

if we depend on readResolve for instance control, all instance fields with object reference types must be declared transient, if not there can be a potential for an attack.
We can prevent this attack with a more preferred approach which is using enum:

public enum Elvis {
    INSTANCE;

    private String[] favoriteSongs = {"a", "b"};

    public void printFavourites() {
        System.out.println(Arrays.toString(favoriteSongs));
    }
}

Item 90

Consider serialization proxies instead of serialized instances
consider this pattern whenever you find yourself having to write readObject or writeObject on a class that is not extendable by its clients
as mentioned in previous items, using serialization increases the likelihood of bugs and security problems. Serialization Proxy Pattern greatly reduces these risks
first, design a private static nested class that concisely represents the logical state of an instance of the enclosing class (this nested class is serialization proxy of the enclosing class)
this class should have one constructor whose parameter type is enclosing class.
both enclosing class and serialization proxy must declare Serialization
this is a serialization proxy for the Period class written in item 50:

private static class SerializationProxy implements Serializable {
    private final Date start;
    private final Date end;

    SerializationProxy(Period period) {
        this.start = period.start;
        this.end = period.end;
    }

    private static final long serialVersionUID = 23413487423847742L; // any number will do
}

now we have to add the writeReplace method to the enclosing class:

private Object writeReplace() {
    return new SerializationProxy(this);
}

with this pattern, we should not generate a serialized version of the enclosing class, to safe gaurd it against attackers, add this to the enclosing class:

private void readObject(ObjectInputStream stream) throws InvalidObjectException {
    throw new InvalidObjectException("Proxy required!");
}

finally, provide readResolve method on the serialization proxy class that returns a logically equivalent instance of the enclosing class:

private Object readResolve() {
    return new Period(start, end);
}

the key here is that at the end, this pattern uses the public constructor in the readResolve method which makes it safe (normally serialization uses extralinguistic mechanism in place of ordinary constructors)

Effective Java —Chapters 6 to 9

Ashkan Entezari — Mon, 04 Nov 2019 14:24:47 +0000

Introduction

This is part 2 of my summary of "Effective Java". For the first part of this summary (chapters 2 to 5) you can refer to this post.

A reminder that *Effective Java is a reference-like book and I tried to have this summary as a quick point of reference. I summarized each item and included my take on it. If you found issues or have suggestions to make them easier and more understandable, please let me know.

6 Enums and Annotations

Item 34

Use enums instead of int constants
When we have an enumerated type whose values are a fixed set of constants we should use enum. Bad alternatives are constant strings or ints like this:

  // bad
  public static final int APPLE_FUJI = 0;
  public static final int APPLE_PIPPIN = 1;

  public static final int ORANGE_NAVEL = 0;
  public static final int ORANGE_BLOOD = 1;

instead we can use something like this:

  public enum Apple { FUJI, PIPPIN, GRANNY_SMITH }
  public enum Orange { NAVEL, BLOOD, TEMPLE }

this item also talks about various disadvantages of using constant ints or strings. For example in above example int values are used for both orange and apple types, later we can do math operations with these ints or can potentially compare these ints which is mathematically allowed but we are basically comparing apples to oranges! They are also verbose (long prefixes before each constant —APPLE_)
enums are designed for this and other than simple example above (which is what we need most of the times) we can make them more advanced with extra functionalities:

public enum Planet {
    MERCURY(3.302e+23, 2.439e5),
    VENUS(4.859e+24, 6.052e6),
    EARTH(5.975e+24, 6.378e6),
    ...;

    private final double mass;
    private final double radius;
    private final double surfaceGravity;

    // constructor
    Planet(double mass, double radius) {
        this.mass = mass;
        this.radius = radius;
        surfaceGravity = 6.6e-11 * mass / (radius*radius);
    }

    public double mass() {return mass;}
    public double radius() {return radius;}
    public double surfaceGravity() {return surfaceGravity;}

    public double surfaceWeight(double mass) {
        return mass * surfaceGravity;
    }
}

in the above code sample we are associating data with enum constants (mass, radius,..) and to do that we should add a constructor. we've also added a shared functionality to easily calculate the surface weight for each constant. Look at these sample usages of the above enum:

double earthWeight = 158; // or read from input
double mass = earthWeight / Planet.EARTH.surfaceGravity();

for (Planet planet : Planet.values()) {
    System.out.println("Weight on " + planet + " is " + planet.surfaceWeight(mass));
}

note that all enums have static values() that returns an array of their values. they also have a default toString() which returns the declared name of each enum value. We can override this if we want.
If enums are only needed in a class we should define them as a member class of that class, but if they are helpful in other places we should declare them as a top-level class.
in Planet enum example we had a shared functionality (surfaceWeight()) that was similar for all of its constants. If we want a method that behaves different for each constant, best approach is to define an abstract method and implement it like this:

public enum Operation {
    PLUS("+") {public double apply(double x, double y){return x + y;} },
    MINUS("-") {public double apply(double x, double y){return x - y;} },
    TIMES("*") {public double apply(double x, double y){return x * y;} },
    DIVIDE("/") {public double apply(double x, double y){return x / y;} };

    public abstract double apply(double x, double y);

    public final String symbol;

    Operation(String symbol) {
        this.symbol = symbol;
    }
}

Item 35

Use instance fields instead of ordinals
enums have an ordinal method that returns an int for each member (in order they are defined, 0-index)
we might get tempted in some situations to get the ordinal() value and use it. Don't do this!!
if you need to associate a value with each member, even an int, use instance fields as explained in item 34.

Item 36

Use EnumSet instead of bit fields
when the enum elements are meant to be used in a set, traditionally many ppl use int enum pattern and instead of enum, for each element they define a different power of 2 and to pass them around they use bit field:

public class Text {
    public static final int STYLE_BOLD = 1 << 0; // 1
    public static final int STYLE_ITALIC = 1 << 0; // 2
    public static final int STYLE_UNDERLINE = 1 << 0; // 4
    // ...

    public void applyStyles(int styles) {...}
}

and to use them and passing them around, instead of set we can do this: text.applyStyles(STYLE_BOLD | STYLE_ITALIC); (we pass something like 100101 in which every 1 says we should apply that style)

Java.util package has EnumSet which should be used instead of these bit fields. it provides type safety and interoperability of sets and internally uses bit vector which makes its performance comparable with bit fields:

public class Text {
    public enum Style { BOLD, ITALIC, UNDERLINE, STRIKETHROUGH }

    public void applyStyles(Set<Style> styles) { ... }
}

and then we can use it like this:

text.applyStyles(EnumSet.of(Style.BOLD, Style.ITALIC));

note that applyStyles() takes Set instead of EnumSet, this is a best practice to accept the interface type rather than the implementation type (item 64), but it works fine if we accept EnumSet.

Item 37

Use EnumMap instead of ordinal indexing
it is rarely appropriate to use oridnals to index into arrays, use EnumMap instead.
- if the relationship being represented is multidimensional, nested EnumMaps should be used: EnumMap<..., EnumMap<...>>
One example for using EnumMaps: consider this class representing a Plant:

public class Plant {
    enum LifeCycle { ANNUAL, PERENNIAL, BIENNIAL }

    final String name;
    final LifeCycle lifeCycle;

    // implement constructor and override toString to return name
}

so here basically each plant has a name and a life cycle. Now we want to have an array of plants representing a garden and we want to organize these plants by there life cycle. We can have an array of set (Set<Plant>[]) and use LifeCycle ordinal value to put each plant in one of the possible 3 sets or we can use EnumMap:

Map<Plant.LifeCycle, Set<Plant>> plantsByLifecycle = Arrays.stream(garden)
                    .collect(gropuingBy(p -> p.lifeCycle,
                        () -> new EnumMap<>(LifeCycle.class),
                        toSet() ));

Item 38

Emulate extensible enums with interfaces
enum types are better that alternative enum patterns (such as int enum patterns). There is however one limitation which is one enum type can not extend another (generally not a good idea!)
in some cases such as operation codes, it might be still valid to have extensible enums. To emulate the extension, we can use interfaces like this:

  public interface Operation {
      double apply(double x, double y);
  }

  public enum BasicOperation implements Operation {
      PLUS("+") {
          public double apply(double x, double y) { return x + y; }
      },
      MINUS("-") {
          public double apply(double x, double y) { return x - y; }
      };

      private final String symbol;

      BasicOperation(String symbol) {
          this.symbol = symbol;
      }

      @Override
      public String toString() { return symbol; }
  }

  public enum ExtendedOperation implements Operation {
      EXP("^") {
          public double apply(double x, double y) { return Math.pow(x, y); }
      },
      REMAINDER("%") {
          public double apply(double x, double y) { return x % y; }
      };

      private final String symbol;

      BasicOperation(String symbol) {
          this.symbol = symbol;
      }

      @Override
      public String toString() { return symbol; }
  }

this pattern lets clients to write their own enums and we can have methods using these enums that rely on their standard methods, for example we can have a method that accepts enums extending Operation and we call apply() method on its enum constants, knowing they all implement it
The only issue here is that there are some duplicated code for toString(). we can potentially use static helper methods to reduce code duplication in these situations

Item 39

Prefer annotations to naming patterns
Annotations in java are used to provide supplement information about a program. They help us associate metadata (information) with the program elements.
- there are standard ones we can use (like @SupressWarnings, @Override, @Deprecated)
- we can also define our own annotations

One example of defining our test annotation for a test framework:

import java.lang.annotation.*;

@Retention(RententionPolicy.RUNTIME) // it will be retained at runtime
@Target(ElementType.METHOD) // it can be used only on methods (not classes, etc.)
public @interface Test {
}

now we can write tests like this:

public class Sample {
    @Test
    public static void testMethod() {}
}

now we can have a framework like this to find the annotated methods and run the tests:

public class TestRunner {
    public static void main(String[] args) throws Exception {
        int tests = 0;
        int passed = 0;
        Class<?> testClass = Class.forName(args[0]);
        for (Method m : testClass.getDeclaredMethods()) {
            if (m.isAnnotationPresent(Test.class)) {
                tests++;
                try {
                    m.invoke(null);
                    passed++;
                } catch() {
                    ... // see full implementation on page 182, 3rd edition
                }
            }
        }
    }
}

we can also define our test annotation to have some associated values (e.g. for exception):

@Retention(RententionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Test {
    Class<? extends Throwable> value();
}

we can use it on a method like this:

@Test(ArithmeticException.class)
public static void badMethod() {
    int i = 3 / 0;
}

and when calling it in our test runner, we can check its value like this:

method.getAnnotation(Test.class).value(); // here it should return ArithmeticException

our custom annotations can contain more information:

@Documented
@Retention(RententionPolicy.RUNTIME)
public @interface User {
    String name() default "Ashkan";
    Long id();
}

and then we can use it like this:

@User(name="Ashkan", id=123L)
public AdminUser adminUser = new AdminUser();

Note

this item recommends using annotations
there used to be some naming conventions (like JUnit 3 was looking for methods defined in a certain way -start with test) but now they use annotations which is much better.

Item 40

Consistently use the Override annotation
the @Override annotation may be used on method declarations that override declarations from interfaces as well as classes
- with the advent of default methods, it is good practice to use Override on implementations of interface methods.
in an abstract class or an interface, it is worth annotating all methods that override superclass or interface methods, it provides extra checks and if by mistake you add a new method (e.g. by using a different method signature), it will warn you that what you are overriding does not exist in the parent

Item 41

Use marker interfaces to define types
a marker interface is an interface that contains no method declarations but merely designates/marks a class a class implementing it as having some property
if you find yourself writing a marker annotation type whose target is ElementType.TYPE (means any class or interface), make sure that you can't use a marker interface instead!
- if you wanna add methods that accept only objects that have this marking, you should use interfaces
this is basically inverse of Item 22 (don't use an interface if you are not defining a type) and it says use an interface if you want to define a type

7 Lambdas and Streams

Item 42

Prefer lambdas to anonymous classes
historically interfaces with single abstract methods were used as functional types. Their instances are known as function objects which represent functions or actions.

Since JDK 1.1 the primary means of creating these function objects was the anonymous class (refer to Item 24). Since Java 8 it is made possible to create these functional interfaces in a much more concise way using lambda expressions:

// using anonymous classes as a function object (obsolete!)
Collections.sort(words, new Comparator<String>() {
    public int compare(String s1, String s2) {
        return Integer.compare(s1.length(), s2.length());
    }
});

// now using lambda expression as function object (instead of anonymous class)
Collections.sort(words, (s1, s2) -> Integer.compare(s1.length(), s2.length()));

// even better using comparator construction method instead of lambda:
Collections.sort(words, comparingInt(String::length));

// even more succinct using sort method added to List interface in Java 8:
words.sort(comparingInt(String::length));

remember from Item 34 in enum type Operation we used constant-specific class bodies and overrode apply() for each enum constant (since behavior was different for each constant). now instead of function objects we used in those examples of Item 34 to override apply(), we can simply do this:

public enum Operation {
    PLUS ("+", (x, y) -> x + y),
    MINUS ("+", (x, y) -> x + y); // omitted other operations for brevity

    private final static symbol;
    private final static DoubleBinaryOperation op;

    Operation(String symbol, DoubleBinaryOperation op) {
        this.symbol = symbol;
        this.op = op;
    }

    public double apply(double x, double y) {
        return op.applyAsDouble(x, y);
    }
}

Notes

Lambdas lack names and documentation, one to three lines are reasonable for a lambda expression, don't put more than that in a lambda since they are not very self-explanatory and may result in confusion and harm the readability.
you should rarely (if ever) serialize a lambda.

Item 43

Prefer method references to lambdas
the primary advantage of lambdas over anonymous classes is that they are more succinct

Java provides a way to generate function objects even more succinct: method references

// lambda expression
map.merge(key, 1, (count, incr) -> count + incr);

// method reference:
map.merge(key, 1, Integer::sum);

in the above example, lambda expression is a bit verbose and all it is saying is that the function returns the sum of its two arguments. we accomplish that by just using Integer::sum
in some situations lambda expression can be shorter that method reference (usually when the method is in the same class as the lambda). in these situations we better use the lambda version:

service.execute(GoshThisClassNameIsHumongous::action);
// vs.
service.execute(() -> action());

there are other cases like Function.identity() which is again better to use the lambda equivalent x -> x as it is shorter and more clear.
so whenever it is shorter and more clear, we should use method references, o.w. we should use lambdas.

Item 44

Favor the use of standard functional interfaces
now that Java has lambdas, best practices of writing APIs has changed considerably
now instead of having a subclass overriding a primitive method in superclass, we can provide a static factory/constructor that accepts a function object
when you want to accept functional interfaces you don't have to create the interface every time. First make sure it doesn't exist in java.util.function (unless you have a good reason not to use them)
there are 43 interfaces in this package but the main 6 are:

Interface               Function signature          Example
--                      
UnaryOperator<T>        T apply(T t)                String::toLowerCase
BinaryOperator<T>       T apply(T t1, T t2)         BigInteger::add
Predicate<T>            boolean test(T t)           Collection::isEmpty
Function<T, R>          R apply(T t)                Arrays::asList
Supplier<T>             T get()                     Instant::now
Consumer<T>             void accept(T t)            System.out::println

make sure you use these interfaces unless there are good reasons like
- it will be commonly used and can benefit from a more descriptive name
- it has a strong contract associated with it
- it would benefit from custom default methods
one example is Comparator (where we don't use an existing interface)
when defining functional interfaces, use @FunctionalInterface annotation:

// for demonstration only, use the standard one under java.util.function:
@FunctionalInterface
interface EldestEntryRemovalFunction<K, V> {
    boolean remove(Map<K, V> map, Map.Entry<K, V> eldest);
}

Item 45

Use streams judiciously
Streams API was added in Java 8 and contains two key abstractions:
1. the stream, which represents finite/infinite sequence of data elements
2. the stream pipeline, which represents a multistage computation on these elements
streams are sufficiently versatile that practically any computation can be performed using streams.
- but this doesn't mean we should!
- when used appropriately, they make programs shorter and cleaner
- otherwise they make programs difficult to read and maintain
as an example look at one implementation of program that reads words and prints them based on anagram groups (words with same letters, different combinations):

public class Anagrams {
    public static void main(String[] args) throws IOException {
        Path dictionary = Paths.get(args[0]);
        int minGroupSize = Integer.parseInt(args[1]);

        try (Stream<String> words = Files.lines(dictionary)) {
            words.collect(groupingBy(word -> alphabetize(word))).values()
            .stream().filter(group -> group.size() >= minGroupSize)
            .forEach(group -> System.out.println(group.size() + ": " + group));
        }
    }

    private static String alphabetize(String str) {
        char[] a = str.toCharArray();
        Arrays.sort(a);
        return new String(a);
    }
}

things to consider in the above code:
- we could make everything iterative or we could use streams everywhere. But this is the best and most concise implementation that combines streams and imperative paradigms:
- we could implement alphabetize() using streams, but would've been less readable and less performant (streams are not efficient on chars as they don't support them)
- we also extracted alphabetize() as a method and used it in our stream. Alternatively it could have been implemented using streams and used in the same stream, but it would have made the entire thing more complex, less readable and less efficient
- we tried to use meaningful names in streams which clearly express the elements we are iterating on (e.g. word and group)
there are certain things we can't do from function objects (in streams) such as defining local variables and reading/modifying them in scope. Also we can't return from the enclosing method or break/continue or throw a checked exception:
- in these situations we should avoid streams.
also there are situations in which streams usually makes more sense:
- uniformly transform sequences of elements
- filter sequences of elements
- search sequence of elements for an element satisfying some criterion
- accumulate sequences of elements into a collection (perhaps grouping them by some common attributes)
- combine sequences of elements using a single operation
there are also some situations which it is not clear that which way is better or more efficient or more readable! in these situations we can go either way!

Notes

Overusing streams makes programs hard to read and maintain
in the absence of explicit types, careful naming of lambda parameters is essential for readability of stream pipelines.
using helper methods is even more important for readability in stream pipelines than in iterative code!

Item 46

Prefer side-effect-free functions in streams
Streams aren't just an api, they are a paradigm based on functional programming
they should have a sequence of transformations where the result of each stage is as close as possible to a pure function:
- its result depends only on its input, it doesn't depend on any mutable state, nor does it update any state
compare the following two examples, the first one doesn't follow the paradigm but the second one is modified to follow the paradigm:

// uses streams but not the paradigm:
Map<String, Long> freq = new HashMap<>();
try (Stream<String> words = new Scanner(file).tokens()) {
    words.forEach(word -> {
        freq.merge(word.toLowerCase(), 1L, Long::sum);
    });
}
// proper use of streams:
Map<String, Long> freq;
try (Stream<String> words = new Scanner(file).tokens()) {
    freq = words.collect(groupingBy(String::toLowerCase, counting()));
}

the problem with the first example above is that we use forEach to mutate a an external state (frequency table). But second example is modified so that it accepts a table and initializes the given table

the forEach operation should be used only to report the result of a stream computation, not to perform the computation
In order to use streams properly, you have to know about collectors. The most important collector factories are toList, toSet, toMap, groupingBy and joining.

Item 47

Prefer collection to stream as a return type
when writing a public API that returns a sequence of elements, we should provide for both users who want to use it in a stream pipeline as well as those who want to iterate on them.
Best option here is to return a Collection that provides both
the only thing to notice here is that if a return type is small enough to be kept in memory, we can use standard collection implementations such as ArrayList or HashSet. If it is large, we should consider returning a custom collection
- one example is returning power set (all the sub-sets) of a given set: its space requirement is 2ⁿ space. Instead we can create a custom one based on binary representation of it (page 218 of the book for the implementation)

Item 48

Use caution when making streams parallel
Java has always tried to facilitate concurrent programming. First version of Java was released with thread support, Java 5 introduced java.util.concurrent library with concurrent collections. Java 8 introduced streams which can be parallelized with a single call to the parallel() method
although it is very easy to call the parallel method we should be very careful as it won't be very helpful in most of the cases and in some cases it can result in failure or performance disaster
in general whenever we want to use it we have to have good reasons and we have to prove that the code remains correct. Then we have to measure the performance before and after to make sure it actually improved
performance gains from parallelism are best on streams over ArrayList, HashMap, ConcurrentHashMap, arrays, int ranges and long ranges.

8 Methods

Item 49

Check parameters for validity
most methods and constructors have some restrictions on their parameters. We should properly document these and also check for their validity as soon as we can.
for public or protected methods use the Javadoc @throws tag to document the exception
the Objects.requireNonNull() is convenient and easy to use (for null checks)

Item 50

Make defensive copies when needed
you must program defensively with the assumption that clients of your class will do their best to destroy it!
as an example of how things can go wrong and how we can prevent them, consider the following class:

public final class Period {
    private final Date start;
    private final Date end;

    // 'start' must be before 'end'
    public Period(Date start, Date end) {
        if (start.compareTo(end) > 0) {
            throw new IllegalArgumentException();
        }
        this.start = start;
        this.end = end;
    }

    public Date start() {
        return start;
    }

    public date end() {
        return end;
    }
}

first of all never use Date as it is mutable and instead use java.time.Instant. The following code can break the validity of our Period instance:

Date start = new Date();
Date end = new Date();
Period period = new Period(start, end);
end.setYear(78); // modifies internals of period!

to fix this, we should make defensive copies in constructor:

public Period(Date start, Date end) {
    this.start = new Date(start.getTime());
    this.end = new Date(end.getTime());

    if (this.start.compareTo(this.end) > 0) {
        throw new IllegalArgumentException();
    }
}

in the above code since we make a copy, it is impossible for the client to change the parameters. we also moved the validity check to after defining the defensive copies, this is to prevent scenarios like this: let's say another thread for example changes the value of parameters after we check their validity so by the time we assign them, they become invalid. but after we make our defensive copies, this can't happen and we can be sure that our Period instance is valid (and will remain valid)

there is one more thing we need to fix in this class to make it completely error prone. The getters we have defined will return the Date instances of the class and again their values can be altered out of the class (the variables are final but that's just the object reference, i.e. its value can change). We apply the same fix:

public Date start() {
    return new Date(start.getTime());
}
// we do the same for end()

same rules apply when you use a mutable object in your class and you know your class can't tolerate mutability in that reference (like you use the referenced object in a map as a key or in a set).

Item 51

Design method signatures carefully
choose proper method names
- if there are naming conventions, obey them
- choose the best name that conveys the purpose of that method clearly
- ideally avoid very long method names
avoid long parameters list (maximum 4 parameters). There are different ways of making parameter lists shorter:
- breaking the method into multiple methods, each with fewer parameters list
- using helper classes/DTOs to pass around different parameters
- using Builder patter (item 2) from object construction to method invocation
for parameter types, favor interfaces over classes
- using classes will put unnecessary restrictions
- e.g. as an input instead of accepting HashMap we can accept Map (someone may want to pass a TreeMap or a ConcurrentHashMap)
prefer two element enum types to boolean parameters
- public enum TemperatureScale { FAHRENHEIT, CELSIUS }
- Thermometer.newInstance(TemperatureScale.CELSIUS) versus Thermometer.newInstance(true)
- we can also later expand the types under our enum type

Item 52

Use overloading judiciously
overloading is when two (or more) methods have the same name and different signatures. If not used carefully, it can get really confusing and generate unexpected results.
Choice of overloading (which overloaded method to be used) is determined at compile time and can cause issues:
```
public String someMethod(Set<?> daSet) {
    return  "Set!";
}

public String someMethod(Collection<?> daCollection) {
    return "Collection";
}
```
in an example like this, user may call someMethod() with a set and expecting it to call the first method, while it may call the second one!
it can get really confusing when there is same number of parameters. One alternative in these situations which makes it very clear and error prone is to use different names:
- like readInt(), readBoolean(), readLong() (instead of three overloaded read()s)

Item 53

Use varargs judiciously
vararg methods accept zero or more arguments of a specified type
- they are life saver when we need variable number of arguments

  static int sum(int... args) {
      int sum = 0;
      for (int arg : args)
          sum += arg;
      return sum;
  }

couple of small notes about varargs and their usage:
1. if your method requires them to have at least one argument, we can check the argument size first thing and throw exception if it was zero:

  if (args.legth == 0) {
      throw new IllegalArgumentException("too few arguments");
  }

but its messy and also more important, it fails at runtime (while it could've been caught at compile time). Best approach here is:

  static int min(int firstArg, int... remainingArgs) {
      ...
  }

we need to be careful in performance-critical situations as each each use of varargs causes an array allocation and initialization. In this situation if we know that 90% of the cases are 2 arguments or less and we want to optimize the program, we can do this:

  public void foo() { }
  public void foo(int a1) { }
  public void foo(int a1, int a2) { }
  public void foo(int a1, int a2, int... rest) { }

Item 54

Return empty collections or arrays, not nulls
There is no reason to return null when the array or collection that we were supposed to return has no members. It makes code messy, on the client side we need to add extra unnecessary code to handle null case first and then if it was not null, process the returned values. If we forget, we may get NPE. It also adds extra unnecessary code on our side as well to see if there are no members return null, if not return the collection (while we should've just returned that collection, even if it is empty!)
in very rare cases we can argue that returning null is more memory efficient than allocating an empty array or collection. First it is inadvisable to worry about performance at this level and usually unnecessary. In the unlikely event that you have evidence suggesting that allocating empty collections is harming the performance, you can avoid it by returning Collections.emptyList(), Collections.emptySet(), Collections.emptyMap(), etc.
- in case of arrays, we can have an empty array and returning the same zero-length array repeatedly (zero length arrays are immutable):
```
  private static final Cheese[] EMPTY_CHEESE_ARRAY = new Cheese[0];

  public Cheese[] getCheeses() {
      return cheesesInStock.toArray(EMPTY_CHEESE_ARRAY); // if we want an empty array here
  }
```

Item 55

Return optionals judiciously
Optionals represent values that can be either present or absent. Prior to Java 8, if a method was not able to return a value it could either throw an exception or return null. Optionals were added in Java 8 (java.util.optional), they are immutable containers that can contain either a non-null object reference or nothing at all (empty optional)

public static <E extends Comparable<E>> Optional<E> max(Collection<E> collection) {
    if (collection.isEmpty()) {
        return Optional.empty();
    }

    E result = //find the maximum element
    return Optional.of(result);
}

passing null to Optional.of(value) will throw an exception.
many terminal operations on streams return optionals. Using stream in the above example will generate the optional for us:

public static <E extends Comparable<E>> Optional<E> max(Collection<E> collection) {
    return collection.stream.max(Comparator.naturalOrder());
}

On the client side, they can decide what to do with an optional returned value. such as:

// use a default value if optional is empty:
String myString = max(words).orElse("No words...");

// or throw an exception if it is empty:
Toy myToy = max(toys).orElseThrow(TemperTantrumException::new);

// if we know it's not empty we can just get the value:
Element lastNobleGas = max(Elements.NOBLE_GAS).get();

if we have a stream of optionals and we want to get those elements of this stream that are not empty:

streamOfOptionals.filter(Optional::isPresent).map(Optional::get);

Java 9 added stream() method to Optional which returns only those elements that have value, so this last code snippet can be even shorter:

streamOfOptionals.flatMap(Optional::stream);

Notes

never return null from an optional-returning method
never return an optional of a boxed primitive type
- this is expensive compared to returning primitive type because the optional has two levels of boxing instead of zero
- you can use OptionalInt, OptionalLong and OptionalDouble if needed

Item 56

Write doc comments for all exposed API elements
to document the API properly, you must precede every exported class, interface, constructor, method and field declarations with a doc comment
The complete guide for writing java docs is here. This doc is a bit old (Java 4), since then, these tags have been added: {@index}, {@implSpec}, {@literal} and {@code}

the text following @param and @return should be a noun phrase, summary description should be a verb phrase. @throws should consist of the word "if" followed by the condition under which the exception is thrown:

/**
* 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);

there are some HTML meta-characters that should be skipped (such as & and <). also first sentence of each doc comment becomes summary description and this will be determined by a dot followed by space, so in this sentence we need to skip the second dot as well:

A college degree, such as B.S., M.S. or Ph.D.

in these situations we can use @literal or @code tags to skip these characters and render them properly

    /**
    * A college degree, such as B.S., {@literal M.S.} or Ph.D.
    */
    public class Degree {...}

Doc comments should be readable both in the source code and in the generated documentation.

9 General Programming

Item 57

Minimize the scope of local variables
the most powerful technique is to declare them where they are first used
if local variable declaration doesn't contain initializer, perhaps we should postpone its declaration to when we have enough information to initialize it.
prefer for loops to while loops because they enforce local variables for iterators
keep methods small and focused
- having a method doing two things (let's say task 1 and task 2), we may define local variables that is used for task 1 but it's not used by task 2!
- to prevent this, simply separate this method into two

Item 58

Prefer for-each loops to traditional for loops
for different reasons such as being more succinct, less error prone and more flexibility we should use for-each loops when possible. Specially that they come with no performance penalty
we should be able to use for-each loops in different situations except when we need to access the iterator index for different scenarios such as removing or modifying an element at a certain index

for (Element element : elements) {
    // do something
}

Item 59

Know and use the libraries
By using a standard library, you take advantage of the knowledge of the experts who wrote it and the experience of those who used it before you
- different functionalities in the libraries get developed and tested with all the edge cases and performance scenarios in mind, gets reviewed by the experts and then gets used by millions of developers. Discovered issues get fixed in future releases.
We should be familiar with standard libraries as well as high-quality 3rd party libraries such as Google's guava library

Item 60

avoid float and double if exact answers are required
these types are designed particularly for scientific and engineering calculations. They carefully provide accurate approximations quickly over a broad range of magnitudes.
they are specially ill-suited for monetary calculations

System.out.println(1.03 - 0.42); // 09999999999999998

use BigDecimal, int (or long) in these situations

Item 61

prefer primitive types to boxed primitives
java has two-part type system:
1. primitives: such as int, double and boolean
2. reference types: such as String and List
every primitive type has a corresponding reference type called boxed primitives
- boxed primitives for int, double and boolean are Integer, Double & Boolean
primitives only have values but boxed primitives have identities distinct from their values. Primitives have only fully functional values whereas boxed primitives have non-functional value which is null. also primitives are more time and space efficient.
there are certain issues that we may encounter when using boxed primitives. for example:
- if we compare them like this: integerOne == integerTwo almost always returns false when their values are equal! (because it compares their identities rather than their values)
- when comparing Integer with int, it will automatically unbox the Integer to get its value and compare it with int. If Integer value is null, it will throw NPE!

  Integer i;
  if (i == 52) { // NullPointerException
      //...
  }

there situations where we can't use primitives. Such as putting elements (or keys or values) in collections. For type parameters also we can't use primitives:
- ThreadLocal<int> is not allowed, you must use ThreadLocal<Integer>
- in summary, we should always use primitives where ever we have the choice.

Item 62

Avoid Strings where other types are appropriate
Strings are designed to represent text, they do a fine job of it. at the same time, they are poor substitutes for other value types.
- poor substitutes for enum types (discussed in Item 34)
- poor substitutes for aggregate types ( strings like 'className#2#true' that are meant to keep different values)
Used inappropriately, strings are more cumbersome, less flexible, slower and more error prone

Item 63

Beware the performance of string concatenation
using string concatenation operator on n strings requires time quadratic in n.
- this is because strings are immutable
don't use string concatenation to combine more than a few strings
for a better performance, use StringBuilder in place of string:

public String statement() {
    StringBuilder stringBuilder = new StringBuilder(newItems() * LINE_WIDTH);
    for (int i = 0; i < numItems(); i++) {
        stringBuilder.append(lineForItem(i));
    }
    return stringBuilder.toString();
}

Item 64

Refer to objects by their interfaces

// good
Set<Son> sonSet = new LinkedHashSet<>();

// bad
LinkedHashSet<Son> sonSet = new LinkedHashSet<>();

If there is no appropriate interface, just use the least specific class that provides the required functionality
if we are using a class-base framework we can use the base class which is usually an abstract class

Item 65

Prefer interfaces to reflection
Using reflection, given a class object you can access its constructor, fields and methods and invoke them. This comes handy when you don't know the class to use until run time.
when using reflection:
- you lose all the benefits of compile time type checking
- the code required for reflection is verbose (see p. 283, 3rd edition for an example)
- performance suffers
we should limit use of reflection as much as possible.
if possible we should create a class instance reflectively and then access the object using an interface or superclass that is known at compile time (to limit use of reflection)

Item 66

Use native methods judiciously
Java lets us call native methods written in native programming languages such as C/C++
- they allow access to low level resources and platform specific facilities such as registries
- they are also used to write performance-critical parts of applications
this item basically says that Java has changed a lot and added more features to make us independent of these native methods. it has also improved performance a lot.
we should rarely use native methods for improved performance
if we use them to access native libraries or low level resources, we should use as little native code as possible

Item 67

Optimize judiciously
this item says that we should avoid optimizing as much as possible! most of the effort is usually wasted and the results are usually negligible and sometimes worse!
instead we should focus on having a good architecture, which in nature is flexible, scalable and fast.
when you're done writing your application, use profiling tools to measure the performance
- if it's fast enough, you're good
- if not, locate source of problem, fix it and measure it afterwards to make sure you made improvements
no amount of low-level optimization can make up for a poor choose of algorithm

Item 68

Adhere to generally accepted naming conventions
there are generally two categories of conventions: typographical and grammatical
package or module
- all lower case
- ideally less than 8 characters
- meaningful abbreviations are encouraged (util instead of utilities)
- start with organization's internet domain in reverse order
- org.junit.jupiter.api, com.google.common
class or interface
- CamelCase
- abbreviations are to be avoided except for common ones such as min and max
- Stream, FutureTask, LinkedHashSet, HttpClient
method or field
- camelCase
- except constants which are all caps, separated with under-score
- remove, groupingBy, getCrc, MIN_VALUE
local variables are lest restricted since they have a limited scope and no visibility in the api. you can use i or abbreviations such as houseNum
- personal note: I still prefer getting into the habit of more readable and meaningful names, specially given that all the modern editors have auto-complete (as mentioned in Clean Code)
type parameters are single letters, E for collection elements, T for an arbitrary type, K and V for key/value types in map, R for return types of methods and X for exception types. a sequence of arbitrary types are T, U, V or T1, T2 and T3
- personal note: lots of developers prefer using full words to make it more clear and meaningful, such as Type instead of T or DataType instead of E, etc. (lots of articles about it online)
grammatical naming conventions are more flexible. none for package and module names. Class names (and enums) are usually singular noun (or noun phrases) such as ChessPiece, Thread,...
non-instantiable utility classes are usually plural noun such as Collectors or Collections
Interfaces are like classes (Collection) or end with -ible/-able like Runnable or Accessible
methods are verbs such as append, drawImage. if returning boolean, usually start with 'is' like isDigit, isEmpty or sometimes like hasSiblings
- methods returning non-boolean usually start with 'get' like getTime but sometimes it can be more readable to avoid get like car.speed()

Effective Java —chapters 2 to 5

Ashkan Entezari — Mon, 04 Nov 2019 14:14:17 +0000

Introduction

Effective Java is a book by Joshua Bloch about Java platform and its best practices.

Bloch is a professor at Carnegie Mellon University. He was formerly the chief Java architect at Google, a distinguished engineer at Sun Microsystems, and a senior systems designer at Transarc. He led the design and implementation of numerous Java platform features, including the JDK 5.0 language enhancements and the Java Collections Framework.

Many consider this book as a must read for any java programmer, many have it on their reading list and many keep it as a reference book and keep referring to it as their work on their java projects.

Recently I read this book which discusses different items (90 in total) about Java, organized in 12 chapters. I learned a lot by reading these items and decided to summarize all of the 90 items to better understand each of them and also to have a quick reference for future.

As part of summarizing the book, I had to simplify a few things, add more explanations a few times, remove a few things and elaborate more on a few items to better understand them. After it was done, I realized that it might be helpful for other people as well. If you haven't read the book and need a faster way to review all of its items (highly recommend to read the book itself) or if you have read the book and need a refresher, or just want a quick reference to a specific item, this summary can help you.

Plan

I will be posting the summary of the 90 items in three posts. Other than the chapter 1 which is introduction, in this post I have summarized chapters 2 to 5 (items 1 to 33).
In part 2 of this post I will include chapters 6 to 9 (items 34 to 68). In the final part, I will include the summary of chapters 10 to 12 (items 69 to 90). Note that this summary is based on the 3rd edition of this book which was published after release of Java 9.

If you found any issues, please let me know and I'll fix them. Without further ado, here is the summary:

2 Creating and Destroying Objects

Item 1

Use static factory methods instead of constructors
static factory method: a static method that returns an instance of the class
a few examples:

  FileStore fileStore = Files.getFileStore(path);
  Date date = Date.from(instant);
  BufferedReader br = Files.newBufferedReader(path);

benefits:
- unlike constructors, they have names
- compare this constructor: BigInteger(int, int, Random) w/ this static factory method: BigInteger.probablePrime(int, int, Random). Here it is more clear that we are returning a BigInteger that is probably prime!
- they don't create a new object each time they are called
- e.g. Boolean.valueOf(boolean) doesn't create a new Boolean object (this allows immutable classes —item 17)
- Unlike constructors, they can return any subtype of their return type (the object)
- e.g., EnumSet has only static factories which return RegularEnumSet if there are less that 64 elements, otherwise they return JumboEnumSet which is backed by a long array. User doesn't need to know about this and just uses it!

Item 2

Use builder when faced w/ many constructor parameters.
maybe for more than 4 parameters in a constructor! or when you know you'll have more class members in future
Compare these two:

 NutritionFacts cocaCola = new NutritionFacts(270, 80, 100, 0, 35, 27);
 // vs.
 NutritionFacts cocaCola = new NutritionFacts.Builder(270, 80).
                                calories(100).sodium(35).carbohydrate(27).build();

as you can see, builder is more readable, arguments are more clear (we know 100 is for calories), we don't need to pass unnecessary parameters for those we don't have a value for (passing default values like '0') and it is more scalable (imagine we had 14 parameters instead of 6!!)
- Simple implementation of the above builder pattern:

  public class NutritionFacts {
    private final int servingSize;
    private final int servings;
    private final int calories;

    public class Builder {
      // Required parameters
      private final int servingSize;
      private final int servings;

      // Optional parameters, initialized to default values:
      private int calories = 0;

      public Builder(int servingSize, int servings) {
        this.servingSize = servingSize;
        this.servings = servings;
      }

      public Builder calories(int val) {
        calories = val;
        return this;
      }

      public NutritionFacts build() {
        return new NutritionFacts(this);
      }
    }

    private NutritionFacts(Builder builder) {
      servingSize = builder.servingSize;
      servings = builder.servings;
      calories = builder.calories;
    }
  }

Item 3

Enforce the singleton property with a private constructor or an enum type (preferred!)
a singleton is a class that is instantiated exactly once
try on of these approaches:

  // singleton w/ static factory (item 1)
  public class Elvis {
      private static final Elvis INSTANCE = new Elvis();

      private Elvis() {...}

      public static Elvis getInstance() {
        return INSTANCE;
      }

      // rest of class implementation...
  }

OR:

    // Enum singleton (preferred):
    public enum Elvis {
      INSTANCE;

      // rest of implementation...
      public void leaveTheBuilding() {...}
    }

only limitation w/ enum type is you can't use enum if you need to extend a superclass

Item 4

Enforce non-instantiability with a private constructor
sometimes we need a class that is a collection of static methods (like java.util.Arrays)
these classes shouldn't have a constructor (not to be instantiated). not writing any constructor will create the default constructor. the solution is a private constructor like this:

public class UtilityClass {
    private UtilityClass() {
      throw new AssertionError();
    }
    ...
}

the only side effect is that this prevents the class from being subclassed, since the subclass would not have an accessible superclass constructor to invoke.

Item 5

Prefer dependency injection to hardwiring resources
not every class needs to be singleton or noninstantiable. sometimes classes behavior is parameterized by underlying resources. In these cases we need to pass the resource to the class
One common way of doing this is passing the resource through constructor when creating a new instance

public class SpellChecker {
    private final Lexicon dictionary;

    public SpellChecker(Lexicon dictionary) {
      this.dictionary = Objects.requireNonNull(dictionary);
    }
    ...
}

DI provides flexibility and testability
in big projects w/ lots of dependencies, handling this can be a bit problematic. In this case dependency injection frameworks can be used to eliminate the clutter
- such as Guice, Dagger or Spring

Item 6

Avoid creating unnecessary objects
this basically says don't create a new object when you can reuse an existing one!
One simple example:

String s = new String("hello"); // don't do this!
String s = "hello"; // this will reuse the string instead of creating a new one

Item 7

Eliminate obsolete object references
Java has garbage collection but in some situation we may leave an unnecessary reference to an object which prevents it from being garbage collected!
for example look at this stack implementation:

public class Stack {
    private Object[] elements;
    private int size = 0;
    // ...

    public void push(Object element) {
        elements[size++] = element;
    }

    public Object pop() {
        if (size == 0) {
            throw new EmptyStackException();
        }
        return elements[--size];
    }
    // ...
}

in this example, our stack cares about the first "size" elements of the stack although other elements are still referring to objects. Java has no idea about that those references are not needed. So it won't be garbage collected and we will have a memory leak here.
in this case we can do this elements[size] = null; to eliminate the obsolete reference.
another benefit of doing this is that if by mistake we dereference the object, it will throw an NPE

Item 8

Avoid finalizers and cleaners
as of Java 9, finalizers have been deprecated and replaced w/ cleaners
they are somehow like destructors in C++ and used to perform some cleanup before garbage collection happens for a particular object
they are both problematic, execution is not guaranteed, they can cause deadlocks
finalizers have even more issues, security issues (known as finalizer attacks) and they ignore exceptions!
what should we do instead?
- best approach is to make the class implement AutoClosable and require its clients to call close() or even better use them in try-with-resource blocks

Item 9

Prefer try-with-resources to try-finally
there are many java resources that must be closed manually
- InputStream, BufferedReader, java.sql.Connection, etc.
in these situations consider using try-with-resources because:
- it is more concise and readable (specially if there are more than one resources)
- in try-finally if the code in try throws an exception and then the code in finally throws another exception, there is no record of the first exception in the exception stack trace
to be usable w/ this construct, a resource must implement AutoClosable
- many classes and interfaces in Java libraries implement or extend AutoClosable
- if you write a class that represents a resource that needs to be closed, make sure you implement AutoClosable too.

  static void copy(String src, String dst) throws IOException {
      try (InputStream in = new FileInputStream(src);
           OutputStream out = new FileOutputStream(dst)) {
               byte[] buffer = new byte[BUFFER_SIZE];
               int n;
               while ((n = in.read(buffer)) >= 0)
                   out.write(buffer, 0, n);
           }
  }

3 Methods Common to All Objects

Item 10

Obey the general contract when overriding equals
first make sure that you need to do that! in these cases you don't need to override it:
- each instance of the class is inherently unique (like Thread)
- there is no need for the class to provide a "logical equality" test
- like java.util.regex.Pattern
- a superclass has already overriden equals
- e.g. most Set implementations inherit their equals from AbstractSet
if you override, you must adhere to its general contract:
1. Reflexive: x.equals(x) must return true
2. Symmetric: x.equals(y) is true if and only if y.equals(x) is true
3. Transitive: x.equals(y) and y.equals(z) then x.equals(z) must be true as well
4. Consistent: x.equals(y) must consistently return true or false
5. for non-null reference value x, x.equals(null) must return false
usually it will be easy to follow this contract but if this doesn't happen we may break so many functionalities with Collections and other things.
There is no way to extend an instantiable class and add a value component while preserving the equals contract
- one solution can be using composition instead of inheritance, or:
- having an abstract class and overriding its sub-classes
When you have to override equals consider the following:
1. for performance optimization use == to check if the argument is a reference to this object (if so, return true)
2. use instanceof to check if the argument has the correct type (if not, return false)
3. cast the argument to the correct type

Item 11

You must override hashCode when you override equals
general contract for hashCode:
1. invoking multiple times should always return same hash value
2. if two objects are equal (according to equals) then calling hashCode on them should return same integer value
3. it is not required to return different hash values for different objects, but doing so will help with performance
if you don't override hashCode when you override equals, you can break item 2 above
to override the hashCode, you have to calculate the value starting from the first significant field, you add the calculated value of each field and result would be the hash value for that object
define an integer called result and for each field, based on its type calculate the value like this:
- if field is a primitive type, use Type.hashCode(field)
- if field is an object, use hashCode() on that function. (if it is null, use 0)
- for arrays, if all fields are significant, use Arrays.hashCode, else calculate the value for each item in the array based on its type (one of the previous 2 steps)
add the calculated hash code c for each field into result:
- result = 31 * result + c;
based on above explanations, for PhoneNumber class (has areaCode, prefix and lineNum) you can do this:

@override
public int hashCode() {
    int result = Short.hashCode(areaCode);
    result = 31 * result + Short.hashCode(prefix);
    result = 31 * result + Short.hashCode(lineNum);
    return result;
}

if performance is not a concern we can use Objects.hash() (previous example is still better):

@override
public int hashCode() {
    return Objects.hash(lineNum, prefix, areaCode);
}

Notes

the number 31 above: it is an odd prime, if it was even and multiplication overflowed, information would be lost. advantage of using a prime is less clear but it's traditional. also for the sake of optimization: 31 * i == (i << 5) - i
write tests for your hashCode, for example make sure multiple calls on the same object returns same value. if you use AutoValue you don't need testing it.

Item 12

always override toString
not as critical as last two items, but very useful and important
- used by default when printing the object, logging, debugging, asserting, ...
by default all objects will return objectName + @ + hashValue (e.g. PhoneNumber@158b39)
general contract for toString is: a concise but informative representation that is easy to read
- e.g. for PhoneNumber we can return 416-421-7373
when practical, toString should return all of the interesting information, otherwise a meaningful summary
always try to specify the format in a comment when overriding toString. if it is subject to change, specify that (like you add more fields in future or just change the format):

/**
* Returns the String representation of this phone number.
* The string contains 12 characters whose format is ....
*/
@override
public String toString() {
    return String.format("%03d-%03d-%04d", areaCode, prefix, lineNum);
}

Notes

if you show something in toString, provide programmatic access to it so user doesn't have to parse the string

Item 13

Override clone judiciously
if a class implements Cloneable, Object's clone method returns a field-by-field copy of the object ow it throws CloneNotSupportedExeption
- highly atypical use of interface! instead of defining behavior for class, changes behavior of a protected method on a superclass
a class implementing Cloneable is expected to provide a proper Clone method
always call super.clone(); first. If your class only contains primitive values or reference to immutable objects, that's all you need:

@Override
public PhoneNumber clone() {
    try {
        return (PhoneNumber) super.clone();
    } catch (CloneNotSupportedExeption e) {
        throw new AssertionError(); // Can't happen
    }
}

but if class has other types, you have to fix them in Clone method after calling super.clone(). For example in Stack example that we have an array of object (Object[] elements;), calling super.clone() returns a replica in which the elements refers to the same array as the original, in this case we can do this:

@Override
public Stack clone() {
    try {
        Stack result = (Stack) super.clone();
        result.elements = elements.clone();
        return result;
    } catch (CloneNotSupportedExeption e) {
        throw new AssertionError();
    }
}

For more complicated objects it will get harder to create a proper copy:

public class HashTable implements Cloneable {
    private Entry[] buckets = ...;

    private static class Entry {
        final Object key;
        Object value;
        Entry next;

        Entry(Object key, Object value, Entry next) {
            this.key = key;
            ...
        }

        Entry deepCopy() {
            return new Entry(key, value, next == null ? null : next.deepCopy());
        }
    }

    @Override
    public HashTable clone() {
        try {
            HashTable result = (HashTable) super.clone();
            result.buckets = new Entry[buckets.length];
            for (int i=0; i < buckets.length; i++) {
                if (buckets[i] != null) {
                    result.buckets[i] = buckets[i].deepCopy();
                }
                return result;
            }
        } catch(...) {...}
    }
}

a better approach to object copying is to provide a copy constructor or copy factory

public Yum(Yum yum) {...}  // copy constructor
public static Yum newInstance(Yum yum) {...} // copy factory

Item 14

Consider implementing Comparable
- when you implement a value class that has a sensible ordering
by implementing it, a class indicates that its instances have a natural ordering
by implementing Comparable, you allow your class to interoperate with all of the many generic algorithms and collection implementations that depend on it
the general contract for compareTo is similar to that of equals
- sgn(x.compareTo(y)) == -sgn(y.compareTo(x))
- if one throws exception the other one throws exception as well
- x.compareTo(y) > 0 and y.compareTo(z) > 0 ==> x.compareTo(z) > 0
- x.compareTo(y) == 0 ==> sgn(x.compareTo(z)) == sgn(y.compareTo(z)) for all z
if a class has multiple significant fields, start from the most to the least significant:

public int compareTo(PhoneNumber phoneNumber) {
    int result = Short.compare(areaCode, phoneNumber.areaCode);
    if (result == 0) {
        result = Short.compare(prefix, phoneNumber.prefix);
        if (result == 0) {
            result = Short.compare(lineNum, phoneNumber.lineNum);
        }
    }
    return result;
}

Comparator based on static compare method:

static Comparator<Object> hashCodeOrder = new Comparator<>(){
    public int compare(Object o1, Object o2) {
        return Integer.compare(o1.hashCode, o2.hashCodeOrder);
    }
};

Notes

in implementations of compareTo never use < or > and always use static compare methods

4 Classes and Interfaces

Item 15

Minimize the accessibility of classes and members
make each class or member as inaccessible as possible
Information Hiding or Encapsulation:
- components communicate only through their APIs and are oblivious to each other's inner workings
Four possible access levels (most restrictive to least restrictive):
1. private: only accessible in the class it is defined
2. package-private: also known as default access, member is accessible from any class in the package
3. protected: accessible from subclasses of the class where it is defined + any class in the package
4. public: accessible from anywhere
by default everything should be declared as private, sometimes it is fine to make them package-private (like for testing) but moving to protected is a major change as they will become part of class's public API and must be supported forever!
it is wrong to have a public static final array field (or an accessor that returns such field):

// potential security hole:
public static final Thing[] VALUES = {...};
//
// one alternative can be:
private static final Thing[] PRIVATE_VALUES = {...};
public static final List<Thing> VALUES =
    Collections.unmodifiableList(Arrays.asList(PRIVATE_VALUES));

Notes:

default access is always package-private except interfaces where it is public
classes w/ public mutable fields are not generally thread-safe

Item 16

In public classes, use accessor methods not public fields

// Encapsulation of data using getters/setters (accessor/mutators):
class Point {
    private double x;
    private double y;

    public Point(double x, double y) {
        this.x = x;
        this.y = y;
    }

    public double getX() { return x; }
    public double getY() { return y; }

    public void setX(double x) { this.x = x; }
    public void setY(double y) { this.y = y; }
}

Item 17

Minimize mutability
immutable class is one that its instances can not be modified
all classes should be declared immutable unless there is a good reason to make them mutable
- in this case we should limit its mutability as much as possible
follow these rules to make your classes immutable:
1. don't provide methods that modify the object (mutators)
2. ensure that class can not be extended
3. make all fields final
4. make all fields private
5. ensure exclusive access to any mutable components
6. e.g. if your class has a field referring to a mutable component, make sure it is private and when returning that through a getter, we can make a defensive copy
some of the advantages of immutable classes:
- They are very simple
- they have exactly one state, the one that was assigned at creation time
- inherently thread-safe, require no synchronization
- can be shared freely
- these classes should encourage clients to reuse existing instances whenever possible
- they can even share their internals (like BigInteger that has sign and magnitude, negative value share the same magnitude and have different signs)
- they make great building blocks for other objects
- specially as map keys or set elements
- They provide failure atomicity for free
- their state never change and there won't be any temporary inconsistencies or random failures!
- you can use lazy initialization on some of its fields
- e.g. hash value of an immutable object never changes, so if its hash value is requested we calculate it once and if its requested again, we just return that same value moving forward (better performance)
the major disadvantage is that they require a separate object for each distinct value
- if you have a million bit BigInteger and want to change its low-order bit
- there are different ways to cope with these issues, for example BigInteger has a companion package-private class that it uses to enhance its performance and memory usage while client can't see and use that mutable class.
simple example of an immutable class:

public final class Complex {
    private final double re;
    private final double im;

    public Complex(double re, double im) {
        this.re = re;
        this.im = im;
    }

    public double realPart() { return re; }
    public double imaginaryPart() { return im; }

    public Complex plus(Complex c) {
        return new Complex(re + c.realPart(), im + c.imaginaryPart());
    }

    ...
}

Item 18

Favor composition over inheritance
unlike method invocation, inheritance violates encapsulation
- subclass depends on the implementation details of its super class
it is safe to
- use inheritance when it is within the same package (controlled by same programmer)
- use inheritance when extending classes that are designed and documented for extension (item 19)
in other cases, many things can go wrong that breaks your code, such as:
- you wanna implement an instrumented HashSet that counts how many items have been added (not the size, including those removed). HashSet has add() and addAll() for which you can override and simply add number of elements to a counter each time any of these are called. Little you know that addAll() calls the add() behind the scene so if you add 2 elements to your set, counter will show 4!
- sometimes they don't have these dependencies but in future updates the superclass may make these changes which still gives same input/output (valid updates) but it may break subclasses if they depend on these implementation details
- let's say you have a collection with a few insert methods that you override them all to make them secure inserts and your clients use them. In future if that collection adds a new insert method your users can potentially use that new insert method and work around your security checks!
These issues won't happen if both classes are controlled by one person (team) or when they are designed to be inherited. This won't also happen when the superclass provides implementation details so you can be careful when inheriting it.
The best way to get around these issues and yet use the abilities of the superclass is to use composition. So instead of extending that class, you create a private instance of that class in your class and our methods can call the methods on this instance. (known as forwarding)

Notes:

Inheritance is appropriate only where the subclass is really a subtype of the superclass
- when class B extends A, ask yourself is B really an A?

Item 19

Design and document for inheritance or else prohibit it
the class must document its self-use of overridable methods
use the java doc to include these details. Since Java 8 there are new tags including @implSpec that should be used of Implementation Requirements. The person overriding these methods should review these documents to make sure he is not breaking things.
The only way to test a class designed for inheritance is to write subclasses
Constructors must not invoke overridable methods.
- this can lead to serious bugs, avoid it!
designing class for inheritance is hard work! you have to document all of its self-use patterns and then commit to them for the life of the class. If you change them in future, you may break other ppl code!

Item 20

Prefer interfaces to abstract classes.
as mentioned earlier inheritance has its own issues and when not necessary we better avoid them! In contrast interfaces don't have those issues and enable safe and powerful functionality enhancement
A class can have one super class but can implement many interfaces
default methods were introduced in Java 8 which let us change existing interfaces (still need to be careful). We add the new method with a default implementation, if it is not defined in the class implementing that interface, the default implementation will be used when needed.
We can also combine an interface with an abstract class implementing that interface to maximize the benefits. These abstract classes are known as Skeletal Implementation:
- the way it works, you have your interface, you create an abstract class that implements that interface and provides implementation for the interface methods
- now user can extend the skeletal implementation (their naming convention is Abstract*InterfaceName*) and for example only override one method and then use the default implementations in AbstractInterface for all other methods
- if for example in another use case we need to override all the interface methods, user has the flexibility to just implement the interface directly (not using AbstractInterface) and override all methods
- an example of this:

  /**
   * The Interface
   *
   */
  interface RedisConnection
  {
      int connect();
      boolean isConnected();
      int disconnect();
      int getDatabaseNumber();
  }

  /**
   * Abstract class which implements the interface.
   * This is called Abstract Interface known as Skeletal Implementation
   *
   */
  abstract class AbstractRedisConnection implements RedisConnection
  {
      @Override
      public final int connect()
      {
          //... lots of code to connect to Redis
      }

      @Override
      public final boolean isConnected()
      {
          //... code to check Redis connection
      }

      @Override
      public final int disconnect()
      {
          //... lots of code to disconnect from Redis and perform cleanup
      }
   }

  /**
   * A subclass which extends from the Abstract Interface
   *
   */
  class RedisOptOut extends AbstractRedisConnection {…}

here if we don't need to redefine those interface methods we just extend the AbstractRedisConnection and will have those default implementations.

Item 21

Design interfaces for posterity
this item mostly talks about the default implementation of interface methods added in Java 8 (mainly to facilitate the use of lambdas)
although it is a powerful and helpful feature but we should be very careful and try not to change interfaces if possible
Java library has some changes to interfaces with new default methods that in some scenarios will break (like removeIf in synchronizedCollection)

Item 22

Use interfaces only to define types
When a class implements an interface that should serve as a type that can be used to refer to instances of the class
there are some cases that interfaces are used to hold constants which is wrong and should be avoided:

  // bad use of interface:
  public interface PhysicalConstants {
      static final double AVOGADROS_NUMBER = 6.022_140_857e23;
      static final double BOLTZMANN_CONTANT = 1.380_648_52e-23;
      ...
  }

this constant patter is a poor use of interface. Alternatives are:

make these constants part of the class that needs them (as a member)
use an Enum
have a utility class to keep them:

package com.ashkan.science;

public class PhysicalConstants {
    static final double AVOGADROS_NUMBER = 6.022_140_857e23;
    static final double BOLTZMANN_CONTANT = 1.380_648_52e-23;
}

then we can use these constants like PhysicalConstants.AVOGADROS_NUMBER. also if one class is heavily using these constants, in order to make it shorter and easier to use, we can use static import:

  import static com.ashkan.science.PhysicalConstants.*;

  public class Test {
      double atoms(double mols) {
          return AVOGADROS_NUMBER * mols;
      }
  }

Note:

the underscore in numbers above (since Java 7) is used for readability and doesn't change the value of the numbers or break them.

Item 23

Prefer class hierarchies to tagged classes.
tagged classes have a tag field that based on its value the class instance gets a different flavor. e.g.

class Figure {
    enum Shape { RECTANGLE, CIRCLE };

    final Shape shape; // tag field

    // these fields used only if it's RECTANGLE:
    double length;
    double width;

    // this field used only if shape is CIRCLE:
    double radius;

    /*
    rest is omitted for brevity: basically different constructors based on Shape and area() method with a switch(shape) statement that behaves differently based on shape, so on and so forth
    */
}

these classes are verbose, error-prone and inefficient (specially memory wise). They violate SRP and they are basically pallid imitation of class hierarchy
avoid these type of classes and replaces them with proper hierarchies.

Item 24

Favor static member classes over non-static
a nested class should exist to serve its enclosing class.
if a nested class will be useful in some other context, then it should be a top-level class
there are four kinds of nested classes:
1. static member classes
2. one common use case is a helper class that can be used in conjunction w/ its outer class. Like Calculator class can have Operation class inside and we can refer to its operations like Calculator.Operation.PLUS.
3. if you declare a class that does not need access to its enclosing instance, make it static.
4. non-static member classes
5. these classes are associated w/ their enclosing class and need to be instantiated. One common use of these non-static member classes is to define an Adapter: this lets an instance of the enclosing class to be viewed as an instance of some other class (like viewing Map's values or keys as a collection view)
6. anonymous classes
7. they can be used anywhere that expressions are allowed
8. they have limitations, such as can not be instantiated or we can't use instanceof on them
9. before lambdas, they were more useful for creating small function objects and process objects but now wherever possible, we should use lambdas
10. local classes
11. they are the least frequently used
these four types should be considered 1 to 4, most to least preferable!

Item 25

Limit source files to a single top-level class
Java let us define multiple top-level classes or interfaces in a single file. This item basically says never do this, it is confusing, messy and can result in errors depending on how you execute your program:

// Animal.java —don't do this
public class Dog {
    ...
}

public class Cat {
    ...
}

5 Generics

Item 26

Don't use raw types
a class/interface whose declaration has type parameters is a generic class/interface
- List<E> --> list of E (elements of type E)
- List<String> --> list of String (elements of type String)
- List --> raw type: list can contain anything (old Java)
main issue of raw types is we may get run-time exceptions. With generic types we will get compile-time exception if we attempt to put an incompatible type into our collection.

  // Raw collection type - don't do this:
  private final Collection stamps = ...;

here we can add something other than Stamp to this collection but later on if do something like Stamp stamp = (Stamp) stamps.get(0); and its first element is not Stamp it will throw ClassCastException
also we have to cast everything that we retrieve from this raw type collection. The correct way of declaring that collection is:

  private final Collection<Stamp> stamps = ...;

Wildcard types are type arguments in the form <?> which can have lower bound and upper bound. They are unknown types and give us some flexibility when working with types that we don't know and at the same time type safety so if we have List<?> myList then the only thing that can be added to this list is null (which is member of every type).

Item 27

Eliminate unchecked warnings
When working w/ generics you see many unchecked warnings. Eliminate every unchecked warning that you can and suppress the rest.
When you can't eliminate the warning but you can prove that the code generating it is type safe, suppress it with @SupressWarnings("unchecked")
- use it on smallest scope possible
- don't use it on entire class or a method declaration
every time you use this tag, explain in a comment why it is safe to do so

// Adding local variable to reduce scope of @SuppressWarnings
public <T> T[] toArray(T[] a) {
    if (a.length < size) {
        // This cast is correct because the array we're creating
        // is of the same type as the one passed in, which is T[].
        @SuppressWarnings("unchecked") T[] result =
            (T[]) Arrays.copyOf(elements, size, a.getClass());
        return result;
    }
    System.arraycopy(elements, 0, a, 0, size);
    if (a.length > size)
        a[size] = null;
    return a;
}

Item 28

Prefer lists to arrays
arrays are covariant, generics are invariant
- Covariant: if Sub is a subtype of Super, then the array type Sub[] is a subtype of Super[]
- invariant: for any two distinct types Type1 and Type2, List<Type1> is neither subtype nor a supertype of List<Type2>
arrays are deficient:

// fails at runtime
Object[] objectArray = new Long[1];
objectArray[0] = "I don't fit in!"; // throws ArrayStoreException

but this will give you compile time error:

// won't compile
List<Object> objectList = new ArrayList<Long>(); // incompatible types

arrays and generics do not mix well, these expressions are illegal:
- List<E>[], new List<String>[] or new E[]
- the reason is they are not type safe
when using arrays with generics, we may get compile errors or unchecked cast warnings. when this happens the best solution often is to use List<E> (replace arrays with lists)

Item 29

Favor generic types
generic types are safer and easier to use than the types that require casts in client code
we should design our code and types to be generic for this reason
- as an example, this item changes the Stack implementation of Item 7 to use generics instead of Object
- when we do this we will get one error in the constructor (elements = new E[...];)
- it resolves it by changing it to elements = (E[]) new Object[...];
- after this we will get a warning but we can justify that elements is internal and will be safe to do so, then based on Item 26 we suppress the warning.
- takeaway: if we can avoid using lists (item 28) it will be more efficient to use arrays! otherwise as item 28 suggests, use lists.
Bounded type: when working w/ generics, we can define a type like <E extends Delayed> which means that we have a generic type that is a subtype of java.util.concurrent.Delayed. The advantage is that we can use methods of Delayed on elements of our generified class (which are of type E).

Item 30

Favor generic methods
same as classes, methods can be generic and we need to use them specially when we have a method whose use requires casting!
to make a method generic, you need to put the type parameter between method's modifier and its return type:

public static <E> Set<E> union(Set<E> s1, Set<E> s2) {
    ...
}

generic methods can be used in generic singleton factory pattern:

private static UnaryOperator<Object> IDENTITY_FN = (t) -> t;

@SupressWarnings("unchecked")
public static <T> UnaryOperator<T> identityFunction() {
    return (UnaryOperator<T>) IDENTITY_FN;
}

// now we can use it on any type:
Number[] numbers = {1, 2.0, 3L};
UnaryOperator<Number> sameNumber = identityFunction();
for (Number number : numbers) {
    System.out.println(sameNumber.apply(number));
}
// or (my example which "I think" should be correct and makes more sense to me):
BigDecimal b = new BigDecimal("1234.1241234");
UnaryOperator<BigDecimal> sameDecimal = identityFunction();
BigDecimal b1 = sameDecimal.apply(b);

Item 31

Use bounded wildcards to increase API flexibility
parameterized types are invariant (two distinct types Type1, Type2 -> List<Type1> is not sub/super type of List<Type2>)
- look at this Stack implementation (here only included the public API):

  public class Stack<E> {
      public Stack();
      public void push(E element);
      public E pop();
  }

we now add the pushAll() method to this class:

  public void pushAll(Iterable<E> src) {
      for (E element : src) {
          push(element);
      }
  }

since parameterized types are invariant, this won't work:

  Stack<Number> numberStack = new Stack<>();
  Iterable<Integer> integers = ...;
  numberStack.pushAll(integers);

although Integer is a subtype of Number but list of it is not! to fix it we need to change pushAll to this:

  public void pushAll(Iterable<? extends E> src) {...}

for the exact same reason, popAll() should be implemented like this:

  public void popAll(Iterable<? super E> dst) {
      while (!isEmpty()) {
          dst.add(pop());
      }
  }

<?> is a wildcard type and when used with extends/super is called a bounded wildcard type
- <? extends E>: any subtype of E
- <? super E>: any supertype of E
for maximum flexibility of our API, we should use bounded wildcard types on input parameters that represent producers or consumers
- PECS stands for producer-extends, consumer-super
- so pushAll() is producing (for internal stack) so it extends
- and popAll() is consuming (from internal stack) so it uses super

Notes

do not use bounded wildcard types as return types
all comparables and comparators are consumers

Item 32

Combine generics and varargs judiciously
varargs (variable legnth arguments) was introduced in Java 5 (same as generics) but they don't work well with each other!
- we can have a method like public void func(int... input) {...} and then call it like func(2); or func(1, 4, 3); etc.
- when we invoke varargs, an array is created to hold the parameters.
- as mentioned in Item 28, arrays and generics do not mix well!
whenever we use varargs on a method with parameterized type, we will get a warning (possible heap pollution warning). To fix this we have to do one of the following:
1. make sure it is type safe and then use @SafeVarargs, or:
2. replace varargs with a list (sth like item 28 to use list instead of arrays)
varargs methods are safe if:
1. it doesn't store anything in the varargs parameter array, and
2. i.e. we don't assign anything to the passed in parameter that is a vararg
3. it doesn't make the array (or a clone) visible to the untrusted code
4. for example getting the varargs parameter and returning it, so another code can get it, use it and break it

Note

@SafeVarargs is legal only on methods that can not be overriden (o.w. those methods may break its safety!)
use @SafeVarargs on every method with a varargs parameter of a generic or parameterized type (so users won't be burdened with warnings)

Item 33

Consider typesafe heterogeneous containers
Common uses of generic collections are like Set<E> and Map<K, V> which is a parametrized container that contains elements of one type.
Usually this is what we want but sometimes we may need a typesafe container that can store and return elements of different types.
- we parametrize the key instead of the container!
before we take a look at one example, consider the following:
- the type of a class literal is Class<T>:
- type of String.class is Class<String>
- when a class literal is passed around for type information it is called a type token
here is a typesafe heterogeneous container:

public class Favorites {
    private Map<Class<?>, Object> favorites = new HashMap<>();

    public <T> void putFavorite(Class<T> type, T instance) {
        favorites.put(Objects.requireNonNull(type), instance));
    }

    public <T> T getFavorite(Class<T> type) {
        return type.cast(favorites.get(type));
    }
}

a sample program to use the above container:

Favorites favorites = new Favorites();
favorites.putFavorite(String.class, "Java");
favorites.putFavorite(Integer.class, 0xcafe);
int favInt = favorites.getFavorite(Integer.class);