Oracle Coherence for C++ API
Release 3.7.1.0

E22845-01

Collections Class Reference

#include <coherence/util/Collections.hpp>

List of all members.


Detailed Description

This class consists exclusively of static methods that operate on or return collections.

Author:
tb 2008.04.04
 

Static Public Member Functions

static void sort (List::Handle hList)
 Sorts the specified list into ascending order, according to the natural ordering of its elements.
static void sort (List::Handle hList, Comparator::Handle hComparator)
 Sorts the specified list according to the order induced by the specified comparator.
static Set::View singleton (Object::Holder ohElement)
 Returns an immutable set containing only the specified object.
static List::View singletonList (Object::Holder ohElement)
 Returns an immutable list containing only the specified object.
static Map::View singletonMap (Object::View vKey, Object::Holder ohValue)
 Returns an immutable map, mapping only the specified key to the specified value.
static Map::Handle synchronizedMap (Map::Handle hMap)
 Returns a synchronized (thread-safe) map backed by the specified map.
static Map::View synchronizedMap (Map::View vMap)
 Returns a synchronized (thread-safe) map backed by the specified map.
static SortedMap::Handle synchronizedSortedMap (SortedMap::Handle hSortedMap)
 Returns a synchronized (thread-safe) sorted map backed by the specified sorted map.
static SortedMap::View synchronizedSortedMap (SortedMap::View vSortedMap)
 Returns a synchronized (thread-safe) map backed by the specified sorted map.
static Collection::Handle unmodifiableCollection (Collection::View vCollection)
 Returns an unmodifiable view of the specified collection.
static Set::Handle unmodifiableSet (Set::View vSet)
 Returns an unmodifiable view of the specified set.
static Set::View emptySet ()
 Returns an unmodifiable view of an empty set.
static Map::View emptyMap ()
 Returns an unmodifiable view of an empty map.
static void toStream (std::ostream &out, Iterator::Handle hIter)
 Write out the contents of a Iterator.
static void toStream (std::ostream &out, Collection::View vCol)
 Write out the contents of a Collection.
static void toStream (std::ostream &out, Map::View vMap)
 Write out the contents of a Map.
static void toStream (std::ostream &out, Map::Entry::View vEntry)
 Write out the contents of a Entry.
static
ObjectArray::Handle 
toArray (Collection::View vCol, ObjectArray::Handle hao=NULL)
 Return the contents of the collection as an ObjectArray.

Member Function Documentation

static void sort ( List::Handle  hList  )  [static]

Sorts the specified list into ascending order, according to the natural ordering of its elements.

All elements in the list must implement the Comparable interface. Furthermore, all elements in the list must be mutually comparable.

This sort is guaranteed to be stable: equal elements will not be reordered as a result of the sort.

The specified list must be modifiable, but need not be resizable.

Parameters:
 hList the list to be sorted
Exceptions:
 ClassCastException if the list contains elements that are not mutually comparable
 UnsupportedOperationException if the specified list's list-iterator does not support the set operation

static void sort ( List::Handle  hList,
    Comparator::Handle  hComparator 
  )    [static]

Sorts the specified list according to the order induced by the specified comparator.

All elements in the list must be mutually comparable using the specified comparator

This sort is guaranteed to be stable: equal elements will not be reordered as a result of the sort.

The specified list must be modifiable, but need not be resizable.

Parameters:
 hList the list to be sorted.
 hComparator the comparator to determine the order of the list. A null value indicates that the elements' natural ordering should be used.
Exceptions:
 ClassCastException if the list contains elements that are not mutually comparable using the specified comparator.
 UnsupportedOperationException if the specified list's list-iterator does not support the set operation.

static Set::View singleton ( Object::Holder  ohElement  )  [static]

Returns an immutable set containing only the specified object.

Parameters:
 ohElement the sole object to be stored in the returned set
Returns:
an immutable set containing only the specified object

static List::View singletonList ( Object::Holder  ohElement  )  [static]

Returns an immutable list containing only the specified object.

Parameters:
 ohElement the sole object to be stored in the returned list
Returns:
an immutable list containing only the specified object

static Map::View singletonMap ( Object::View  vKey,
    Object::Holder  ohValue 
  )    [static]

Returns an immutable map, mapping only the specified key to the specified value.

Parameters:
 vKey the sole key to be stored in the returned map
 ohValue the value to which the returned map maps key
Returns:
an immutable map containing only the specified key-value mapping

static Map::Handle synchronizedMap ( Map::Handle  hMap  )  [static]

Returns a synchronized (thread-safe) map backed by the specified map.

In order to guarantee serial access, it is critical that all access to the backing map is accomplished through the returned map.

It is imperative that the user manually synchronize on the returned map when iterating over any of its collection views:

  Map::Handle m = Collections::synchronizedMap(HashMap::create());
      ...
  Set::View s = m->keySet();     // Needn't be in synchronized block
      ...
  synchronized(m) {              // Synchronizing on m, not s!
      // Must be in synchronized block
      Iterator::Handle i = s->iterator();
      while (i->hasNext())
          foo(i->next());
  }
 
Failure to follow this advice may result in non-deterministic behavior.

Parameters:
 hMap the map to be synchronized
Returns:
an synchronized wrapper for a map

static Map::View synchronizedMap ( Map::View  vMap  )  [static]

Returns a synchronized (thread-safe) map backed by the specified map.

Parameters:
 vMap the map to be synchronized
Returns:
an synchronized wrapper for a map

static SortedMap::Handle synchronizedSortedMap ( SortedMap::Handle  hSortedMap  )  [static]

Returns a synchronized (thread-safe) sorted map backed by the specified sorted map.

In order to guarantee serial access, it is critical that all access to the backing sorted map is accomplished through the returned sorted map (or its views).

It is imperative that the user manually synchronize on the returned sorted map when iterating over any of its collection views, or the collections views of any of its subMap, headMap or tailMap views.

  SortedMap::Handle m = Collections::synchronizedSortedMap(
          TreeMap::create());
      ...
  Set::View s = m->keySet();  // Needn't be in synchronized block
      ...
  synchronized(m) {           // Synchronizing on m, not s!
      // Must be in synchronized block
      Iterator::Handle i = s->iterator();
      while (i->hasNext())
          foo(i->next());
  }
 
or:
  SortedMap::Handle m = Collections::synchronizedSortedMap(
          TreeMap::create());
  SortedMap::Handle m2 = m->subMap(foo, bar);
      ...
  Set::View s2 = m2->keySet();  // Needn't be in synchronized block
      ...
  synchronized(m) {             // Synchronizing on m, not m2 or s2!
       // Must be in synchronized block
      Iterator::Handle i = s->iterator();
      while (i->hasNext())
          foo(i->next());
  }
 
Failure to follow this advice may result in non-deterministic behavior.

Parameters:
 hSortedMap the sorted map to be synchronized
Returns:
an synchronized wrapper for a sorted map

static SortedMap::View synchronizedSortedMap ( SortedMap::View  vSortedMap  )  [static]

Returns a synchronized (thread-safe) map backed by the specified sorted map.

Parameters:
 vSortedMap the sorted map to be synchronized
Returns:
an synchronized wrapper for a sorted map

static Collection::Handle unmodifiableCollection ( Collection::View  vCollection  )  [static]

Returns an unmodifiable view of the specified collection.

This method allows modules to provide users with "read-only" access to internal collections. Query operations on the returned collection "read through" to the specified collection, and attempts to modify the returned collection, whether direct or via its iterator, result in an UnsupportedOperationException.

The returned collection does not pass the hashCode and equals operations through to the backing collection, but relies on Object's equals and hashCode methods. This is necessary to preserve the contracts of these operations in the case that the backing collection is a set or a list.

Parameters:
 vCollection the collection for which an unmodifiable view is to be returned.
Returns:
an unmodifiable view of the specified collection.

static Set::Handle unmodifiableSet ( Set::View  vSet  )  [static]

Returns an unmodifiable view of the specified set.

This method allows modules to provide users with "read-only" access to internal sets. Query operations on the returned set "read through" to the specified set, and attempts to modify the returned set, whether direct or via its iterator, result in an UnsupportedOperationException.

Parameters:
 vSet the set for which an unmodifiable view is to be returned.
Returns:
an unmodifiable view of the specified set.

static Set::View emptySet (  )  [static]

Returns an unmodifiable view of an empty set.

Returns:
an unmodifiable view of an empty set.

static Map::View emptyMap (  )  [static]

Returns an unmodifiable view of an empty map.

Returns:
an unmodifiable view of an empty map.

static void toStream ( std::ostream &  out,
    Iterator::Handle  hIter 
  )    [static]

Write out the contents of a Iterator.

Parameters:
 out the stream to write the Iterator to
 hIter the Iterator to write

static void toStream ( std::ostream &  out,
    Collection::View  vCol 
  )    [static]

Write out the contents of a Collection.

Parameters:
 out the stream to write the Collection to
 vCol the Collection to write

static void toStream ( std::ostream &  out,
    Map::View  vMap 
  )    [static]

Write out the contents of a Map.

Parameters:
 out the stream to write the Map to
 vCol the Map to write

static void toStream ( std::ostream &  out,
    Map::Entry::View  vEntry 
  )    [static]

Write out the contents of a Entry.

Parameters:
 out the stream to write the Entry to
 vEntry the Entry to write

static ObjectArray::Handle toArray ( Collection::View  vCol,
    ObjectArray::Handle  hao = NULL 
  )    [static]

Return the contents of the collection as an ObjectArray.

If the collection fits in the specified array, it is returned, otherwise, a new array is allocated that is the size of this collection.

If the collection fits in the array with aditional room then the element in the array immediately following the end of the collection is set to NULL. This can be useful in determining the length of this collection if the caller knows that the collection does not contain any NULL elements.

Parameters:
 vCol the Collection to turn into an array
 hao an array in which to store the collection's contents
Returns:
a ObjectArray containing all the elements of the collection in the same order as returned by the collection's Iterator
See also:
Iterator


The documentation for this class was generated from the following file:
Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.