Package com.luciad.util.collections

Interface ILcdCollection<T>

All Superinterfaces:
Collection<T>, Iterable<T>
All Known Subinterfaces:
ILcdList<T>
All Known Implementing Classes:
TLcdArrayList, TLspGraphicsEffects
public interface ILcdCollection<T> extends Collection<T>

An extension of the Java Collection which fires a TLcdCollectionEvent for every element that is added to or removed from the collection.

Due to those events, there is a decrease in performance compared to the traditional Collection when adding and/or removing multiple elements at once (e.g. addAll(java.util.Collection) or removeAll(java.util.Collection) ). For every element that is added or removed, those methods should fire an individual event. An example implementation for such a method is:

public boolean addAll(Collection<? extends T> aCollection) {
  boolean result = false;
  for (T element : aCollection) {
    result = add(element) || result;
  }
  return result;
}
The firing of events can also be postponed, by means of the methods that take an ILcdFireEventMode parameter. This is useful for example when the collection is protected by a read/write lock. In that case, the actual modifications must be performed within the write lock, while the change events are only fired afterwards when the lock has been released, in order to avoid potential deadlocks down the line. For example, as follows: 
    try (TLcdLockUtil.Lock writeLock = TLcdLockUtil.writeLock(collection)) {
      collection.add(element, ILcdFireEventMode.FIRE_LATER);
    } finally {
      collection.fireCollectedChanges();
    }
Since:
9.1
See Also:

  • Method Details

    • addAll

      default boolean addAll(Collection<? extends T> aCollection)

      The elements should be added to the Collection one by one, and an TLcdCollectionEvent fired each time an element has been added.

      This method immediately fires change events to its registered change listeners. If this collection is protected by a read/write lock, call addAll(Collection, int) instead with the ILcdFireEventMode.FIRE_LATER fire event mode, and subsequently call fireCollectedChanges() after the lock has been released. This can avoid potential deadlocks down the line. See the class javadoc for an example code snippet.

      Specified by:
      addAll in interface Collection<T>
      See Also:

    • removeAll

      default boolean removeAll(Collection<?> aCollection)

      The elements should be removed from the Collection one by one, and an TLcdCollectionEvent fired each time an element has been removed.

      This method immediately fires change events to its registered change listeners. If this collection is protected by a read/write lock, call removeAll(Collection, int) instead with the ILcdFireEventMode.FIRE_LATER fire event mode, and subsequently call fireCollectedChanges() after the lock has been released. This can avoid potential deadlocks down the line. See the class javadoc for an example code snippet.

      Specified by:
      removeAll in interface Collection<T>
      See Also:

    • retainAll

      default boolean retainAll(Collection<?> aCollection)

      The elements should be removed from the Collection one by one, and an TLcdCollectionEvent fired each time an element has been removed.

      This method immediately fires change events to its registered change listeners. If this collection is protected by a read/write lock, call retainAll(Collection, int) instead with the ILcdFireEventMode.FIRE_LATER fire event mode, and subsequently call fireCollectedChanges() after the lock has been released. This can avoid potential deadlocks down the line. See the class javadoc for an example code snippet.

      Specified by:
      retainAll in interface Collection<T>
      See Also:

    • clear

      default void clear()

      The elements should be removed from the Collection one by one, and an TLcdCollectionEvent fired each time an element has been removed.

      This method immediately fires change events to its registered change listeners. If this collection is protected by a read/write lock, call clear(int) instead with the ILcdFireEventMode.FIRE_LATER fire event mode, and subsequently call fireCollectedChanges() after the lock has been released. This can avoid potential deadlocks down the line. See the class javadoc for an example code snippet.

      Specified by:
      clear in interface Collection<T>
      See Also:

    • add

      default boolean add(T aElement)

      This method immediately fires change events to its registered change listeners. If this collection is protected by a read/write lock, call add(Object, int) instead with the ILcdFireEventMode.FIRE_LATER fire event mode, and subsequently call fireCollectedChanges() after the lock has been released. This can avoid potential deadlocks down the line. See the class javadoc for an example code snippet.

      Specified by:
      add in interface Collection<T>
      See Also:

    • remove

      default boolean remove(Object aElement)

      This method immediately fires change events to its registered change listeners. If this collection is protected by a read/write lock, call remove(Object, int) instead with the ILcdFireEventMode.FIRE_LATER fire event mode, and subsequently call fireCollectedChanges() after the lock has been released. This can avoid potential deadlocks down the line. See the class javadoc for an example code snippet.

      Specified by:
      remove in interface Collection<T>
      See Also:

    • addAll

      default boolean addAll(Collection<? extends T> aCollection, int aEventMode)
      This method behaves the same as addAll(Collection), but additionally accepts an ILcdFireEventMode parameter that allows to postpone firing change events resulting from this method call. When ILcdFireEventMode.FIRE_LATER is passed, any change events are temporarily stored and only fired once fireCollectedChanges() is called. This is useful for example when the collection is protected by a read/write lock, in order to avoid potential deadlocks down the line. See the class javadoc for an example code snippet.
      Parameters:
      aCollection - collection containing elements to be added to this collection.
      aEventMode - the ILcdFireEventMode for sending out the change event.
      Returns:
      true if this collection changed as a result of the call
      Since:
      2024.1
      See Also:

    • removeAll

      default boolean removeAll(Collection<?> aCollection, int aEventMode)
      This method behaves the same as removeAll(Collection), but additionally accepts an ILcdFireEventMode parameter that allows to postpone firing change events resulting from this method call. When ILcdFireEventMode.FIRE_LATER is passed, any change events are temporarily stored and only fired once fireCollectedChanges() is called. This is useful for example when the collection is protected by a read/write lock, in order to avoid potential deadlocks down the line. See the class javadoc for an example code snippet.
      Parameters:
      aCollection - collection containing elements to be removed from this collection.
      aEventMode - the ILcdFireEventMode for sending out the change event.
      Returns:
      true if this collection changed as a result of the call
      Since:
      2024.1
      See Also:

    • retainAll

      default boolean retainAll(Collection<?> aCollection, int aEventMode)
      This method behaves the same as retainAll(Collection), but additionally accepts an ILcdFireEventMode parameter that allows to postpone firing change events resulting from this method call. When ILcdFireEventMode.FIRE_LATER is passed, any change events are temporarily stored and only fired once fireCollectedChanges() is called. This is useful for example when the collection is protected by a read/write lock, in order to avoid potential deadlocks down the line. See the class javadoc for an example code snippet.
      Parameters:
      aCollection - collection containing elements to be retained in this collection.
      aEventMode - the ILcdFireEventMode for sending out the change event.
      Returns:
      true if this collection changed as a result of the call
      Since:
      2024.1
      See Also:

    • clear

      default void clear(int aEventMode)
      This method behaves the same as clear(), but additionally accepts an ILcdFireEventMode parameter that allows to postpone firing change events resulting from this method call. When ILcdFireEventMode.FIRE_LATER is passed, any change events are temporarily stored and only fired once fireCollectedChanges() is called. This is useful for example when the collection is protected by a read/write lock, in order to avoid potential deadlocks down the line. See the class javadoc for an example code snippet.
      Parameters:
      aEventMode - the ILcdFireEventMode for sending out the change event.
      Since:
      2024.1
      See Also:

    • add

      default boolean add(T aElement, int aEventMode)
      This method behaves the same as add(Object), but additionally accepts an ILcdFireEventMode parameter that allows to postpone firing change events resulting from this method call. When ILcdFireEventMode.FIRE_LATER is passed, any change events are temporarily stored and only fired once fireCollectedChanges() is called. This is useful for example when the collection is protected by a read/write lock, in order to avoid potential deadlocks down the line. See the class javadoc for an example code snippet.
      Parameters:
      aElement - element whose presence in this collection is to be ensured.
      aEventMode - the ILcdFireEventMode for sending out the change event.
      Returns:
      true if this collection changed as a result of the call
      Since:
      2024.1
      See Also:

    • remove

      default boolean remove(Object aElement, int aEventMode)
      This method behaves the same as remove(Object), but additionally accepts an ILcdFireEventMode parameter that allows to postpone firing change events resulting from this method call. When ILcdFireEventMode.FIRE_LATER is passed, any change events are temporarily stored and only fired once fireCollectedChanges() is called. This is useful for example when the collection is protected by a read/write lock, in order to avoid potential deadlocks down the line. See the class javadoc for an example code snippet.
      Parameters:
      aElement - element to be removed from this collection, if present.
      aEventMode - the ILcdFireEventMode for sending out the change event.
      Returns:
      true if an element was removed as a result of this call
      Since:
      2024.1
      See Also:

    • fireCollectedChanges

      default void fireCollectedChanges()
      Fires all the collected change events from modifications performed with the ILcdFireEventMode.FIRE_LATER fire event mode.
      Since:
      2024.1

    • addCollectionListener

      void addCollectionListener(ILcdCollectionListener<T> aCollectionListener)

      Register the listener aCollectionListener to be informed about changes in this collection.

      Parameters:
      aCollectionListener - the listener
      See Also:

    • removeCollectionListener

      void removeCollectionListener(ILcdCollectionListener<T> aCollectionListener)

      Unregister the listener aCollectionListener so it will no longer be informed about changes in this collection.

      This method should do nothing when aCollectionListener was not registered previously.

      Parameters:
      aCollectionListener - the listener
      See Also: