Uploaded image for project: 'Commons Collections'
  1. Commons Collections
  2. COLLECTIONS-379

Bugs In Javadoc Comment in the CollectionUtils class

    XMLWordPrintableJSON

    Details

    • Type: Bug
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: 3.2
    • Fix Version/s: 4.0-alpha1, 4.0
    • Component/s: Collection
    • Labels:
    • Environment:

      System independent

      Description

      I came across the following bugs in the Javadoc comments in the method below in the CollectionUtils class:

      1.

      /**

      • Selects all elements from input collection which match the given predicate
      • and adds them to outputCollection.
      • <p>
      • If the input collection or predicate is null, there is no change to the
      • output collection.
      • @param inputCollection the collection to get the input from, may be null
      • @param predicate the predicate to use, may be null
      • @param outputCollection the collection to output into, may not be null
        */
        public static void select(Collection inputCollection, Predicate predicate, Collection outputCollection) {

      This method will execute normally when calling select((Collection)null, (Predicate)null, (Collection)null) but the comment clearly states that outputCollection may not be null

      2.

      /**

      • Selects all elements from inputCollection which don't match the given predicate
      • and adds them to outputCollection.
      • <p>
      • If the input predicate is <code>null</code>, no elements are added to <code>outputCollection</code>.
      • @param inputCollection the collection to get the input from, may be null
      • @param predicate the predicate to use, may be null
      • @param outputCollection the collection to output into, may not be null
        */
        public static void selectRejected(Collection inputCollection, Predicate predicate, Collection outputCollection) {

      This method will execute normally when calling selectRejected((Collection)null, (Predicate)null, (Collection)null) but the comment also clearly states that outputCollection may not be null

      3.

      /**

      • Transforms all elements from the inputIterator with the given transformer
      • and adds them to the outputCollection.
      • <p>
      • If the input iterator or transformer is null, there is no change to the
      • output collection.
        *
      • @param inputIterator the iterator to get the input from, may be null
      • @param transformer the transformer to use, may be null
      • @param outputCollection the collection to output into, may not be null
      • @return the outputCollection with the transformed input added
      • @throws NullPointerException if the output collection is null
        */
        public static Collection collect(Iterator inputIterator, final Transformer transformer, final Collection outputCollection) {

      This method will execute normally when calling collect((Iterator)null, (Transformer)null, (Collection)null) but the comment clearly states that NullPointerException will be thrown when the outputCollection is null

      4.

      /**

      • Transforms all elements from inputCollection with the given transformer
      • and adds them to the outputCollection.
      • <p>
      • If the input collection or transformer is null, there is no change to the
      • output collection.
        *
      • @param inputCollection the collection to get the input from, may be null
      • @param transformer the transformer to use, may be null
      • @param outputCollection the collection to output into, may not be null
      • @return the outputCollection with the transformed input added
      • @throws NullPointerException if the output collection is null
        */
        public static Collection collect(Collection inputCollection, final Transformer transformer, final Collection outputCollection) {

      This method will execute normally when calling collect((Collection)null, (Transformer)null, (Collection)null) but the comment clearly states that NullPointerException will be thrown when the outputCollection is null

      The bugs in the Javadoc comments above could be confusing to the users of the Common Collection library and they could be fixed easily by the developers..

      There are a few ways to fix the:
      1. Throwing the NullPointerException explicitly when the outputCollection is null.
      2. Changing the Javadoc comments to include the case where all of the parameters are null.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              shinhwei SHIN HWEI TAN
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Time Tracking

                Estimated:
                Original Estimate - 20m
                20m
                Remaining:
                Remaining Estimate - 20m
                20m
                Logged:
                Time Spent - Not Specified
                Not Specified