Effective Java

Chapter 2. Creating and Destroying Objects¶

1. Consider static factory methods instead of constructors

A class can provide a public static factory method, which is simply a static method that returns an instance of the class.

A static factory method is not the same as the Factory Method pattern from Design Patterns

Advantages:

• can use well-chosen name to make code easier to read
• not required to create a new object each time invoked
  • save resource on expensive-to-create objects
• can return an object of any subtype of their return type
  • requires the client to refer to the returned object by interface rather than implementation class
  • an API can return objects without making their classes public, hiding implementation classes
• the class of the returned object can vary from call to call as a function of the input parameters
• the class of the returned object need not exist when the class containing the method is written

Disadvantages:

• classes without public or protected constructors cannot be subclassed
• static factory methods are hard for programmers to find
  • do not stand out in API documentation

Side note about service provider framework¶

There are three essential components in a service provider framework: a service interface, which represents an implementation; a provider registration API, which providers use to register implementations; and a service access API, which clients use to obtain instances of the service.

The service access API may allow clients to specify criteria for choosing an implementation. In the absence of such criteria, the API returns an instance of a default implementation, or allows the client to cycle through all available implementations. The service access API is the flexible static factory that forms the basis of the service provider framework.

An optional fourth component of a service provider framework is a service provider interface, which describes a factory object that produces instances of the service interface. In the absence of a service provider interface, implementations must be instantiated reflectively.

In the case of JDBC, Connection plays the part of the service interface, DriverManager.registerDriver is the provider registration API, DriverManager.getConnection is the service access API, and Driver is the service provider interface.

Some common names for static factory methods¶

• from — A type-conversion method that takes a single parameter and returns a corresponding instance of this type. i.e. Date.from(instant)
• of — An aggregation method that takes multiple parameters and returns an instance of this type that incorporates them, i.e. EnumSet.of(JACK, QUEEN, KING)
• valueOf — A more verbose alternative to from and of, i.e. BigInteger.valueOf(Integer.MAX_VALUE)
• instance or getInstance — Returns an instance that is described by its parameters (if any) but cannot be said to have the same value. i.e. StackWalker.getInstance(options)
• create or newInstance — Like instance or getInstance, except that the method guarantees that each call returns a new instance, i.e. Array.newInstance(classObject, arrayLen)
• getType — Like getInstance, but used if the factory method is in a different class. Type is the type of object returned by the factory method. i.e. Files.getFileStore(path)
• newType — Like newInstance, but used if the factory method is in a different class. Type is the type of object returned by the factory method. i.e. Files.newBufferedReader(path)
• type — A concise alternative to getType and newType. i.e. Collections.list(legacyLitany)

1. Consider a builder when faced with many constructor parameters

Instead of making the desired object directly, the client calls a constructor (or static factory) with all of the required parameters and gets a builder object.

Then the client calls setter-like methods on the builder object to set each optional parameter of interest.

Finally, the client calls a parameterless build method to generate the object, which is typically immutable.

To detect invalid parameters as soon as possible, check parameter validity in the builder’s constructor and methods. Check invariants involving multiple parameters in the constructor invoked by the build method. To ensure these invariants against attack, do the checks on object fields after copying parameters from the builder. If a check fails, throw an IllegalArgumentException.

The Builder pattern is well suited to class hierarchies. Use a parallel hierarchy of builders, each nested in the corresponding class.

public abstract class Pizza {
   public enum Topping { HAM, MUSHROOM, ONION, PEPPER, SAUSAGE }

   final Set<Topping> toppings;

   abstract static class Builder<T extends Builder<T>> { // generic type with a recursive type parameter
      EnumSet<Topping> toppings = EnumSet.noneOf(Topping.class);
      public T addTopping(Topping topping) {
         toppings.add(Objects.requireNonNull(topping));
         return self();
      }
      abstract Pizza build();
      // Subclasses must override this method to return "this"
      protected abstract T self();
   }

   Pizza(Builder<?> builder) {
      toppings = builder.toppings.clone(); // See Item  50
   }
}
public class NyPizza extends Pizza {
    public enum Size { SMALL, MEDIUM, LARGE }
    private final Size size;

    public static class Builder extends Pizza.Builder<Builder> {
        private final Size size;
        public Builder(Size size) {
            this.size = Objects.requireNonNull(size);
        }
        @Override public NyPizza build() {
            return new NyPizza(this);
        }
        @Override protected Builder self() { return this; }
    }

    private NyPizza(Builder builder) {
        super(builder);
        size = builder.size;
    }
}
NyPizza pizza = new NyPizza.Builder(SMALL).addTopping(SAUSAGE).addTopping(ONION).build();

the Builder pattern is a good choice when designing classes whose constructors or static factories would have more than a handful of parameters, especially if many of the parameters are optional or of identical type.

1. Enforce the singleton property with a private constructor or an enum type

Making a class a singleton can make it difficult to test its clients because it’s impossible to substitute a mock implementation for a singleton unless it implements an interface that serves as its type.

public class Elvis {
  // exactly one Elvis instance will exist once the Elvis class is initialized—no more, no less
  public static final Elvis INSTANCE = new Elvis();
  private Elvis() { ... }
  ...
}

The above approach is simple and guarantees a singleton instance.

// another approach
public class Elvis {
  private static final Elvis INSTANCE = new Elvis();
  private Elvis() { ... }
  // All calls to Elvis.getInstance return the same object reference, and no other Elvis instance will ever be created
  public static Elvis getInstance() { return INSTANCE; }
}

The above approach gives the flexibility to change mind for singleton, allows us write generic singleton factory, and a method reference can be used as a supplier i.e. Elvis::instance

// a third way
public enum Elvis {
  INSTANCE;
  ...
}

The above approach is very concise, with serialization.

To make sure even after the object is deserialized still a singleton,

public class Elvis implements Serializable {
  private static final transient Elvis INSTANCE = new Elvis();
  ...
  private Object readResolve() { return INSTANCE; }
}

A single-element enum type is often the best way to implement a singleton. Note that you can’t use this approach if your singleton must extend a superclass.

1. Enforce noninstantiability with a private constructor

a class can be made noninstantiable by including a private constructor.

1. Prefer dependency injection to hardwiring resources

Static utility classes and singletons are inappropriate for classes whose behavior is parameterized by an underlying resource.

Dependency Injection: Pass the resource into the constructor when creating a new instance.

It preserves immutability, and is equally applicable to constructors, static factories, and builders.

A useful variant of the pattern is to pass a resource factory to the constructor. The Supplier interface, introduced in Java 8, is perfect for representing factories.

Methods that take a Supplier on input should typically constrain the factory’s type parameter using a bounded wildcard type to allow the client to pass in a factory that creates any subtype of a specified type. i.e. Mosaic create(Supplier<? extends Tile> tileFactory) { ... }

In summary, do not use a singleton or static utility class to implement a class that depends on one or more underlying resources whose behavior affects that of the class, and do not have the class create these resources directly.

Instead, pass the resources, or factories to create them, into the constructor (or static factory or builder).

1. Avoid creating unnecessary objects

Reuse can be both faster and more stylish. An object can always be reused if it is immutable.

Some object creations are much more expensive than others. If you’re going to need such an "expensive object" repeatedly, it may be advisable to cache it for reuse.

One good example:

static boolean isRomanNumeral(String s) {
    return s.matches("^(?=.)M*(C[MD]|D?C{0,3})" + "(X[CL]|L?X{0,3})(I[XV]|V?I{0,3})$");
}

is expensive to create a Pattern Object. As the method is called repeatedly, more Pattern Objects are created. Better:

public class RomanNumerals {
    private static final Pattern ROMAN = Pattern.compile("^(?=.)M*(C[MD]|D?C{0,3})" + "(X[CL]|L?X{0,3})(I[XV]|V?I{0,3})$");
    static boolean isRomanNumeral(String s) {
        return ROMAN.matcher(s).matches();
    }
}

Aside from the performance improvement, making a static final field for the otherwise invisible Pattern instance allows us to give it a name, which is far more readable than the regular expression itself.

Prefer primitives to boxed primitives, and watch out for unintentional autoboxing.

Avoiding object creation by maintaining your own object pool is a bad idea unless the objects in the pool are extremely heavyweight.

Generally speaking, however, maintaining your own object pools clutters your code, increases memory footprint, and harms performance. Modern JVM implementations have highly optimized garbage collectors that easily outperform such object pools on lightweight objects.

1. Eliminate obsolete object references

A prog. lang with garbage collector does not mean you don't need to worry about memory management.

The best way to eliminate an obsolete reference is to let the variable that contained the reference fall out of scope. This occurs naturally if you define each variable in the narrowest possible scope.

Generally speaking, whenever a class manages its own memory, the programmer should be alert for memory leaks. Whenever an element is freed, any object references contained in the element should be nulled out.

Another common source of memory leaks is caches.

A third common source of memory leaks is listeners and other callbacks, which happens when clients register callbacks but don’t deregister them explicitly. One way to ensure that callbacks are garbage collected promptly is to store only weak references to them, for instance, by storing them only as keys in a WeakHashMap.

1. Avoid finalizers and cleaners

Finalizers are unpredictable, often dangerous, and generally unnecessary.

Cleaners are less dangerous than finalizers, but still unpredictable, slow, and generally unnecessary.

It can take arbitrarily long between the time that an object becomes unreachable and the time its finalizer or cleaner runs. This means that you should never do anything time-critical in a finalizer or cleaner. And you should never depend on a finalizer or cleaner to update persistent state.

Just have your class implement AutoCloseable, and require its clients to invoke the close method on each instance when it is no longer needed, typically using try-with-resources to ensure termination even in the face of exceptions.

One detail worth mentioning is that the instance must keep track of whether it has been closed: the close method must record in a field that the object is no longer valid, and other methods must check this field and throw an IllegalStateException if they are called after the object has been closed.

So what, if anything, are cleaners and finalizers good for? They have perhaps two legitimate uses.

One is to act as a safety net in case the owner of a resource neglects to call its close method.

A second legitimate use of cleaners concerns objects with native peers. A native peer is a native (non-Java) object to which a normal object delegates via native methods. Because a native peer is not a normal object, the garbage collector doesn’t know about it and can’t reclaim it when its Java peer is reclaimed. A cleaner or finalizer may be an appropriate vehicle for this task.

How to write a cleaner

public class Room implements AutoCloseable {
    private static final Cleaner cleaner = Cleaner.create();
    // Resource that requires cleaning. Must not refer to Room!
    private static class State implements Runnable {
        int numJunkPiles; // Number of junk piles in this room
        State(int numJunkPiles) {
            this.numJunkPiles = numJunkPiles;
        }
        // Invoked by close method or cleaner
        @Override
        public void run() {
            System.out.println("Cleaning room");
            numJunkPiles = 0;
        }
    }
    // The state of this room, shared with our cleanable
    private final State state;
    // Our cleanable. Cleans the room when it’s eligible for gc
    private final Cleaner.Cleanable cleanable;
    public Room(int numJunkPiles) {
        state = new State(numJunkPiles);
        cleanable = cleaner.register(this, state);
    }
    @Override
    public void close() {
        cleanable.clean();
    }
}

State implements Runnable, and its run method is called at most once, by the Cleanable that we get when we register our State instance with our cleaner in the Room constructor.

The call to the run method will be triggered by one of two things: Usually it is triggered by a call to Room’s close method calling Cleanable’s clean method. If the client fails to call the close method by the time a Room instance is eligible for garbage collection, the cleaner will (hopefully) call State’s run method.

It is critical that a State instance does not refer to its Room instance. If it did, it would create a circularity that would prevent the Room instance from becoming eligible for garbage collection.

If clients surround all Room instantiations in try-with-resource blocks, automatic cleaning will never be required.

public class Adult {
    public static void main ( String[] args ) {}
        try (Room myRoom = new Room(7)) {
            System.out.println("Goodbye");
        } catch () {

        }
    }
}

In summary, don’t use cleaners, or in releases prior to Java 9, finalizers, except as a safety net or to terminate noncritical native resources. Even then, beware the indeterminacy and performance consequences.

1. Prefer try-with-resources to try-finally

Historically, a try-finally statement was the best way to guarantee that a resource would be closed properly, even in the face of an exception or return.

// try-finally - No longer the best way to close resources!
static String firstLineOfFile(String path) throws IOException {
    BufferedReader br = new BufferedReader(new FileReader(path));
    try {
        return br.readLine();
    } finally {
        br.close();
    }
}

However, the code in both the try block and the finally block is capable of throwing exceptions.

Java 7 introduced the try-with-resources statement. To be usable with this construct, a resource must implement the AutoCloseable interface, which consists of a single void-returning close method.

static String firstLineOfFile(String path) throws IOException {
    try (BufferedReader br = new BufferedReader(new FileReader(path))) {
       return br.readLine();
    }
}

Not only are the try-with-resources versions shorter and more readable than the originals, but they provide far better diagnostics. Multiple exceptions may be suppressed in order to preserve the exception that you actually want to see.

Chapter 3. Methods Common to All Objects¶

ALTHOUGH Object is a concrete class, it is designed primarily for extension. All of its nonfinal methods (equals, hashCode, toString, clone, and finalize) have explicit general contracts because they are designed to be overridden.

1. Obey the general contract when overriding EQUALS

The easiest way to avoid problems is not to override the equals method, in which case each instance of the class is equal only to itself. This applies when:

• Each instance of the class is inherently unique.
• There is no need for the class to provide a "logical equality" test.
• A superclass has already overridden equals, and the superclass behavior is appropriate for this class.
• The class is private or package-private, and you are certain that its equals method will never be invoked.

It is appropriate to override equals when a class has a notion of logical equality that differs from mere object identity and a superclass has not already overridden equals, generally the case for value classes.

A value class is simply a class that represents a value, such as Integer or String.

Overriding equals enables instances to serve as map keys or set elements with predictable, desirable behavior.

One kind of value class that does not require the equals method to be overridden is a class that uses instance control to ensure that at most one object exists with each value. Enum types fall into this category. For these classes, logical equality is the same as object identity, so Object’s equals method functions as a logical equals method.

equals implements an equivalence relation. It has following properties:

• Reflexive: For any non-null reference value x, x.equals(x) must return true.
• Symmetric: For any non-null reference values x and y, x.equals(y) must return true if and only if y.equals(x) returns true.
• Transitive: For any non-null reference values x, y, z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) must return true.
• Consistent: For any non-null reference values x and y, multiple invocations of x.equals(y) must consistently return true or consistently return false, provided no information used in equals comparisons is modified.
• For any non-null reference value x, x.equals(null) must return false.

Once you’ve violated the equals contract, you simply don’t know how other objects will behave when confronted with your object.

There is no way to extend an instantiable class and add a value component while preserving the equals contract, unless you’re willing to forgo the benefits of object-oriented abstraction.

While there is no satisfactory way to extend an instantiable class and add a value component, there is a fine workaround:

"Favor composition over inheritance." Instead of having ColorPoint extend Point, give ColorPoint a private Point field and a public view method that returns the point at the same position as this color point.

// Adds a value component without violating the equals contract

public class ColorPoint {
   private final Point point;
   private final Color color;
   public ColorPoint(int x, int y, Color color) {
      point = new Point(x, y);
      this.color = Objects.requireNonNull(color);
   }
   public Point asPoint() {
      return point;
   }
   @Override public boolean equals(Object o) {
      if (!(o instanceof ColorPoint))
         return false;
      ColorPoint cp = (ColorPoint) o;
      return cp.point.equals(point) && cp.color.equals(color);
   }
   ...    // Remainder omitted
}

There are some classes in the Java platform libraries that do extend an instantiable class and add a value component. For example, java.sql.Timestamp extends java.util.Date and adds a nanoseconds field. The equals implementation for Timestamp does violate symmetry and can cause erratic behavior if Timestamp and Date objects are used in the same collection or are otherwise intermixed.

Here is the recipe for a high-quality equals method:

1. Use the == operator to check if the argument is a reference to this object
2. Use the instanceof operator to check if the argument has the correct type
3. Cast the argument to the correct type
4. For each "significant" field in the class, check if that field of the argument matches the corresponding field of this object.
5. For primitive fields whose type is not float or double, use the == operator for comparisons; for object reference fields, call the equals method recursively; for float fields, use the static Float.compare(float, float) method; and for double fields, use Double.compare(double, double). The special treatment of float and double fields is made necessary by the existence of Float.NaN, -0.0f and the analogous double values
6. Some object reference fields may legitimately contain null. To avoid the possibility of a NullPointerException, check such fields for equality using the static method Objects.equals(Object, Object)
7. For best performance, you should first compare fields that are more likely to differ, less expensive to compare, or, ideally, both.
8. When you are finished writing your equals method, ask yourself three questions: Is it symmetric? Is it transitive? Is it consistent?
9. Consistent use of the @Override annotation

An excellent alternative to writing and testing these methods manually is to use Google’s open source AutoValue framework, which automatically generates these methods for you, triggered by a single annotation on the class.

1. Always override HASHCODE when you override EQUALS

If you fail to do so, your class will violate the general contract for hashCode, which will prevent it from functioning properly in collections such as HashMap and HashSet:

• When the hashCode method is invoked on an object repeatedly during an execution of an application, it must consistently return the same value
• If two objects are equal according to the equals(Object) method, then calling hashCode on the two objects must produce the same integer result
• If two objects are unequal according to the equals(Object) method, it is not required that calling hashCode on each of the objects must produce distinct results (although it helps improve performance of hash tables)

Receipe for fair good hashcode:

1. Declare an int variable named result, and initialize it to the hash code c for the first significant field in your object
2. For every remaining significant field f in your object, computer an int hash code c:
3. if the field is a primitive type, compute Type.hashCode(f)
4. if the field is an Object and this class’s equals method compares the field by recursively invoking equals, recursively invoke hashCode on the field; if a more complex comparison is required, compute a "canonical representation" for this field and invoke hashCode on the canonical representation; if the value of the field is null, use 0
5. If the field is an array, treat it as if each significant element were a separate field.
6. Do this for each hashcode c computed result = 31 * result + c;
7. return result;

Some other advices:

• If a class is immutable and the cost of computing the hash code is significant, you might consider caching the hash code in the object rather than recalculating it each time it is requested.
• Do not be tempted to exclude significant fields from the hash code computation to improve performance.
• Don’t provide a detailed specification for the value returned by hashCode, so clients can’t reasonably depend on it; this gives you the flexibility to change it.
• The AutoValue framework provides a fine alternative to writing equals and hashCode methods manually

1. Always override TOSTRING

The returned string of toString should be "a concise but informative representation that is easy for a person to read." Providing a good toString implementation makes your class much more pleasant to use and makes systems using the class easier to debug.

When practical, the toString method should return all of the interesting information contained in the object.

It is recommended to specify the format of the return value for value classes. If you specify the format, it’s usually a good idea to also provide a matching static factory or constructor so programmers can easily translate back and forth between the object and its string representation.

Whether or not you decide to specify the format, you should clearly document your intentions.

Whether or not you specify the format, provide programmatic access to the information contained in the value returned by toString.

It makes no sense to write a toString method in a static utility class. Nor should you write a toString method in most enum types because Java provides a perfectly good one for you. You should, however, write a toString method in any abstract class whose subclasses share a common string representation.

1. Override CLONE with Causion

The Cloneable interface determines the behavior of Object’s protected clone implementation: if a class implements Cloneable, Object’s clone method returns a field-by-field copy of the object; otherwise it throws CloneNotSupportedException.

Normally, implementing an interface says something about what a class can do for its clients. In this case, it modifies the behavior of a protected method on a superclass, which is very rare.

A class implementing Cloneable is expected to provide a properly functioning public clone method.

Note that immutable classes should never provide a clone method because it would merely encourage wasteful copying.

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

In effect, the clone method functions as a constructor; you must ensure that it does no harm to the original object and that it properly establishes invariants on the clone.

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

In order to make a class cloneable, it may be necessary to remove final modifiers from some fields.

Java supports covariant return types. In other words, an overriding method’s return type can be a subclass of the overridden method’s return type.

In effect, the clone method functions as a constructor; you must ensure that it does no harm to the original object and that it properly establishes invariants on the clone.

Public clone methods should omit the throws clause, as methods that don’t throw checked exceptions are easier to use.

To prevent a subclass from implementing a working clone method,

@Override
protected final Object clone() throws CloneNotSupportedException {
  throw new CloneNotSupportedException();
}

If you write a thread-safe class that implements Cloneable, remember that its clone method must be properly synchronized, just like any other method.

A better approach to object copying is to provide a copy constructor or copy factory. A copy constructor is simply a constructor (or static method) that takes a single argument whose type is the class containing the constructor.

1. Consider Implementing COMPARABLE

It is the sole method in the Comparable interface but it permits order comparisons in addition to simple equality comparisons, and it is generic. By implementing Comparable, a class indicates that its instances have a natural ordering. Sorting an array of objects that implement Comparable is as simple as this: Arrays.sort(a);

Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object. Throws ClassCastException if the specified object’s type prevents it from being compared to this object.

• The implementor must ensure that sgn(x.compareTo(y)) == -sgn(y. compareTo(x)) for all x and y. (This implies that x.compareTo(y) must throw an exception if and only if y.compareTo(x) throws an exception.)
• The implementor must also ensure that the relation is transitive: (x. compareTo(y) > 0 && y.compareTo(z) > 0) implies x.compareTo(z) > 0.
• Finally, the implementor must ensure that x.compareTo(y) == 0 implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for all z.
• It is strongly recommended, but not required, that (x.compareTo(y) == 0) == (x.equals(y))

In Java 7, static compare methods were added to all of Java’s boxed primitive classes. Use of the relational operators < and > in compareTo methods is verbose and error-prone and no longer recommended.

If a class has multiple significant fields, the order in which you compare them is critical. Start with the most significant field and work your way down. If a comparison results in anything other than zero (which represents equality), you’re done.

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

In Java 8, the Comparator interface was outfitted with a set of comparator construction methods, which enable fluent construction of comparators. These comparators can then be used to implement a compareTo method

private static final Comparator<PhoneNumber> COMPARATOR =
    comparingInt((PhoneNumber pn) -> pn.areaCode)
      .thenComparingInt(pn -> pn.prefix)
      .thenComparingInt(pn -> pn.lineNum);
public int compareTo(PhoneNumber pn) {
    return COMPARATOR.compare(this, pn);
}
// alternative
static Comparator<PhoneNumber> hashCodeOrder = new Comparator<>() {
    public int compare(PhoneNumber o1, PhoneNumber o2) {
        int result =  Short.compare(areaCode, o2.areaCode);
        if (result == 0)  {
            result = Short.compare(prefix, pn.prefix);
            if (result == 0)
                result = Short.compare(lineNum, pn.lineNum);
        }
        return result;
    }
};

The method comparingInt is a static method that takes a key extractor function that maps an object reference to a key of type int and returns a comparator that orders instances according to that key.

The method thenComparingInt is an instance method on Comparator that takes an int key extractor function, and returns a comparator that first applies the original comparator and then uses the extracted key to break ties.

Classes implement the Comparable interface produce instances that can be easily sorted, searched, and used in comparison-based collections. When comparing field values in the implementations of the compareTo methods, avoid the use of the < and > operators. Instead, use the static compare methods in the boxed primitive classes or the comparator construction methods in the Comparator interface.

Chapter 4 Classes and Interfaces¶

CLASSES and interfaces lie at the heart of the Java programming language. They are its basic units of abstraction.

15: Minimize the accessibility of classes and members

A well-designed component hides all its implementation details, cleanly separating its API from its implementation. This concept, known as information hiding or encapsulation, is a fundamental tenet of software design that it decouples the components that comprise a system, allowing them to be developed, tested, optimized, used, understood, and modified in isolation.

The rule of thumb is simple: make each class or member as inaccessible as possible.

For top-level (non-nested) classes and interfaces, there are only two possible access levels: package-private and public. - By making it package-private, you make it part of the implementation rather than the exported API, and you can modify it, replace it, or eliminate it in a subsequent release without fear of harming existing clients. - If you make it public, you are obligated to support it forever to maintain compatibility. - If a package-private top-level class or interface is used by only one class, consider making the top-level class a private static nested class of the sole class that uses it. - If a method overrides a superclass method, it cannot have a more restrictive access level in the subclass than in the superclass. - Instance fields of public classes should rarely be public; classes with public mutable fields are not generally thread-safe. - It is wrong for a class to have a public static final array field, or an accessor that returns such a field, since clients will be able to modify the contents of the array.

Access levels:

• private—The member is accessible only from the top-level class where it is declared.
• package-private—The member is accessible from any class in the package where it is declared. Technically known as default access, this is the access level you get if no access modifier is specified (except for interface members, which are public by default).
• protected—The member is accessible from subclasses of the class where it is declared (subject to a few restrictions [JLS, 6.6.2]) and from any class in the package where it is declared.
• public—The member is accessible from anywhere.

As of Java 9, there are two additional, implicit access levels introduced as part of the module system.

• A module is a grouping of packages, like a package is a grouping of classes.
• A module may explicitly export some of its packages via export declarations in its module declaration.
• A module may explicitly export some of its packages via export declarations in its module declaration (which is by convention contained in a source file named module-info.java).
• Public and protected members of unexported packages in a module are inaccessible outside the module; within the module, accessibility is unaffected by export declarations.
• Using the module system allows you to share classes among packages within a module without making them visible to the entire world.

After carefully designing a minimal public API, you should prevent any stray classes, interfaces, or members from becoming part of the API. With the exception of public static final fields, which serve as constants, public classes should have no public fields. Ensure that objects referenced by public static final fields are immutable.

16: In public classes, use accessor methods, not public fields

if a class is accessible outside its package, provide accessor methods to preserve the flexibility to change the class’s internal representation.

if a class is package-private or is a private nested class, there is nothing inherently wrong with exposing its data fields, assuming they do an adequate job of describing the abstraction provided by the class.

Public classes should never expose mutable fields. It is less harmful, though still questionable, for public classes to expose immutable fields. It is, however, sometimes desirable for package-private or private nested classes to expose fields, whether mutable or immutable.

17: Minimize mutability

Immutable classes are easier to design, implement, and use than mutable classes. They are less prone to error and are more secure.

Five rules of thumb to make a class immutable:

1. Don’t provide methods that modify the object’s state (known as mutators).
2. Ensure that the class can’t be extended by making the class final.
3. Make all fields final.
4. Make all fields private.
5. Ensure exclusive access to any mutable components.

Immutable objects are simple and inherently thread-safe; they require no synchronization and can be shared freely. Immutable objects provide failure atomicity for free; their state never changes, so there is no possibility of a temporary inconsistency.

The major disadvantage of immutable classes is that they require a separate object for each distinct value.

public class Complex {
    private final double re;
    private final double im;
    private Complex(double re, double im) {
        this.re = re;
        this.im = im;
    }
    public static Complex valueOf(double re, double im) {
      // sanity checks here
        return new Complex(re, im);
    }
    ... // Remainder unchanged
}

If you choose to have your immutable class implement Serializable and it contains one or more fields that refer to mutable objects, you must provide an explicit readObject or readResolve method, or use the ObjectOutputStream.writeUnshared and ObjectInputStream.readUnshared methods.

Constructors should create fully initialized objects with all of their invariants established.

18: Favor composition over inheritance

Unlike method invocation, inheritance violates encapsulation. A subclass depends on the implementation details of its superclass for its proper function. The superclass’s implementation may change from release to release, and if it does, the subclass may break, even though its code has not been touched.

One caveat is that wrapper classes are not suited for use in callback frameworks, wherein objects pass self-references to other objects for subsequent invocations ("callbacks").

Because a wrapped object doesn’t know of its wrapper, it passes a reference to itself (this) and callbacks elude the wrapper. This is known as the SELF problem.

Inheritance is appropriate only when a genuine subtype relationship exists between the subclass and the superclass.

Even then, inheritance may lead to fragility if the subclass is in a different package from the superclass and the superclass is not designed for inheritance.

Use composition and forwarding instead of inheritance, especially if an appropriate interface to implement a wrapper class exists.

19: Design and document for inheritance or else prohibit it

What does it mean for a class to be designed and documented for inheritance?

• A class must document its self-use of overridable methods.
• A class may have to provide hooks into its internal workings in the form of judiciously chosen protected methods or, in rare instances, protected fields.
• Constructors must not invoke overridable methods
• Designing a class for inheritance requires great effort and places substantial limitations on the class.

20: Prefer interfaces to abstract classes

Here is why:

• To implement the type defined by an abstract class, a class must be a subclass of the abstract class. Not for interfaces.
• Existing classes can easily be retrofitted to implement a new interface.
• Interfaces are ideal for defining mixins. A mixin is a type that a class can implement in addition to its "primary type," to declare that it provides some optional behavior. It is called a mixin because it allows the optional functionality to be "mixed in" to the type’s primary functionality.
• Interfaces allow for the construction of nonhierarchical type frameworks. Type hierarchies are great for organizing some things, but other things don’t fall neatly into a rigid hierarchy.
  • i.e. class Singer and class SongWriter. A singer can also be a songwriter. A class can implement both Singer and SongWriter, but not extending both if they are abstract classes.
• Interfaces enable safe, powerful functionality enhancements via the wrapper class idiom

An interface is generally the best way to define a type that permits multiple implementations. If you export a nontrivial interface, you should strongly consider providing a skeletal implementation to go with it. To the extent possible, you should provide the skeletal implementation via default method.

21: Design interfaces for posterity

In Java 8, the default method construct was added, with the intent of allowing the addition of methods to existing interfaces. Default methods are "injected" into existing implementations without the knowledge or consent of their implementors.

It is not always possible to write a default method that maintains all invariants of every conceivable implementation.

22: Use interfaces only to define types

When a class implements an interface, the interface serves as a type that can be used to refer to instances of the class.

The constant interface pattern is a poor use of interfaces. Avoid making interfaces for the sake of defining constants.

23: Prefer class hierarchies to tagged classes

Occasionally you may run across a class whose instances come in two or more flavors and contain a tag field indicating the flavor of the instance.

In short, tagged classes are verbose, error-prone, and inefficient.

A tagged class is just a pallid imitation of a class hierarchy.

If you’re tempted to write a class with an explicit tag field, think about whether the tag could be eliminated and the class replaced by a hierarchy.

24: Favor static member classes over nonstatic

A nested class should exist only to serve its enclosing class. If a nested class would be useful in some other context, then it should be a top-level class.

There are four kinds of nested classes: static member classes, nonstatic member classes, anonymous classes, and local classes. All but the first kind are known as inner classes.

One common use of a static member class is as a public helper class, useful only in conjunction with its outer class.

Despite the syntactic similarity, static member classes and nonstatic member classes are very different. Each instance of a nonstatic member class is implicitly associated with an enclosing instance of its containing class.

If an instance of a nested class can exist in isolation from an instance of its enclosing class, then the nested class must be a static member class: it is impossible to create an instance of a nonstatic member class without an enclosing instance.

If you declare a member class that does not require access to an enclosing instance, always put the static modifier in its declaration

A common use of private static member classes is to represent components of the object represented by their enclosing class. i.e. many Map implementations have an internal Entry object for each key-value pair in the map.

There are many limitations on the applicability of anonymous classes. You can’t instantiate them except at the point they’re declared. You can’t perform instanceof tests or do anything else that requires you to name the class. You can’t declare an anonymous class to implement multiple interfaces or to extend a class and implement an interface at the same time. Clients of an anonymous class can’t invoke any members except those it inherits from its supertype. Because anonymous classes occur in the midst of expressions, they must be kept short—about ten lines or fewer—or readability will suffer.

If a nested class needs to be visible outside of a single method or is too long to fit comfortably inside a method, use a member class. If each instance of a member class needs a reference to its enclosing instance, make it nonstatic; otherwise, make it static. Assuming the class belongs inside a method, if you need to create instances from only one location and there is a preexisting type that characterizes the class, make it an anonymous class; otherwise, make it a local class.

25: Limit source files to a single top-level class

Never put multiple top-level classes or interfaces in a single source file. Keep each source file one class (nested classes are okay to have).

Chapter 5. Generics¶

With generics, you tell the compiler what types of objects are permitted in each collection. This results in programs that are both safer and clearer, but these benefits, which are not limited to collections, come at a price.

26: Don’t use raw types

A class or interface whose declaration has one or more type parameters is a generic class or interface. Generic classes and interfaces are collectively known as generic types.

Each generic type defines a set of parameterized types, i.e. E in List.

Each generic type defines a raw type, which is the name of the generic type used without any accompanying type parameters. i.e. List is a raw type for List.

If you use raw types, you lose all the safety and expressiveness benefits of generics. But it is fine to use types that are parameterized to allow insertion of arbitrary objects, such as List