Collection Class Library Exceptions

This file contains information about the following subjects:

• Exceptions Defined and Used by the Collection Classes
• Exception Causes
• Exceptions Caused by System Failures and Restrictions

Exceptions Defined and Used by the Collection Classes

The exceptions defined and used in the Collection Class Library are shown in the table below (classes defined by the Collection Class Library are shown in bold). They all derive from IException, directly or indirectly.

Hierarchy of Exceptions Defined and Used by the Collection Classes

IException
   ICollectionResourceException
   ICollectionLockException
   ICollectionUnlockException
   ICollectionLockTimeOutException*
   IPreconditionViolation
      IChildAlreadyExistsException
      ICursorInvalidException
      IEmptyException
      IFullException
      IIdenticalCollectionException
      InvalidReplacementException
      IKeyAlreadyExistsException
      INotBoundedException
      INotContainsKeyException
      IPositionInvalidException
      IRootAlreadyExistsException
   IResourceExhausted
      IOutOfMemory

*not on .

Exception Causes

A precondition of a called function is a condition that the function requires to be true when it is called. The calling function must assure that this condition holds. The called function implementation may assume that the condition holds without further checking it. If a precondition does not hold, the called function's behavior is undefined.

If you want to make your programs more robust and to locate errors in the test phase, the functions your program calls should check to ensure that their preconditions hold. The Collection Class Library enables this checking through macro definitions. Because this checking often requires significant overhead, it is turned off by default. You need only use it while you are testing the system and verifying that preconditions are always met.

A call to a function that violates the function's preconditions has two possible results:

• If the called function checks its preconditions, the function will throw an exception.
• If the function does not check its preconditions, the behavior of the function is undefined.

Precondition-Violations

The Collection Classes include the following precondition-violation exceptions:

• IChildAlreadyExistsException--Occurs when you try to add a child to a tree using addAsChild at a position that already contains a child.
• ICursorInvalidException--Two cursor properties may lead to the ICursorInvalidException:

  1. Every time a cursor is created, you must specify the collection that it belongs to. If a function takes a cursor as an argument (such as add, setToFirst, and locate), the function can only be applied to the collection that the cursor belongs to. If the function is applied to another collection, the ICursorInvalidException results.

  2. If a function takes a cursor as an input argument (such as elementAt, removeAt, and replaceAt), the cursor must be valid. A cursor is valid if it actually refers to some element contained in the collection. You can use the isValid function to determine if a cursor is valid.

• IEmptyException--Occurs when a function tries to access an element of an empty collection. Functions that might cause this exception include firstElement and removeFirstElement.
• IFullException--Occurs when a function tries to add an element to a bounded collection that is already full. Functions that might cause this exception include add and addAsFirst.
• IIdenticalCollectionException--Occurs when the function addAllFrom is called with the source collection being the same as the target collection.
• IInvalidReplacementException--Occurs when, during a replaceAt function, the replacing element has different positioning properties than the positioning properties of the element to be replaced.
• IKeyAlreadyExistsException--Occurs when a function attempts to add an element to a map or sorted map that already has a different element with the same key. Functions that might cause this exception include add and addAllFrom.
• INotBoundedException--Occurs when the function maxNumberOfElements() is applied to a collection that is not bounded.
• INotContainsKeyException--Occurs when the function elementWithKey is applied to a collection that does not contain an element with the specified key.

Other Exceptions

The following lists the causes of the other exceptions defined or used by the Collection Classes:

• IOutOfMemory--Occurs when a function cannot obtain the space that it requires. This exception is not the result of a precondition violation. Functions that add an element to a collection, including add and addAsFirst, can cause this exception.
• IPositionInvalidException--Occurs when a function specifies a position that is not valid in a collection. The functions that might cause this exception include elementAtPosition, removeAtPosition, and setToPosition.
• IRootAlreadyExistsException--Occurs when the function addAsRoot is called for a tree that already has a root.
• ICollectionResourceException--Occurs when the Collection is constructed and the creation of the internal Resource object fails.
• ICollectionLockException--Occurs when an internal lock request fails.
• ICollectionUnlockException--Occurs when an internal unlock request fails.
• ICollectionLockTimeOutException--Occurs when a time-out value is specified during the construction of a Guard object and the lock cannot be obtained within the specified period of time.

Exceptions Caused by System Failures and Restrictions

System failures and restrictions are different from precondition violations. You cannot usually anticipate them, and you have no opportunity to verify that such situations, for example storage overflow, will not occur. These exceptions need to be checked for, and an exception should be thrown if they occur.

Introduction to the Collection Classes
Collection Characteristics
Adding Elements
Removing Elements
Replacing Elements
Thread Safety and the Collection Classes

Enabling Exception Checking
Implementing Bounded Collections
Guard Objects
Instantiating a Guard Object
Using Guard Objects
Adding an Element to a Collection
Removing an Element from a Collection
Using Cursors to Locate and Access Elements
Using Cursors to Iterate Over a Collection
Using allElementsDo and Applicators to Iterate Over a Collection
Cursors vs. Exception Handling
Instantiating the Collection Classes