jdsl.core.api
Interface OrderedDictionary
- All Known Implementing Classes:
- RBTree
- public abstract interface OrderedDictionary
- extends Dictionary
A Dictionary in which the keys are totally ordered. That is, given a set of
keys, S, where a and b are elements of S,
exactly one of the following properties holds:
This expansion of the Dictionary interface allows OrderedDictionaries to be
searched through sequentially.
- Author:
- John Kloss
|
Field Summary |
static Locator |
BOUNDARY_VIOLATION
Returned from all four methods of OrderedDictionary to
indicate that the user tried to go before the first element
of the dictionary or after the last. |
|
Method Summary |
Locator |
after(Locator locator)
Returns the Locator that is sequentially after another Locator in this
Container. |
Locator |
before(Locator locator)
Returns the Locator that is sequentially before another Locator in this
Container. |
Locator |
closestAfter(java.lang.Object key)
Returns a Locator whose key is sequentially greater than or
equal to the search key. |
Locator |
closestBefore(java.lang.Object key)
Returns a Locator whose key is sequentially less than or equal to
the search key. |
BOUNDARY_VIOLATION
public static final Locator BOUNDARY_VIOLATION
- Returned from all four methods of OrderedDictionary to
indicate that the user tried to go before the first element
of the dictionary or after the last. Note that dictionaries have
special values returned from lookup methods, rather than exceptions,
when the lookup fails.
before
public Locator before(Locator locator)
throws InvalidLocatorException,
UncontainedLocatorException
- Returns the Locator that is sequentially before another Locator in this
Container. If there is no such element then the returned Locator will
be invalid.
- Parameters:
locator - An abstract position in this Container.- Returns:
- A Locator which is sequentially before
locator. Note: this Locator will be
the invalid BOUNDARY_VIOLATION if no such locator exists. - Throws:
- InvalidLocatorException - If
locator is
invalid (For example: It does not actually reference
an element within this Container).
after
public Locator after(Locator locator)
throws InvalidLocatorException,
UncontainedLocatorException
- Returns the Locator that is sequentially after another Locator in this
Container. If there is no such element then the returned Locator will
be invalid.
- Parameters:
locator - An abstract position in this Container.- Returns:
- A Locator which is sequentially after
locator. Note: this Locator will be
the invalid BOUNDARY_VIOLATION if no such locator exists. - Throws:
- InvalidLocatorException - If
locator is
invalid (For example: It does not actually reference
an element within this Container).
closestBefore
public Locator closestBefore(java.lang.Object key)
throws InvalidKeyException,
UncontainedLocatorException
- Returns a Locator whose key is sequentially less than or equal to
the search key.
The key which is ordered before
key may have many Locators
mapped to it. Which one is closest to key is implementation
dependent. It is also possible that there are no such Locators
ordered before key, in which case, the Locator returned
will be invalid. Finally, it is possible that key
is actually present in the container, in which case a locator whose
key is equal to key will be returned.
- Parameters:
key - An abstract position in this Container.- Returns:
- The first Locator whose key is less than or
equal to
key in this Container. Note:
If no such Locator exists, the returned Locator will
be the invalid BOUNDARY_VIOLATION. - Throws:
- InvalidKeyException - If
key is not of
a type accepted by this Container (For example: The
key is not comparable).
closestAfter
public Locator closestAfter(java.lang.Object key)
throws InvalidKeyException,
UncontainedLocatorException
- Returns a Locator whose key is sequentially greater than or
equal to the search key.
The key which is ordered after
key may have many Locators
mapped to it. Which one is closest to key is implementation
dependent. It is also possible that there are no such Locators
ordered after key, in which case, the Locator returned
will be invalid. Finally, it is possible that key
is actually present in the container, in which case a locator whose
key is equal to key will be returned.
- Parameters:
key - An abstract position in this Container.- Returns:
- The first Locator whose key is greater than
or equal to
key in this Container. Note:
If no such Locator exists, the returned Locator will
be the invalid BOUNDARY_VIOLATION. - Throws:
- InvalidKeyException - If
key is not of
a type accepted by this Container (For example: The
key is not comparable).