Effective Java (First Edition) Companion

Consider providing static factory methods instead of constructors.

This technique has both advantages and disadvantages. To favor composition over inheritance though, having static factory methods is advisable.

Advantages:

• Factory methods have names and as such they can be more expressive. Limitations of method overloading can be eliminated by explicitly named methods. Constructors don't enjoy that freedom.
• They don't have to return a new instance of the class unlike constructors.
• They can return an instance of any (even nonpublic) subtype of a given type. This facilitates the backing-store-reuse or view pattern and promotes interface-based frameworks (e.g. Java Collections Framework).

Disadvantages:

• It favors composition over inheritance as a class can't be subclassed if it does not have a non-private constructor.
• Usually a naming convention has to be followed if these methods have to stand out as factory methods. The current conventions are: getInstance() and valueOf(SomeOtherType).

Enforce the singleton property with a private constructor.

The topic of Singletons is under scrutiny by developer community. It's clearly an overused pattern. Developers should think hard to justify the need for Singletons. It has somehow become a deplorable norm to create Singletons without justification and at times implement them incorrectly.

But first, the following discusses two ways of implementing Singletons correctly (under normal circumstances) should the need for them be justified:

First: This is correct, straightforward and should generally be employed.

public class MySingleton {
  private static final MySingleton INSTANCE = new MySingleton();
  /*essential to make this private*/
  private MySingleton() {
    // this can possibly delay class loading, but that's OK
  }
  public static getInstance() {
    return INSTANCE;
  }
  // implement readResolve() method if this class needs to be Serializable
}

Second:

public class MySingleton {
  private static MySingleton INSTANCE = null;
  /*essential to make this private*/
  private MySingleton() {
    // this can possibly delay class loading, but that's OK
  }
  public synchronized static getInstance() {
    // this results in lock contention, but it is correct
    if (INSTANCE == null) {
      INSTANCE = new MySingleton();
    }
    return INSTANCE;
  }
  // implement readResolve() method if this class needs to be Serializable
}

There are other techniques like lazy initialization, but you have to be extremely careful with them. The first technique above is by far the best way of defining Singletons.

Few good references on this topic:

• Article from IBM DeveloperWorks
• Wikipedia Entry

Never be over-smart with implementing something as trivial as correct Singleton pattern. This results in insidious issues with thread safety of your program because of the so-called broken Double-checked locking idiom:

//Don't Do This
public class OverSmart { 
  private OverSmart os = null;
  public OverSmart getInstance() {
    if (os == null) {
      synchronized(this) {
        if (os == null) {
          os = new OverSmart();
        }    
      }    
    }    
    return os;
  }
 
  // other members...
}

Enforce noninstantiability with a private constructor.

A class can be made noninstantiable only by providing a single explicit private constructor. Note that noninstantiability of a class can't be guaranteed by making it abstract.

Another technique I have seen is to create a parameterless public constructor that throws a RuntimeException. But this is not an effective code pattern because it does not make the intent of the programmer explicit.

For API or library designers, it is a good idea to make a class noninstantiable if it is a mere collection of utility static methods.

 //Don't Do This
public class  YouCantCreateMe {
   public YouCantCreateMe() {
      throw new RuntimeException("Sorry");
   }
 }

Avoid creating duplicate objects.

Quoting Joshua: "Reuse can be both faster and more stylish".

Following the intent of this item requires sound judgment. There are quite a few considerations and counter-arguments that a programmer has to contemplate while following what has been said here.

Note that reuse here refers to functionally equivalent objects. In other words, there is a potential to reuse existing objects in lieu of new ones, if the new ones are functionally equivalent to existing ones.

In order to take benefits of object reuse, one should carefully study the immutable classes and use them whenever possible as they always promote reuse through functional equivalence. Making a class immutable however, needs thorough analysis.

More subtle cases involve reusing the objects when they are mutable. These are more complex cases to analyze. For example, a profiling session tells you that you are calling a method hundreds of times and that this method unnecessarily creates invariant objects every time it is called. In that case, again, after thorough analysis, you can optimize the use of existing objects by facilitating reuse.

//Don't Do This
 String s = new String("silly");
//The argument to the String constructor ("silly") is itself a 
//String instance, functionally identical to all of the objects 
//created by the constructor.

Eliminate obsolete object references.

Myth for novice programmers: Java (programs written in Java) has no memory leaks.

Although Java manages the memory required for our programs, it can not understand what we want to do. If we are holding onto an object by maintaining a reference to it, it is obvious that Java thinks that we want to do that. This means that as programmers, it is our prime responsibility to not hold onto references that are obsolete. Holding onto obsolete references constitutes memory leaks in Java. This is also termed as unintentional object retention.

Nulling out a reference to remove obsolete references to an object is good, but one must not overdo it. The best way to eliminate an obsolete reference is to reuse the variable in which it was contained or to let it fall out of 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 -- Don't confuse this with the previous paragraph. You don't have to necessarily null out the references if the variable falls out of scope.

Because memory leaks typically do not manifest themselves as obvious failures, they may remain present in a system for years. -- This is why they are subtle to find out and remove. Programmers need heap profilers to diagnose such silent killers.

Avoid finalizers.

"Finalizers are unpredictable, often dangerous, and generally unnecessary. Their use can cause erratic behavior, poor performance, and portability problems."

Frankly, I have never used finalizers and hence I don't have much to add to this discussion. It is worth noting that depending on execution of finalizers is a bad decision nevertheless.

Providing and making clients of your code call a termination or resource reclamation method leads to much cleaner API. Examples are: close() method on several java.io classes.

A legitimate use of finalizers arises when you feel the need of a safety net because the clients may not do the due diligence and resources are not reclaimed. Obviously, finalizers are not the best solution for this (owing to previous discussion), but that is the only way.

Another reason for their use is in case of classes that have native peers. Remember however that native peers must not hold critical resources to be reclaimed in a finalizer.

The rules of thumb are:

• Don't use finalizers yet. If you have to claim critical resources promptly, explicit termination method (that clients should call) is the only right hook for that.
• "The termination method should do whatever is required to free the critical resource. The termination method can be a native method, or it can invoke one."
• If you override finalize(), then it is a good practice to manually call super.finalize() since chaining of finalizers is not automatic. Object.finalize() simply returns (is a no-op).

Finally, Joshua suggests a finalizer guardian idiom for a nonfinal public class that guards against a malicious subclass that fails to call super.finalize() failing to give your class a chance to finalize. This idiom is used in java.util.Timer class. A finalizer guardian's (which is an instance of anonymous inner class) sole purpose (at the cost of its existence) is to call the enclosing instance's finalize() method.

A quick check on GlassFish codebase reveals that there are several finalizers and I am not quite sure if all of them are called for.

Minimize the accessibility of classes and members.

Benefits of information hiding (encapsulation) and separating interfaces from implementation are obvious. Java provides several facilities to hide the internals of a module. This results in clean design and modules can be tested, changed without affecting the correctness of the entire system since modules rely on each other's API. Don't confuse information hiding with the subtle topic of Method Overloading-Method Overriding-Field Hiding.

Access Control Mechanism in Java should be carefully studied. From this standpoint, (top-level) classes and members are the two broad categories of interest. As of Java SE 5.0 and Java SE 6, packages are the only way to sand-box code organized into classes and interfaces. The natural way to design large bodies of code is to first define the API and then define packages, then interfaces and classes and then implement the methods and fields considering access specification at every step. To achieve this, it is best to start with the most protected access and then relax it, till you achieve required accessibility.

The rule of thumb is that you should make each class or member as inaccessible as possible.

The default access is implied by the absence of any specifier on a given entity. Thus, a top-level class (and interface) is either public which means it is seen by the universe or it is package-private which means by default, only other classes and interface in the same package can see it. This is the first entry point as far as access is concerned.

If a package-private top-level class or interface is used only from within a single class, you should consider making it a private nested class (or interface) of the class in which it is used (Item 18).

A member can have one of private (accessible only from within the class) , package-private (default, accessible from within any class in the same package), protected (mostly accessible from any subclass anywhere and from within the package) and public (accessible from anywhere) access specifiers. An important conclusion is that the protected access specifier is less protected than the default access, don't place a protected access specifier in an attempt to protect a member of a class. Thus, if you are unsure of accessibility, start with private, followed by package-private.

Public variables should be avoided as they result in exposing the internal representation of the data and are hard to replace by something else. An exception here is the definition of constants. Constants should always be instances of either primitive types or immutable classes. "A final field containing a reference to a mutable object has all the disadvantages of
a nonfinal field."

Note that a nonzero-length array is always mutable, so it is nearly always wrong to have public static final array field.

To summarize, optimizing access specification is like tightening the screws leaving tolerance that is just enough, eliminating extraneous words in a sentence, paragraphs in a chapter and so on.

//Don't Do This
class Base { 
    public static final String NAME = "Base";
    // Hiding/Shadowing is not advisable
}
class Derived extends Base {
    public static final String NAME = "Derived";
}

//Potential security hole! 
public static final Type[] VALUES =  { ... };

Favor Immutability.

An immutable class is simply a class whose instances cannot be modified. An immutable object can be in exactly one state, the state in which it was created.

Follow this recipe to impart immutability to classes.

Immutable objects are simple and inherently thread-safe; they require no synchronization since there are no state changes that they go through.

It is appropriate to share the internals of immutable objects with other objects if there is no way to modify them. Generally speaking, the internals of an immutable object are comprised of immutable objects.

Ways to make an object immutable in addition to following the recipe:

1. Make the class final. Make the class non-final but make all the methods final, leaving the room for extension. This means you have to undertake the responsibility of defending against malicious subclasses.
2. Make the constructors private (or package-private) and provide static factory methods.

It is an oversight that BigInteger and BigDecimal classes are not final. You should always make value classes immutable. To reduce the performance overhead, you can think of a package-private mutable companion class that an immutable class uses to speed up multistep operations. If predicting what can be done with an immutable class is not possible, make this companion class public (for example, java.lang.String and java.lang.StringBuffer).

Favor composition over inheritance.

Implementation Inheritance is dangerous with classes not designed for that. This is mainly because the superclass implementation of overridden methods may change from release to release and break the subclasses even if their (of subclasses) implementation has not changed.

To quote Joshua:

A related cause of fragility in subclasses is that their superclasses can acquire new methods in subsequent releases.

Surprising things may result if you rely on the implementation of behavior in superclasses. This is especially so for classes that are not designed for extension. The effect is pronounced when when you use overriding.

An alternate technique uses composition and employs the decorator or forwarding design pattern. The idea is to make an implementation a private member of your class and forward requests of common interface to that member. This is likely to make your implementation more robust.

<personal-problem>
The inheritance-composition dilemma usually takes some toll on me. Composition is likely to provide more robust design -- does it mean that when programmers are not sure about extensibility of implementation, they should make all implementations final?

On the other hand, we have some examples where inheritance is used effectively and composition is considered at least tedious or procedural.

</personal-problem>

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

According to Joshua:

There are a number of obvious violations of this principle in the Java platform libraries. For example, a stack is not a vector, so Stack should not extend Vector. Similarly, a property list is not a hash table so Properties should not extend Hashtable. In both cases, composition would have been appropriate.

Design and document (for) inheritance or else prohibit it.

(Editorial comment: As the perhaps only case, I thought for is not required in this item's synopsis).

Perhaps this item tries to minimize the dilemma about when to choose inheritance.

Documentation of how a class uses its overridable methods in the /**doc comments */ of a method is a must. This helps users of the API to understand the implications of overriding methods. This is called documenting self-use of the class.

This is where (I feel) the art part of programming comes into picture (again), since there is no recipe to follow.

There are a few more restrictions that a class must obey to allow inheritance. Constructors must not invoke overridable methods, directly or indirectly. If this rule is violated, it is likely that program failure will result. The superclass constructor runs before the subclass constructor, so the overriding method in the subclass will get invoked before the subclass constructor has run. If the overriding method depends on any initialization performed by the subclass constructor, then the method will not behave as expected.

Note that if you violate the above, a final field can be observed in two different states by a program!

It's generally not a good idea for classes designed for extension to implement Cloneable or Serializable interfaces. If they do, they should follow certain restrictions:

Neither clone nor readObject may invoke an overridable method, directly or indirectly.

This is where the implementation of a class becomes part of public interface of a class. This is because if you have designed a Serializable class for extension, you have to make readresolve() or writeReplace() methods protected or else they are silently ignored by the subclasses while (de)serializing.

Since this is rather confusing, I am going to quote Joshua, as I can't do any better --

The best solution to this problem is to prohibit subclassing in classes that are not designed and documented to be safely subclassed. There are two ways to prohibit subclassing. The easier of the two is to declare the class final. The alternative is to make all the constructors private or package-private and to add public static factories in place of the constructors. This alternative, which provides the flexibility to use subclasses internally, is discussed in Item 13. Either approach is acceptable.

This advice may be somewhat controversial, as many programmers have grown accustomed to subclassing ordinary concrete classes to add facilities such as instrumentation, notification, and synchronization or to limit functionality. If a class implements some interface that captures its essence, such as Set, List, or Map, then you should feel no compunction about prohibiting subclassing. The wrapper class pattern, described in Item 14, provides a superior alternative to inheritance for altering the functionality.

This item concludes by providing a technique of moving the self-use of a class's overridable methods to its private helper method.