Oracle Coherence for C++ API
Release 3.6.1.0
E18813-01

- Main Page
- Namespaces
- Classes
- Files

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# 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:

- coherence/util/Collections.hpp

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.