Effective Java

Effective Java: Programming Language Guide

• Item 1: Consider providing static factory methods instead of constructor.

Advantage: have a name, no new operator everytime, return any subtype of iteself.   Consider pattern: Singleton and Factory method (with many different ways to implement: Creator by inheritance, parameterized method, Template, Class::forName( … ). newInstance() in java). In java, all objects are reference, but value. so use new operator as less as possible. All assumption based on reference ( clone, equal, hashCode, Comparable.compareTos)

• Items 2: Enforce the singleton property with a private constructor. Singleton Pattern.
• Items 3: Enforece non-instantiability with a private constructor.
• Item 4: Avoid creating duplicate objects. Not use new operator much. Reference to object is kept track by JVM.
• Item 5: Eliminate obsolete object reference. Let reference of object null in order to let gc do its work.
• Item 6: Avoid finalizer instead of providing an explicit termination method in tryàcatchàfinally block. Finalizer of superclass must be invoked in your finalizer.
• Item 7: Obey the general contract when overriding equals of Object. Although object is a concrete class, it is designed primarily for extension. All of its non-final method(equals, hashcode, toString, clone, and finalize) have explicit general contracts because they are designed to be overiden. It is the responsibility of any class overiding these methods to obey their general contracts; failure to do so will prevent other classes that depend on these contracts from functioning properly in conjunction with the class. Also including interface: Comparable. compareTo.

• /*
   * Licensed to the Apache Software Foundation (ASF) under one or more
   * contributor license agreements.  See the NOTICE file distributed with
   * this work for additional information regarding copyright ownership.
   * The ASF licenses this file to You under the Apache License, Version 2.0
   * (the "License"); you may not use this file except in compliance with
   * the License.  You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  /*
   * Copyright (C) 2008 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package java.lang;
  
  /**
   * The root class of the Java class hierarchy. All non-primitive types
   * (including arrays) inherit either directly or indirectly from this class.
   *
   * <a name="writing_equals"><h4>Writing a correct {@code equals} method</h4></a>
   * <p>Follow this style to write a canonical {@code equals} method:
   * <pre>
   *   // Use @Override to avoid accidental overloading.
   *   &#x0040;Override public boolean equals(Object o) {
   *     // Return true if the objects are identical.
   *     // (This is just an optimization, not required for correctness.)
   *     if (this == o) {
   *       return true;
   *     }
   *
   *     // Return false if the other object has the wrong type.
   *     // This type may be an interface depending on the interface's specification.
   *     if (!(o instanceof MyType)) {
   *       return false;
   *     }
   *
   *     // Cast to the appropriate type.
   *     // This will succeed because of the instanceof, and lets us access private fields.
   *     MyType lhs = (MyType) o;
   *
   *     // Check each field. Primitive fields, reference fields, and nullable reference
   *     // fields are all treated differently.
   *     return primitiveField == lhs.primitiveField &amp;&amp;
   *             referenceField.equals(lhs.referenceField) &amp;&amp;
   *             (nullableField == null ? lhs.nullableField == null
   *                                    : nullableField.equals(lhs.nullableField));
   *   }
   * </pre>
   * <p>If you override {@code equals}, you should also override {@code hashCode}: equal
   * instances must have equal hash codes.
   *
   * <p>See <i>Effective Java</i> item 8 for much more detail and clarification.
   *
   * <a name="writing_hashCode"><h4>Writing a correct {@code hashCode} method</h4></a>
   * <p>Follow this style to write a canonical {@code hashCode} method:
   * <pre>
   *   &#x0040;Override public int hashCode() {
   *     // Start with a non-zero constant.
   *     int result = 17;
   *
   *     // Include a hash for each field.
   *     result = 31 * result + (booleanField ? 1 : 0);
   *
   *     result = 31 * result + byteField;
   *     result = 31 * result + charField;
   *     result = 31 * result + shortField;
   *     result = 31 * result + intField;
   *
   *     result = 31 * result + (int) (longField ^ (longField >>> 32));
   *
   *     result = 31 * result + Float.floatToIntBits(floatField);
   *
   *     long doubleFieldBits = Double.doubleToLongBits(doubleField);
   *     result = 31 * result + (int) (doubleFieldBits ^ (doubleFieldBits >>> 32));
   *
   *     result = 31 * result + Arrays.hashCode(arrayField);
   *
   *     result = 31 * result + referenceField.hashCode();
   *     result = 31 * result +
   *         (nullableReferenceField == null ? 0
   *                                         : nullableReferenceField.hashCode());
   *
   *     return result;
   *   }
   * </pre>
   *
   * <p>If you don't intend your type to be used as a hash key, don't simply rely on the default
   * {@code hashCode} implementation, because that silently and non-obviously breaks any future
   * code that does use your type as a hash key. You should throw instead:
   * <pre>
   *   &#x0040;Override public int hashCode() {
   *     throw new UnsupportedOperationException();
   *   }
   * </pre>
   *
   * <p>See <i>Effective Java</i> item 9 for much more detail and clarification.
   *
   * <a name="writing_toString"><h4>Writing a useful {@code toString} method</h4></a>
   * <p>For debugging convenience, it's common to override {@code toString} in this style:
   * <pre>
   *   &#x0040;Override public String toString() {
   *     return getClass().getName() + "[" +
   *         "primitiveField=" + primitiveField + ", " +
   *         "referenceField=" + referenceField + ", " +
   *         "arrayField=" + Arrays.toString(arrayField) + "]";
   *   }
   * </pre>
   * <p>The set of fields to include is generally the same as those that would be tested
   * in your {@code equals} implementation.
   * <p>See <i>Effective Java</i> item 10 for much more detail and clarification.
   */
  public class Object {
      /**
       * Constructs a new instance of {@code Object}.
       */
      public Object() {
      }
  
      /**
       * Creates and returns a copy of this {@code Object}. The default
       * implementation returns a so-called "shallow" copy: It creates a new
       * instance of the same class and then copies the field values (including
       * object references) from this instance to the new instance. A "deep" copy,
       * in contrast, would also recursively clone nested objects. A subclass that
       * needs to implement this kind of cloning should call {@code super.clone()}
       * to create the new instance and then create deep copies of the nested,
       * mutable objects.
       *
       * @return a copy of this object.
       * @throws CloneNotSupportedException
       *             if this object's class does not implement the {@code
       *             Cloneable} interface.
       */
      protected Object clone() throws CloneNotSupportedException {
          if (!(this instanceof Cloneable)) {
              throw new CloneNotSupportedException("Class doesn't implement Cloneable");
          }
  
          return internalClone((Cloneable) this);
      }
  
      /*
       * Native helper method for cloning.
       */
      private native Object internalClone(Cloneable o);
  
      /**
       * Compares this instance with the specified object and indicates if they
       * are equal. In order to be equal, {@code o} must represent the same object
       * as this instance using a class-specific comparison. The general contract
       * is that this comparison should be reflexive, symmetric, and transitive.
       * Also, no object reference other than null is equal to null.
       *
       * <p>The default implementation returns {@code true} only if {@code this ==
       * o}. See <a href="{@docRoot}reference/java/lang/Object.html#writing_equals">Writing a correct
       * {@code equals} method</a>
       * if you intend implementing your own {@code equals} method.
       *
       * <p>The general contract for the {@code equals} and {@link
       * #hashCode()} methods is that if {@code equals} returns {@code true} for
       * any two objects, then {@code hashCode()} must return the same value for
       * these objects. This means that subclasses of {@code Object} usually
       * override either both methods or neither of them.
       *
       * @param o
       *            the object to compare this instance with.
       * @return {@code true} if the specified object is equal to this {@code
       *         Object}; {@code false} otherwise.
       * @see #hashCode
       */
      public boolean equals(Object o) {
          return this == o;
      }
  
      /**
       * Invoked when the garbage collector has detected that this instance is no longer reachable.
       * The default implementation does nothing, but this method can be overridden to free resources.
       *
       * <p>Note that objects that override {@code finalize} are significantly more expensive than
       * objects that don't. Finalizers may be run a long time after the object is no longer
       * reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup.
       * Note also that finalizers are run on a single VM-wide finalizer thread,
       * so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary
       * for a class that has a native peer and needs to call a native method to destroy that peer.
       * Even then, it's better to provide an explicit {@code close} method (and implement
       * {@link java.io.Closeable}), and insist that callers manually dispose of instances. This
       * works well for something like files, but less well for something like a {@code BigInteger}
       * where typical calling code would have to deal with lots of temporaries. Unfortunately,
       * code that creates lots of temporaries is the worst kind of code from the point of view of
       * the single finalizer thread.
       *
       * <p>If you <i>must</i> use finalizers, consider at least providing your own
       * {@link java.lang.ref.ReferenceQueue} and having your own thread process that queue.
       *
       * <p>Unlike constructors, finalizers are not automatically chained. You are responsible for
       * calling {@code super.finalize()} yourself.
       *
       * <p>Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer
       * thread.
       *
       * See <i>Effective Java</i> Item 7, "Avoid finalizers" for more.
       */
      @FindBugsSuppressWarnings("FI_EMPTY")
      protected void finalize() throws Throwable {
      }
  
      /**
       * Returns the unique instance of {@link Class} that represents this
       * object's class. Note that {@code getClass()} is a special case in that it
       * actually returns {@code Class<? extends Foo>} where {@code Foo} is the
       * erasure of the type of the expression {@code getClass()} was called upon.
       * <p>
       * As an example, the following code actually compiles, although one might
       * think it shouldn't:
       * <p>
       * <pre>{@code
       *   List<Integer> l = new ArrayList<Integer>();
       *   Class<? extends List> c = l.getClass();}</pre>
       *
       * @return this object's {@code Class} instance.
       */
      public final native Class<?> getClass();
  
      /**
       * Returns an integer hash code for this object. By contract, any two
       * objects for which {@link #equals} returns {@code true} must return
       * the same hash code value. This means that subclasses of {@code Object}
       * usually override both methods or neither method.
       *
       * <p>Note that hash values must not change over time unless information used in equals
       * comparisons also changes.
       *
       * <p>See <a href="{@docRoot}reference/java/lang/Object.html#writing_hashCode">Writing a correct
       * {@code hashCode} method</a>
       * if you intend implementing your own {@code hashCode} method.
       *
       * @return this object's hash code.
       * @see #equals
       */
      public native int hashCode();
  
      /**
       * Causes a thread which is waiting on this object's monitor (by means of
       * calling one of the {@code wait()} methods) to be woken up. If more than
       * one thread is waiting, one of them is chosen at the discretion of the
       * VM. The chosen thread will not run immediately. The thread
       * that called {@code notify()} has to release the object's monitor first.
       * Also, the chosen thread still has to compete against other threads that
       * try to synchronize on the same object.
       * <p>
       * This method can only be invoked by a thread which owns this object's
       * monitor. A thread becomes owner of an object's monitor
       * </p>
       * <ul>
       * <li>by executing a synchronized method of that object;</li>
       * <li>by executing the body of a {@code synchronized} statement that
       * synchronizes on the object;</li>
       * <li>by executing a synchronized static method if the object is of type
       * {@code Class}.</li>
       * </ul>
       *
       * @see #notifyAll
       * @see #wait()
       * @see #wait(long)
       * @see #wait(long,int)
       * @see java.lang.Thread
       */
      public final native void notify();
  
      /**
       * Causes all threads which are waiting on this object's monitor (by means
       * of calling one of the {@code wait()} methods) to be woken up. The threads
       * will not run immediately. The thread that called {@code notify()} has to
       * release the object's monitor first. Also, the threads still have to
       * compete against other threads that try to synchronize on the same object.
       * <p>
       * This method can only be invoked by a thread which owns this object's
       * monitor. A thread becomes owner of an object's monitor
       * </p>
       * <ul>
       * <li>by executing a synchronized method of that object;</li>
       * <li>by executing the body of a {@code synchronized} statement that
       * synchronizes on the object;</li>
       * <li>by executing a synchronized static method if the object is of type
       * {@code Class}.</li>
       * </ul>
       *
       * @throws IllegalMonitorStateException
       *             if the thread calling this method is not the owner of this
       *             object's monitor.
       * @see #notify
       * @see #wait()
       * @see #wait(long)
       * @see #wait(long,int)
       * @see java.lang.Thread
       */
      public final native void notifyAll();
  
      /**
       * Returns a string containing a concise, human-readable description of this
       * object. Subclasses are encouraged to override this method and provide an
       * implementation that takes into account the object's type and data. The
       * default implementation is equivalent to the following expression:
       * <pre>
       *   getClass().getName() + '@' + Integer.toHexString(hashCode())</pre>
       * <p>See <a href="{@docRoot}reference/java/lang/Object.html#writing_toString">Writing a useful
       * {@code toString} method</a>
       * if you intend implementing your own {@code toString} method.
       *
       * @return a printable representation of this object.
       */
      public String toString() {
          return getClass().getName() + '@' + Integer.toHexString(hashCode());
      }
  
      /**
       * Causes the calling thread to wait until another thread calls the {@code
       * notify()} or {@code notifyAll()} method of this object. This method can
       * only be invoked by a thread which owns this object's monitor; see
       * {@link #notify()} on how a thread can become the owner of a monitor.
       * <p>
       * A waiting thread can be sent {@code interrupt()} to cause it to
       * prematurely stop waiting, so {@code wait} should be called in a loop to
       * check that the condition that has been waited for has been met before
       * continuing.
       * </p>
       * <p>
       * While the thread waits, it gives up ownership of this object's monitor.
       * When it is notified (or interrupted), it re-acquires the monitor before
       * it starts running.
       * </p>
       *
       * @throws IllegalMonitorStateException
       *             if the thread calling this method is not the owner of this
       *             object's monitor.
       * @throws InterruptedException
       *             if another thread interrupts this thread while it is waiting.
       * @see #notify
       * @see #notifyAll
       * @see #wait(long)
       * @see #wait(long,int)
       * @see java.lang.Thread
       */
      public final void wait() throws InterruptedException {
          wait(0 ,0);
      }
  
      /**
       * Causes the calling thread to wait until another thread calls the {@code
       * notify()} or {@code notifyAll()} method of this object or until the
       * specified timeout expires. This method can only be invoked by a thread
       * which owns this object's monitor; see {@link #notify()} on how a thread
       * can become the owner of a monitor.
       * <p>
       * A waiting thread can be sent {@code interrupt()} to cause it to
       * prematurely stop waiting, so {@code wait} should be called in a loop to
       * check that the condition that has been waited for has been met before
       * continuing.
       * </p>
       * <p>
       * While the thread waits, it gives up ownership of this object's monitor.
       * When it is notified (or interrupted), it re-acquires the monitor before
       * it starts running.
       * </p>
       *
       * @param millis
       *            the maximum time to wait in milliseconds.
       * @throws IllegalArgumentException
       *             if {@code millis < 0}.
       * @throws IllegalMonitorStateException
       *             if the thread calling this method is not the owner of this
       *             object's monitor.
       * @throws InterruptedException
       *             if another thread interrupts this thread while it is waiting.
       * @see #notify
       * @see #notifyAll
       * @see #wait()
       * @see #wait(long,int)
       * @see java.lang.Thread
       */
      public final void wait(long millis) throws InterruptedException {
          wait(millis, 0);
      }
  
      /**
       * Causes the calling thread to wait until another thread calls the {@code
       * notify()} or {@code notifyAll()} method of this object or until the
       * specified timeout expires. This method can only be invoked by a thread
       * that owns this object's monitor; see {@link #notify()} on how a thread
       * can become the owner of a monitor.
       * <p>
       * A waiting thread can be sent {@code interrupt()} to cause it to
       * prematurely stop waiting, so {@code wait} should be called in a loop to
       * check that the condition that has been waited for has been met before
       * continuing.
       * </p>
       * <p>
       * While the thread waits, it gives up ownership of this object's monitor.
       * When it is notified (or interrupted), it re-acquires the monitor before
       * it starts running.
       * </p>
       *
       * @param millis
       *            the maximum time to wait in milliseconds.
       * @param nanos
       *            the fraction of a millisecond to wait, specified in
       *            nanoseconds.
       * @throws IllegalArgumentException
       *             if {@code millis < 0}, {@code nanos < 0} or {@code nanos >
       *             999999}.
       * @throws IllegalMonitorStateException
       *             if the thread calling this method is not the owner of this
       *             object's monitor.
       * @throws InterruptedException
       *             if another thread interrupts this thread while it is waiting.
       * @see #notify
       * @see #notifyAll
       * @see #wait()
       * @see #wait(long,int)
       * @see java.lang.Thread
       */
      public final native void wait(long millis, int nanos) throws InterruptedException;
  }

• Item 8: Always overide hashCode when you orveride equals.
• Item 9: Always overide toString.
• Item 10: Overide clone judiciously(wisely).

• package java.lang;
  
  
  /**
   * This (empty) interface must be implemented by all classes that wish to
   * support cloning. The implementation of {@code clone()} in {@code Object}
   * checks if the object being cloned implements this interface and throws
   * {@code CloneNotSupportedException} if it does not.
   *
   * @see Object#clone
   * @see CloneNotSupportedException
   */
  public interface Cloneable {
      // Marker interface
  }

• Item 11: Consider implementing Comparable.

• public interface Comparable<T> {
  
      /**
       * Compares this object to the specified object to determine their relative
       * order.
       *
       * @param another
       *            the object to compare to this instance.
       * @return a negative integer if this instance is less than {@code another};
       *         a positive integer if this instance is greater than
       *         {@code another}; 0 if this instance has the same order as
       *         {@code another}.
       * @throws ClassCastException
       *             if {@code another} cannot be converted into something
       *             comparable to {@code this} instance.
       */
      int compareTo(T another);
  }

• Item 12: Minimize the accessibility of classes and member.
• Item 13: Favor immutability
• Item 14: Favor composition over inheritance.
• Item 15: Design and document for inheritance or else prohibit it.
• Item 16: Prefer interface to abstract classes
• Item 17: Use interface only to defint types.
• Item 18: Favor static member classes over non-static.
• Item 19: Replace structures with classes
• Item 20: Replace unions with class hierachies
• Item 21: Replace enum constructs with classes.
• Item 22: Replace function pointer with classes and interfaces.
• Item 23: Check parameters for validity
• Item 24: Make defensive copies when needed.
• Item 25: Desgin method signatures carefully
• Item 26: Use overloading wisely
• Item 27: Return zero-length arrays, not nulls
• Item 28: Write doc comments for all exposed API elements.
• Item 29: Minimize the scope of local variables.
• Item 30: Know and use the libraries
• Item 31: Avoid float and double if exact answers are required
• Item 32: Avoid strings where others types are more appropirate.
• Item 33: Beware the performance of string concatenation
• Item 34: Refer to objects by their interfaces.
• Item 35: Pefer interfaces to reflection
• Item 36: Use native methods judiciously
• Item 37: Optimize judiciously
• Item 38: Adhere to generally accepted naming conventions
• Item 39: Use exceptions only for exceptional conditions.
• Item 40: Use checked exceptions for recoverable conditions and run-time exceptions for programming errors.
• Item 41: Avoid unnecessary use of checked exceptions.
• Item 42: Favor the use of standard exceptions
• Item 43: Throw exceptions appropriate to the abstraction
• Item 44: Document all exceptions thrown by each method
• Item 45: Include failur-capture information in detail messages
• Item 47: Don’t ignore exceptions
• Item 48: Synchronize access to shared mutable data.
• Item 49: Avoid excessive synchronization
• Item 50: Never invoke wait outside a loop.
• Item 51: Don’t depend on the thread scheduler.
• Item 52: Document thread safely
• Item 53: Avoid thread groups
• Item 54: Implement Serializable judiciously
• Item 55: Consider using a custom serialized form
• Item 56: Write readObject methods defensively
• Item 57: Provide a readResovle method when necessary