org.klomp.snark.comments

## Class CommentSet

- java.lang.Object
- - java.util.AbstractCollection<E>
  - - java.util.AbstractSet<Comment>
    - - org.klomp.snark.comments.CommentSet

- All Implemented Interfaces:
    Iterable<Comment>, Collection<Comment>, Set<Comment>

      public class CommentSet
      extends AbstractSet<Comment>

  Store comments.

  Optimized for fast checking of duplicates, and retrieval of ratings. Removes are not really removed, only marked as hidden, so they don't reappear. Duplicates are detected based on an approximate time range. Max size of both elements and total text length is enforced.

  Supports persistence via save() and File constructor.

  NOT THREAD SAFE except for iterating AFTER the iterator() call.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `MAX_SIZE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CommentSet(Collection<Comment> coll)`
    `CommentSet(File file)` File must be gzipped.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(Comment c)` Max length for strings enforced in Comment.java.
    `void` | `clear()` Actually clears everything, including hidden.
    `double` | `getAverageRating()`
    `long` | `getLatestCommentTime()` Is not adjusted if the latest comment wasn't hidden but is then hidden.
    `int` | `getMyRating()`
    `int` | `getRatingCount()`
    `boolean` | `isModified()`
    `Iterator<Comment>` | `iterator()` Will be in reverse-sort order, i.e.
    `boolean` | `remove(int id)` Remove the id as retrieved from Comment.getID().
    `boolean` | `remove(Object o)` Only hides the comment, doesn't really remove it.
    `void` | `save(File file)` File will be gzipped.
    `int` | `size()` May be more than what the iterator returns, we do additional deduping in the iterator.

    - ### Methods inherited from class java.util.AbstractSet

      `equals, hashCode, removeAll`

    - ### Methods inherited from class java.util.AbstractCollection

      `addAll, contains, containsAll, isEmpty, retainAll, toArray, toArray, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.Set

      `addAll, contains, containsAll, isEmpty, retainAll, spliterator, toArray, toArray`

    - ### Methods inherited from interface java.util.Collection

      `parallelStream, removeIf, stream`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach`

- - ### Field Detail

    - #### MAX_SIZE

          public static final int MAX_SIZE

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### CommentSet

          public CommentSet(Collection<Comment> coll)

    - #### CommentSet

          public CommentSet(File file)
                     throws IOException

      File must be gzipped. Need not be sorted. See Comment.toPersistentString() for format.
      Throws:
        `IOException`

  - ### Method Detail

    - #### add

          public boolean add(Comment c)

      Max length for strings enforced in Comment.java. Max total length for strings enforced here. Enforces max size for set
      Specified by:
        `add` in interface `Collection<Comment>`
      Specified by:
        `add` in interface `Set<Comment>`
      Overrides:
        `add` in class `AbstractCollection<Comment>`

    - #### clear

          public void clear()

      Actually clears everything, including hidden. Resets ratings to zero.
      Specified by:
        `clear` in interface `Collection<Comment>`
      Specified by:
        `clear` in interface `Set<Comment>`
      Overrides:
        `clear` in class `AbstractCollection<Comment>`

    - #### getAverageRating

          public double getAverageRating()

      Returns:
        0 if none, or 1-5

    - #### getLatestCommentTime

          public long getLatestCommentTime()

      Is not adjusted if the latest comment wasn't hidden but is then hidden.
      Returns:
        the timestamp of the most recent non-hidden comment

    - #### getMyRating

          public int getMyRating()

      Returns:
        0 if none, or 1-5

    - #### getRatingCount

          public int getRatingCount()

      Returns:
        Number of ratings making up the average rating

    - #### isModified

          public boolean isModified()

      Returns:
        true if modified since instantiation

    - #### iterator

          public Iterator<Comment> iterator()

      Will be in reverse-sort order, i.e. newest-first. The returned iterator is thread-safe after this call. Changes after this call will not be reflected in the iterator. iter.remove() has no effect on the underlying set. Hidden comments not included.

      Returned values may be less than indicated in size() due to additional deduping in the iterator.

      Specified by:
        `iterator` in interface `Iterable<Comment>`
      Specified by:
        `iterator` in interface `Collection<Comment>`
      Specified by:
        `iterator` in interface `Set<Comment>`
      Specified by:
        `iterator` in class `AbstractCollection<Comment>`

    - #### remove

          public boolean remove(int id)

      Remove the id as retrieved from Comment.getID(). Only hides the comment, doesn't really remove it. This is for the UI.
      Returns:
        true if present and not previously hidden

    - #### remove

          public boolean remove(Object o)

      Only hides the comment, doesn't really remove it.
      Specified by:
        `remove` in interface `Collection<Comment>`
      Specified by:
        `remove` in interface `Set<Comment>`
      Overrides:
        `remove` in class `AbstractCollection<Comment>`
      Returns:
        true if present and not previously hidden

    - #### save

          public void save(File file)
                    throws IOException

      File will be gzipped. Not sorted, includes hidden. See Comment.toPersistentString() for format. Sets isModified() to false.
      Throws:
        `IOException`

    - #### size

          public int size()

      May be more than what the iterator returns, we do additional deduping in the iterator.
      Specified by:
        `size` in interface `Collection<Comment>`
      Specified by:
        `size` in interface `Set<Comment>`
      Specified by:
        `size` in class `AbstractCollection<Comment>`
      Returns:
        the non-hidden size