[COLLECTIONS-388] Inconsistent Javadoc comment and code for prototypeFactory(T) in org.apache.commons.collections.FactoryUtils

• Type: Bug
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: 4.0, 4.x
• Fix Version/s: 4.0-alpha1, 4.0
• Component/s: Collection
• Labels: javadoc null

Environment

Platform independent

• Assignee: Unassigned
• Reporter: SHIN HWEI TAN
• Created: 08/Jan/12 08:29
• Updated: 09/Nov/14 14:31
• Resolved: 09/Apr/12 17:16

Description

The Javadoc comment below states that the method "throws IllegalArgumentException if the prototype is null":
/**
..

• @param prototype the object to clone each time in the factory
• @return the <code>prototype</code> factory
• @throws IllegalArgumentException if the prototype is null
• @throws IllegalArgumentException if the prototype cannot be cloned
  */
  public static <T> Factory<T> prototypeFactory(T prototype) { return PrototypeFactory.<T>prototypeFactory(prototype); }

However, the method returns a NULL_INSTANCE object instead of throwing IllegalArgumentException when called with null.

Suggested Fixes:
1. Change "@throws IllegalArgumentException if the prototype is null" and "@return" to "@return NULL_INSTANCE if the prototype is null".
or
2. Remove the entire "throws IllegalArgumentException if the prototype is null".