    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Interface collections.UpdatableCollection

public interface interface UpdatableCollection
extends Collection

UpdatableCollection is the root interface of all mutable collections; i.e., collections that may have elements dynamically added, removed, and/or replaced in accord with their collection semantics.

##

clear()
  Cause the collection to become empty.
exclude(Object)
  Exclude all occurrences of the indicated element from the collection.
excludeElements(Enumeration)
  Exclude all occurrences of each element of the Enumeration.
removeElements(Enumeration)
  Remove an occurrence of each element of the Enumeration.
removeOneOf(Object)
  Remove an instance of the indicated element from the collection.
replaceAllOf(Object, Object)
  Replace all occurrences of oldElement with newElement.
replaceOneOf(Object, Object)
  Replace an occurrence of oldElement with newElement.
take()
  Remove and return an element.
version()
  All updatable collections maintain a `version number'.

##

version

     public abstract int version()

  All updatable collections maintain a `version number'. The numbering scheme is arbitrary, but is guaranteed to change upon every modification that could possibly affect an elements() enumeration traversal. (This is true at least within the precision of the `int' representation; performing more than 2^32 operations will lead to reuse of version numbers). Versioning may be conservative with respect to `replacement' operations. For the sake of versioning replacements may be considered as removals followed by additions. Thus version numbers may change even if the old and new elements are identical.

  All element() enumerations for Updatable Collections track version numbers, and raise inconsistency exceptions if the enumeration is used (via nextElement()) on a version other than the one generated by the elements() method.

  You can use versions to check if update operations actually have any effect on observable state. For example, clear() will cause cause a version change only if the collection was previously non-empty.

  Returns:
    the version number

clear

     public abstract void clear()

  Cause the collection to become empty.

  Returns:
    condition:

         isEmpty() &&
         Version change iff !PREV(this).isEmpty();

exclude

     public abstract void exclude(Object element)

  Exclude all occurrences of the indicated element from the collection. No effect if element not present.

  Parameters:
    element - the element to exclude.
  Returns:
    condition:

         !includes(element) &&
         size() == PREV(this).size() - PREV(this).occurrencesOf(element) &&
         no other element changes &&
         Version change iff PREV(this).includes(element)

removeOneOf

     public abstract void removeOneOf(Object element)

  Remove an instance of the indicated element from the collection. No effect if !includes(element)

  Parameters:
    element - the element to remove
  Returns:
    condition:

         let occ = max(1, occurrencesOf(element)) in
          size() == PREV(this).size() - occ &&
          occurrencesOf(element) == PREV(this).occurrencesOf(element) - occ &&
          no other element changes &&
          version change iff occ == 1

replaceOneOf

     public abstract void replaceOneOf(Object oldElement,
                                       Object newElement) throws IllegalElementException

  Replace an occurrence of oldElement with newElement. No effect if does not hold oldElement or if oldElement.equals(newElement). The operation has a consistent, but slightly special interpretation when applied to Sets. For Sets, because elements occur at most once, if newElement is already included, replacing oldElement with with newElement has the same effect as just removing oldElement.

  Returns:
    condition:

         let int delta = oldElement.equals(newElement)? 0 :
                       max(1, PREV(this).occurrencesOf(oldElement) in
          occurrencesOf(oldElement) == PREV(this).occurrencesOf(oldElement) - delta &&
          occurrencesOf(newElement) ==  (this instanceof Set) ?
                 max(1, PREV(this).occurrencesOf(oldElement) + delta):
                        PREV(this).occurrencesOf(oldElement) + delta) &&
          no other element changes &&
          Version change iff delta != 0

  Throws: IllegalElementException
    if includes(oldElement) and !canInclude(newElement)

replaceAllOf

     public abstract void replaceAllOf(Object oldElement,
                                       Object newElement) throws IllegalElementException

  Replace all occurrences of oldElement with newElement. No effect if does not hold oldElement or if oldElement.equals(newElement). The operation has a consistent, but slightly special interpretation when applied to Sets. For Sets, because elements occur at most once, if newElement is already included, replacing oldElement with with newElement has the same effect as just removing oldElement.

  Returns:
    condition:

         let int delta = oldElement.equals(newElement)? 0 :
        PREV(this).occurrencesOf(oldElement) in
          occurrencesOf(oldElement) == PREV(this).occurrencesOf(oldElement) - delta &&
          occurrencesOf(newElement) ==  (this instanceof Set) ?
                 max(1, PREV(this).occurrencesOf(oldElement) + delta):
                        PREV(this).occurrencesOf(oldElement) + delta) &&
          no other element changes &&
          Version change iff delta != 0

  Throws: IllegalElementException
    if includes(oldElement) and !canInclude(newElement)

take

     public abstract Object take() throws NoSuchElementException

  Remove and return an element. Implementations may strengthen the guarantee about the nature of this element. but in general it is the most convenient or efficient element to remove.

  Example usage. One way to transfer all elements from UpdatableCollection a to UpdatableBag b is:

       while (!a.empty()) b.add(a.take());

  Returns:
    an element v such that PREV(this).includes(v) and the postconditions of removeOneOf(v) hold.
  Throws: NoSuchElementException
    iff isEmpty.

excludeElements

     public abstract void excludeElements(Enumeration e) throws CorruptedEnumerationException

  Exclude all occurrences of each element of the Enumeration. Behaviorally equivalent to

       while (e.hasMoreElements()) exclude(e.nextElement());

  Parameters:
    e - the enumeration of elements to exclude.
  Throws: CorruptedEnumerationException
    is propagated if thrown

removeElements

     public abstract void removeElements(Enumeration e) throws CorruptedEnumerationException

  Remove an occurrence of each element of the Enumeration. Behaviorally equivalent to

       while (e.hasMoreElements()) removeOneOf(e.nextElement());

  Parameters:
    e - the enumeration of elements to remove.
  Throws: CorruptedEnumerationException
    is propagated if thrown

    All Packages  Class Hierarchy  This Package  Previous  Next  Index