View on GitHub

effective-java-3rd-edition

Effective Java 3rd Edition Notes

Effective Java - 3rd Edition Notes

Chapter Index

Chapter 02 - Creating and Destroying Objects

Item 1 - Consider static factory methods instead of constructors

traditional vs. flexible way of object instantiation

example of static factory method:

public static Boolean valueOf(boolean b) {
  return b ? Boolean.TRUE : Boolean.FALSE;
}

Advantages and disadvantages:

(PRO) static factories have names, unlike constructors
(PRO) static factories are not required to create a new object on each invocation
such classes are called instance controlled
- enable singleton (Item 2) and non-instantiability (Item 3) guarantees
- allows immutable value class to guarantee no two instances exist
- forms the basis of Flyweight Pattern
- Enum types provide this guarantee
(PRO) static methods can return an object of any subtype of their return type, unlike constructors
this can lead to compact APIs
lends itself to interface-based frameworks (Item 20)
companion classes mostly obviated in Java 8
- default methods
- still some limitations which are dealt with in Java 9+
(PRO) static factories allow the class of the returned object to vary from call to call as function of input params
example: EnumSet
- backed by a long - RegularEnumSet
- backed by a long[] - JumboEnumSet
(PRO) static factories do not require the class of returned object to exist when the class containing the method is written
form the basis of service provider frameworks
example: JDBC
variants:
- dependency-injection frameworks (i.e. Spring, Guice)
- Bridge Pattern
(CON) classes without public/protected constructors cannot be subclassed
a blessing in disguise
- encourages composition over inheritance
(CON) hard to find in documentation
current JavaDoc limitations

Some common names for static factory methods

from()
of()
valueOf()
instance() or getInstance()
getType()
newType()
type()

Conclusion

Avoid the reflex to provide a public constructor and consider static methods/factories.

Item 2 - Consider a builder when faced with many constructor params

static factories and constructors share a limitation: they scale poorly with the increase of (optional) params
traditional ways of dealing with this:
- telescoping constructor
  - also scales poorly: hard to write with many params and even harder to read
- JavaBeans pattern
  - allows inconsistency
  - precludes immutability (Item 17)
a better way: Builder pattern
- typically a static member class (Item 24)
- the client code is easy to write and, more importantly, easy to read
- easy to incorporate validity checks
  - check on object fields after copying params from the builder (Item 50)
  - failing check will throw an IllegalArgumentException (Item 72) with exception details (Item 75)
- well suited to class hierarchies
  - generic builder with recursive type parameters (Item 30) can construct any subclass
  - abstract self() simulates self-type which, combined with covariant return typing, obviates need for casting
- flexible
disadvantages:
- cost of creating a builder
- more verbose than a telescoping constructor
conclusion:
- almost always start with a builder in the first place
  - especially so if we have more than a handful params
  - client code much easier to read and write than telescoping constructors
  - builder are much safer than JavaBeans

Item 3 - Enforce the singleton property when a private constructor or enum type

singleton is a class that is instantiated exactly once
making a class a singleton can make it difficult to test
three common ways of implementing it:
- with public final field
- with static factory
- with a single-element enum (preferred)
conclusion:
- if a singleton is indeed warranted, create it as a single-element enum
  - well-defended against reflection
  - solves serialization problems

Item 4 - Enforce non-instantiability with a private constructor

occasionally, we want to write a class that is simply a grouping of static methods and static fields
such utility classes have acquired a bad reputation due to their abuse in avoiding thinking in terms of objects but they have valid uses:
- group related methods on primitive values or arrays
  - examples: java.util.Math or java.util.Arrays
- group static methods, including factories (Item 1)
  - default methods are also available (providing we own the interface)
- group methods on a final class, since we can’t put them in a subclass
make such classes non-instantiable
- provide an explanatory comment
- throw an AssertionError from constructor instead of empty one, to guard against accidental constructions from within the class
- as a side-effect, this class is now effectively final
  - the class cannot be subclassed as there are no available constructors
  - still, it is good to document this a make the class itself final

Item 5 - Prefer dependency injection to hard-wiring resources

do not use static utility methods or singletons to handle creations of class’ resources
- these yield inflexible and untestable classes
favour dependency injection by supplying the required resource parametrically
- we inject (pass) the dependency (resource) into the class that requires it
- testable
- flexible (esp. with Factory Method pattern)
  - Supplier<T> is perfectly suited for representing factories
  - methods that take this interface should typically constrain the factory’s type parameter with a bounded wildcard type (Item 31)
    - the client should be able to pass in a factory that requires any subtype of a specified type
the manual dependency injection can be automatised with frameworks

Item 6 - Avoid creating unnecessary objects

creating unnecessary objects can be avoided by using static factory methods (Item 1)
some object creations are much more expensive than others
- it may be advisable to cache such objects
- example: regex matching
immutable objects can trivially be reused
other examples are Adapters (a.k.a. views)
- adapter is an object delegating to a backing object, providing an alternative interface
- has not state beyond the backing object thus provides a view of it
- example: keySet() in Map interface
autoboxing can often subtly create unnecessary objects
almost never create own object pools
- JVM gc will almost always outperform such pools
- exception to this: very expensive objects
  - example: database connection objects
counterpoint to this is defencive copying (Item 50)

Item 7 - Eliminate obsolete object references

when relying on automatic gc, be wary of leaks
- example: a resizing-array stack that doesn’t null out its references on pop()
common sources of leaks
- classes that manage their own memory
- caches
  - can be mitigated with WeakHashMap
  - sophisticated caches might need to use java.lang.ref directly
- listeners and other callbacks
  - APIs that register callbacks but don’t deregister them explicitly
  - can be mitigated with WeakHashMap
conclusion: it very desirable to learn to anticipate such problems before they occur as they can be very costly to fix

Item 8 - Avoid finalizers and cleaners

finalizers and cleaners are used to reclaim non-memory resources
- example: input/output streams, files, etc.
- they are not analogues of C++ destructors
finalizers are unpredictable, dangerous and generally unnecessary
cleaners are less dangerous than finalizers but still slow, unpredicatble and generally unnecessary
disadvantages:
- spec makes no guarantee when they’ll be executed
  - their execution is a function of GC algorithm, thus JVM implementation
  - never do anything time-critical in a finalizer or cleaner
  - providing a finalizer may arbitrarily delay reclamation of class’ instances
  - cleaners are a bit better but still run under the control of GC so still the same applies
  - any existing methods that claim to trigger finalization are decade-old traps
    - examples: System.runFinalizerOnExit or Runtim.runFinalizerOnExit
- uncaught exception thrown during finalization is ignored and finalization of that object terminates
  - object is potentially left in corrupted state
  - normally, uncaught exception terminates the executing thread and dumps stacktrace but not if it occurs in finalizer
  - cleaners do not suffer from this problem
- there is a severe performance GC penalty for using finalizers and cleaners
  - finalizers: ~50x slower reclamation
  - cleaners: ~5x slower reclamation, equal to finalizers if they’re used to clean all instance of the class
- finalizers open up classes to finalizer attacks
  - if an exception is thrown during finalization, the finalizer leaves the class unreclaimed
  - attackers can exploit this and run code that shouldnt’ve existed
  - to protect non-final classes against it - write a final finalize() that does nothing
instead of using finalizers or classes simply use AutoCloseable
- require clients to invoke close() whenever instance is not required
legitimate uses:
- act as a safety net for closeables
  - think long and hard before doing so
- reclaim native peer objects
conclusion: don’t use cleaners, or in releases prior to Java 9, finalizers - except as a safety net or to terminate non-critical native resources. Even then, beware the indeterminacy and performance consequences

Item 9 - Prefer `try-with-resources` to `try-finally`

Java libraries include many resources that must be closed manually by invoking close()
- examples: InputStream, OutputStream, java.sql.Connection, etc.
closing objects is often overlooked by clients
many use finalizers as safety net, with dire performance consequences (Item 8)
historically, try-finally was the best way to guarantee a resource would be closed properly, even when facing exception or return
- while it doesn’t look bad for a single resource, it doesn’t scale well with the increase of resources required to be closed
  - nested try-finally blocks stick out like a sore thumb
- it’s tricky to get it right, even in JDK
- nested finally block complicate debugging

try-with-resources suffers none of this issues

example:

  // try-with-resources on multiple resources - short and sweet
  static void copy(String src, String dst) throws IOException {
  try (InputStream in = new FileInputStream(src);
       OutputStream out = new FileOutputStream(dst)) {
       byte[] buf = new byte[BUFFER_SIZE];
       int n;
       while ((n = in.read(buf)) >= 0)
       out.write(buf, 0, n);
       }
  } catch (IOException e) {
       // do something here
  }

shorter, more readable than try-finally
provides far better diagnostics
- no exceptions are suppressed

conclusion: always use try-with-resources when working with resources that must be closed

Chapter 03 - Methods Common to All Objects

Item 10 - Obey the general contract when overriding `equals()`

overriding the equals() seems simple but there are many pitfalls and consequences can be dire
easiest way to avoid problems is not override the method at all
- then, we fall back to object identity only - each object is equal only to itself
do not override the method if:
- each instance of the class is inherently unique
  - example: java.util.thread.Thread
- there is no need for the class to provide ‘logical equality’ test
  - example: java.util.regex.Pattern
- superclass is already overriding equals() and superclass’ behaviour is appropriate for the subclass
  - example: most root classes from java.util.collection and subclasses of java.util.Map inherit equals() behaviour from their abstract implementations
- the class is (package-)private and we’re certain equals() will never be invoked
  - the risk-averse may throw an exception in the subclass if equals() is called
- the class is instance controlled (Item 1)
  - example: enum types
do override the method if a class has a notion of logical equality that differs from mere object identity
- this is generally the case for value classes
- examples: java.util.Integer or java.util.String
overriding the equals() implies adhering to its general contract of equivalence relation:
- (reflexivity) x.equals(x) == true, for x != null
  - hard to violate unintentionally
- (symmetry) x.equals(y) == y.equals(x), for x, y != null
  - example: compare ordinary and case insensitive strings
- (transitivity) x.equals(y) == y.equals(z) == x.equals(z), for x, y, z != null
  - examples: subclass adds a new value component; java.util.Date and java.util.Timestamp
  - easier to violate when using inheritance
  - once this property is violated, subsequent fixes are likely to violate other properties
  - fundamental problem of equivalence relations in OO languages => there is no way to extend an instantiable class and add a value component whilst preserving the relation!
  - workaround: favour composition over inheritance
- (consistency) x.equals(y) == x.equals(y), for x, y != null
  - example: ‘java.util.URL’
  - do not write equals() that depend on unreliable resources
- (non-nullity) x.equals(null) == false, for x != null
  - hard to violate unintenionally, unless an exception is thrown instead of returning false
violation of this contract means it is uncertain how other objects will behave when confronted with our object
conclusions:
- rely on IDEs to generate the equals()
- if manual tuning is really necessary, pay attention to equivalence relation violation (write tests!) and performance

Item 11 - Always override `hashCode()` when overriding `equals()`

violating this rule will violate the general contract for hashCode()
- it prevents proper functioning of hash-based collections
general hashCode() contract:
- (consistency) x.hashCode() == x.hashCode(), for x != null
- (equality) x.equals(y) => (x.hashCode() == y.hashCode()), for x, y != null
worst possible hash-code implementation is returning the same number
- degrades performance horrifically
conclusions:
- it is mandatory to override hashCode() each time equals() is overridden
  - failure to do so precludes correct functioning of the program (fallback on Object)
- obey the general hashCode() contract
- rely on the Object.hashCode(...) to compute the hash-code unless performance is very important

Item 12 - Always override `toString()`

makes systems using the class easier to debug
- disadvantage: once specified, it’s for-life
clearly document intentions
don’t override toString() on
- static utility class (Item 4)
- enum types (Item 34)
rely on IDE to create a good toString() implementation

Item 13 - Override `clone()` judiciously

conclusions:
- do not use clone()
- use static factory to copy objects whenever possible

Item 14 - Consider implementing `Comparable`

isn’t inherited from Object type
located in functional interface Comparable
similar to equals() except it permits order comparisons in addition to simple equality comparisons
implementing Comparable, class indicates its instances follow natural ordering
it also makes it easy to apply various searching, sorting and extreme values computations on such a class
- example: java.util.String
- class automatically interoperates with a variety of generic algorithms and collection implementations
- small effort and code footprint to leverage existing (vast) capabilites
general contract of compareTo() is very similar to equals:
- (reflexivity) (x.compareTo(y) == 0) => (sgn(x.compareTo(z) == sgn(y.compareTo(z)), for x, y, z != null
- (symmetry) sgn(x.compareTo(y)) == -sgn(y.compareTo(x)), for x, y != null
  - helps imposing total order
- (transitivity) (x.compareTo(y) && y.compareTo(z)) > 0 => (x.compareTo(z)) > 0, for x, y, z != null
  - helps imposing total order
- (optional consistency with equals) (x.compareTo(y) == 0) <=> (x.equals(y)), for x, y != null
  - if violated, still will yield valid comparisons but will generally not guarantee obeying the general contract for collections and maps
  - examples: java.util.BigDecimal in HashSet and TreeSet
to compare object ref fields, invoke compareTo() recursively
do not use relational operators in compareTo()
- use compare() on boxed primitive types
- alternately, use comparator fluent construction methods in Comparator interface
do not use hashCode arithmetics-based comparisons
- though somewhat more performant, they are fraught with danger from integer overflow and FP arithmetic artifacts
- use the same techniques as in the bullet point above
generally, same limitations and workarounds as for the equals() apply here
- exceptions may be thrown, however, without violating the contract
conclusions:
- whenever a value class has sensible ordering, Comparable should be implemented
  - easy sorting, searching and usage in comparison-based collections
- do not use relational comparison operators to determine the result of comparing two elements
  - rely on static compare() in the boxed primitive types
  - alternately, use comparator construction methods in Comparator interface

Chapter 04 - Classes and Interfaces

Item 15 - Minimise the accesibility of classes and members

well-designed components:
- hide their internal data and other implementation details from other components
- thus, they cleanly separate their API from its implementation
- components are then oblivios to each other’s workings
- this is encapsulation (information hiding) -> a fundamental tenet of software design
importance of encapsulation:
- decouples the components comprising a system
- this allows for development/optimisation/usage/reasoning/modification in isolation
  - speeds up development (parallelisation)
  - reduces maintenance costs (easier reasoning/debugging/replacement)
  - makes for effective performance tuning (isolation -> does not influence correctness of others)
  - increases reuse (decoupled components usually provide use in contexts beyond original design)
  - de-risks development (individual components may prove successful even if the system does not)
Java encapsulation facilities:
- access control mechanism (private, protected, public keywords + default access)
encapsulation rule of thumb: make each class/member as inaccessible as possible
- after carefully designing a class’ public API, the reflex should be to make all other members private
- change design if you find yourself opening up the API too frequently
  - there may be a better decomposition with higher decoupling
- some fields may leak into the exported API if the class implements Serializable interface
huge increase in visibility when going from default to protected
- becomes a part of exported API (has to be supported forever)
- should be relatively rare
overridden methods cannot have restrictive access level in the subclass than it is in the superclass
- fields a compile-time error
- a consequence of Liskov substition principle
- special rule -> if a class implements an interface, all implemented methods must be public
opening up a class to facilitate testing is acceptable (to a degree)
- the less restrictive access must not be any higher than default access
- it is fine to make the code “worse” in order to cover it with tests (M. Feathers, “Working Effectively With Legacy Code”)
instance fields of public classes should rarely be public
- gives up :
  - the ability to enforce invariants on the field
  - the flexibility to change data structure
- not thread-safe
- same applies for static fields, except if they are also final
  - exception: it’s always wrong to expose a mutable data structure as public static final (e.g. Arrays, Lists…)
  - for such instances make an accessor which defencively copies the data structure and make the field private
Java 9 modules:
- module is a group of packages, much like a pakcage is group of classes
- it may explicitly export some of its packages (via export declarations in its module declaration module-info.java)
- public/protected members of unexported packages in a module are inaccessible outside the module
  - within, they work as before
- using the module system allows us to share classes among packages within a module without making them visible to the entire world
- the need for this kind of sharing is relatively rar and can often be eliminated by rearranging classes within a package
- it is unclear if it will achieve widespread use outside of the JDK itself (where it’s strictly enforced)
summary:
- reduce accebility of program elements as much as possible
- do not expose mutable types as public static final fields

Item 16 - Favour accessors over public fields in public classes

occasionaly, degenerate classes are rolled out such as this one:

class Point {
  public double x;
  public double y
}

if confined to package-private or private access modifier, they can be very useful in reducing visual clutter and overhead
- making them more accessible would be dangerous and is not advised
  - there are examples in JDK that violate this rule (java.awt.Point, java.awt.Dimension)

Item 17 - Minimise mutability

immutable classes are classes whose instances cannot be modified
- all of the data in the object is fixed for the lifetime of the object
- e.g. java.lang.String, the boxed primitive classes, BigInteger and BigDecimal
many reasons to use immutable classes -> easier to design, implement and use than mutable classes
to make a class mutable, follow these 5 rules:
- don’t provide mutators
- ensure that the class cannot be extended
- make all fields final
- make all fields private
- ensure exclusive access to any mutable components
immutable classes are easier to realise using functional, rather than imperative approach
immutable objects are simple
- has always exactly one state - the state in which it was created
- they are easier to use reliably
immutable object are inherently thread-safe (they require no synchronisation)
- thus can be shared freely, promoting reuse
- no defencive copies necessary
- their internals can be shared freely
immutable objects make great building blocks for other objects
- they also make great map keys or set elements
immutable object provide atomicity for free
the one disadvantage -> they require a separate object for each distinct value
- the problem is exacerbated if the object is a part of multistep transformation
- one way to solve this issue is by providing mutable ‘companion classes’
no method may produce an externally visible change in the object’s state
- consider using lazy initialisation technique
summary:
- classes should be immutable unless there is a very good reason to make them mutable
- if a class cannot be made immutable, limit its mutability as much as possible
  - declare every field private final unless there is a good reason to do so otherwise
constructors should create fully initialised objects with all their invariants established
- e.g. CountDownLatch

Item 18 - Favour composition over inheritance

this chapter applies to implementation inheritance, not interface inheritance
inheritance is a powerful way to achieve code reuse
can lead to fragile software if employed inappropriately
safe to use:
- within a package (where sub- and super-class are under control of the same programmers)
- if a class specifically is designed and documented for inheritance
inheritance violates encapsulation
- subclass depends on implementation details of the superclass
- both must evolve in tandem
- e.g. HashSet extension
  - depending on superclass’ method to implement your own can lead to fragility - as the superclass evolves, your code may break without any changes
- related cause of fragility is that their superclass can acquire new methods in subsequent releases
  - e.g. Hashtable and Vector classes had to had their security holes fixed before being retrofitted to participate in Collections framework
solution to these issues is the application of composition
- existing class becomes a component of the new one
- new class is free to forward calls to the old class where appropriate (forwarding methods)
- resulting classes are then rock solid:
  - they don’t depend on the implementation details of the existing class
- the forwarder-wrapper pattern is also known as the Decorator pattern
  - this combination of composition and forwarding is also informally defined as delegation
- disadvantages of wrapper classes are few:
  - not suited for use in callback frameworks (callbacks elude the wrapper - SELF problem)
  - theoretical performance and memory impacts
  - tedious to write forwarding classes
inheritance is only appropriate for classes that pass the “is-a” test
- answer truthfully to question “If B extended A, is B really an A?”
- a number of obvious violations in JDK
  - Stack extends Vector
  - Properties extends Hashtable
does the class contemplated to extends has any flaws in its API?
summary:
- inheritance is powerful but problematic as it violates encapsulation
- appropriate only when a genuine subtype relationship exists between the sub- and super-class
- inheritance may lead to fragility
  - use composition and forwarding instead to avoid this fragility
  - wrapper classes are more robust and powerful than subclasses

Item 19 - Design and document for inheritance or else prohibit it

what does it mean to design/document for inheritance?
- the class must document its self-use of overridable methods
  - this is one special case where it’s ok to document implementation detail (unfortunate side-effect of inheritance violating encapsulation)
- the class may have to provide hooks into its internal workings
  - careful choosing of protected methods
  - enables programmers to write efficient subclasses without undue pain
- the only way to test a class designed for inheritance is to write subclasses
  - test before releasing the class
- constructors must not invoke overridable methods (directly or indirectly)
  - safe to invoke private/final/static methods, none of which are overridable
- Cloneable or Serializable interfaces are especially difficult to design for inheritance
  - use neither in such classes
designing a class for inheritance requires great effort and places substantial limitations on the class
- occasionaly, it is clearly the right thing to do (e.g. abstract classes, interfaces or skeletal implementations)
- the opposite also holds (e.g. immutable classes)
best approach is to prohibit subclassing in classes that are not designed and documented for safe subclassing
- prohibit inheritance on classes implementing an interface that captures its essence
- for other classes, ensure at least that the class never invokes any of its overridable methods and document this
summary:
- designing a class for inheritance is hard
- document all self-use patterns
- export one or more protected methods
- strongly consider prohibiting inheritance altogether

Item 20 - Prefer interfaces to abstract classes

two mechanisms to define a type that permits multiple implementations: interfaces and abstract classes
existing classes can easily be retrofitted to implement a new interface
- they cannot, in general, be retrofitted with a new abstract class without doing collateral damage to the type hierarchy
interfaces are ideal for defining mixins
- a mixin is a type thtat a class implements additionally to its ‘primary type’
  - e.g. Comparable
- abstract classes cannot be used to define mixins
interfaces allow for the construction of non-hierarchical type frameworks
- they can prevent combinatorial explosion produced by abstract classes
interfaces enable safe, powerful functionality enhancements
- wrapper class idiom