Interface COM.odi.coll.Dictionary_String

public interface Dictionary_String

extends Bag

See Also:

Collection, Bag

DONT_MAINTAIN_CARDINALITY

This behavior flag indicates that the dictionary does not keep track of its own cardinality (the number of elements in the collection) by increasing and decreasing a counter when elements are inserted and deleted.

SIGNAL_DUP_KEYS

This behavior flag indicates that duplicate keys are not allowed in the dictionary.

contains(String, Object)

Indicates whether or not there is at least one element in the dictionary that has the specified key and value.

countValues(String)

Obtains the number of entries in the dictionary that have the specified key.

insert(String, Object)

Inserts an element with the specified key value into the dictionary.

pick(String)

Obtains an element that has the specified key in the dictionary.

remove(String, Object)

Removes an element from the dictionary, with exactly the specified key and value.

removeValue(String, int)

Removes n entries from the dictionary that have the given key.

retrieveKey(Cursor)

Obtains the key associated with the element that the cursor is positioned at.

set(Dictionary_String)

Sets the contents of this dictionary to be the same as the contents of otherDictionary.

  public final static int SIGNAL_DUP_KEYS

This behavior flag indicates that duplicate keys are not allowed in the dictionary. When SIGNAL_DUP_KEYS is specified, an attempt to insert an element with a key that is already present throws DuplicateKeyException. The default is that it is okay for two distinct elements in a dictionary to have the same key.

  public final static int DONT_MAINTAIN_CARDINALITY

This behavior flag indicates that the dictionary does not keep track of its own cardinality (the number of elements in the collection) by increasing and decreasing a counter when elements are inserted and deleted. The reason for not maintaining the cardinality is to improve the concurrency behavior of insertions and deletions. An attempt to obtain the cardinality computes the cardinality by counting the elements. You can use the cardinalityEstimate() and updateCardinality() methods to obtain and update approximations of the cardinality.

  public abstract void insert(String k,
                              Object o)

Inserts an element with the specified key value into the dictionary. If there is already an element in the dictionary with the same key and the same value, this method does nothing.

Parameters:

k - The key of the element to be inserted.

o - The element to insert.

Throws: DuplicateKeyException

If the dictionary has SIGNAL_DUP_KEYS behavior and some element of the dictionary already has this key.

Throws: ModifyTransientCollectionException

If the collection is transient.

Throws: NullPointerException

If the element is null.

Throws: ObjectNotExportedException

If the collection and the key, or the collection and the value being inserted, are in different segments and the item is not exported.

Throws: ObjectNotPersistenceCapableException

If the object is not persistence-capable.

  public abstract void remove(String k,
                              Object o)

Removes an element from the dictionary, with exactly the specified key and value. If there is no element with this key and value, this method does nothing.

Parameters:

k - The key of the element to be removed.

o - The element to remove.

Throws: ModifyTransientCollectionException

If the collection is transient.

  public abstract Object removeValue(String k,
                                     int n)

Removes n entries from the dictionary that have the given key. If there are fewer than n such entries, remove all of them. If there are no such entries, this method does nothing.

Returns:

One of the elements that was removed, or null if no element was removed.

Throws: ModifyTransientCollectionException

If the collection is transient.

  public abstract int countValues(String k)

Obtains the number of entries in the dictionary that have the specified key.

Parameters:

k - The key for which you want to know how many elements there are.

Returns:

The number of elements with the specified key.

  public abstract boolean contains(String k,
                                   Object o)

Indicates whether or not there is at least one element in the dictionary that has the specified key and value.

Parameters:

k - The key that you are inquiring about.

o - The element value that you are inquiring about.

Returns:

True if there is at least one element in the dictionary with the specified key and value. False if otherwise.

  public abstract String retrieveKey(Cursor c)

Obtains the key associated with the element that the cursor is positioned at. It is your responsibility to ensure that the cursor is valid.

Parameters:

c - The cursor for which you want the current key.

Returns:

The key associated with the pointed-to element.

Throws: NullCursorException

If the cursor is null.

  public abstract Object pick(String key)

Obtains an element that has the specified key in the dictionary. If there is more than one such element, this method picks an arbitrary one. If there is no such element and the dictionary has PICK_FROM_EMPTY_RETURNS_NULL behavior, this method returns null. If there is no such element and the dictionary does not have PICK_FROM_EMPTY_RETURNS_NULL behavior, this method throws NoSuchElementException.

Parameters:

key - The key to search for.

Throws: NoSuchElementException

If the key is not found and PICK_FROM_EMPTY_RETURNS_NULL behavior is on.

  public abstract void set(Dictionary_String otherDictionary)

Sets the contents of this dictionary to be the same as the contents of otherDictionary. ObjectStore makes the dictionary empty, and then inserts each of the elements of otherDictionary into the collection.

Parameters:

otherDictionary - The dictionary whose elements you want to place in this dictionary.

Throws: ModifyTransientCollectionException

If this dictionary is transient.

Throws: ObjectNotExportedException

If there are objects in otherDictionary that are not exported and are stored in a different segment from this dictionary.