com.wm.data

Interface IDataCursor

All Known Subinterfaces:

IDataHashCursor, IDataIndexCursor, IDataTreeCursor

public interface IDataCursor

This interface defines the methods you use to access, traverse, and manipulate the contents of an IData object. It is returned by an IData object's getIDataCursor method.

An IDataCursor is used to traverse the key/value pairs in an IData object. The cursor starts out in an unpositioned' state, meaning that it is not resting on an element of the IData object. The first command to a cursor determines its initial position. For example, if you use the next, first, or insertBefore method on an unpositioned cursor, the cursor is moved to the first element in the IData object. Conversely, if you use the previous, last, or insertAfter method on an unpositioned cursor, the cursor is moved to the last element in the IData object.

Be aware that a single instance of IData can be accessed concurrently from multiple different threads as long as the IData has a thread-safe implementation or the application protects itself against different threads modifying the IData at the same time. Each thread must have its own cursor. Not all IData implementations need to be thread-safe.

The IDataCursor methods do not throw exceptions when errors occur. Instead, errors accumulate in an error storage that you can examine after you call the method. Any IDataCursor method is capable of generating an error. A method does not generate more than one error during a given call.

Note: Be aware that not all types of cursors generate errors, so if you are using one that does not generate errors, it is not necessary to check for errors after each method call. The documentation for a cursor will indicate whether or not it generates errors.

When a method generates an error, the state of the underlying IData object and the cursor's position are unchanged. The IData object and the cursor are valid and usable after the error occurs.

See Also:

IData, IDataFactory

Method Summary

Modifier and Type	Method and Description
boolean	delete() Removes the key/value pair at the cursor's current position and positions the cursor on the key/pair value that immediately follows the one you removed.
void	destroy() Discards this IData cursor.
boolean	first() Moves the cursor to the first key/value pair in the IData object.
boolean	first(java.lang.String key) Moves the cursor to the first key/value pair that has a specified key.
IDataCursor	getCursorClone() Returns a new cursor that is identical in state and type to the cursor on which you call this method.
java.lang.String	getKey() Returns a String object containing the key of the key/value pair at the cursor's current position.
DataException	getLastError() Returns the most recent cursor error.
java.lang.Object	getValue() Returns an Object containing the value of the key/value pair at the cursor's current position.
boolean	hasMoreData() Indicates whether the cursor is on the last element in the IData object (i.e., indicates whether next, if executed, would move the cursor successfully).
boolean	hasMoreErrors() Reports whether there are any errors in error storage.
void	insertAfter(java.lang.String key, java.lang.Object value) Inserts a new key/value pair immediately after the cursor's current position.
void	insertBefore(java.lang.String key, java.lang.Object value) Inserts a new key/value pair immediately before the cursor's current position and positions the cursor on the new pair.
IData	insertDataAfter(java.lang.String key) Inserts a new key/value pair immediately after the cursor's current position and positions the cursor on the new pair.
IData	insertDataBefore(java.lang.String key) Inserts a new key/value pair immediately before the cursor's current position.
boolean	last() Moves the cursor to the last key/value pair.
boolean	last(java.lang.String key) Moves the cursor to the last key/value pair that has a specified key.
boolean	next() Moves the cursor to the next key/value pair in the IData object (to the key/value pair that immediately follows the cursor's current position).
boolean	next(java.lang.String key) Moves the cursor to the next key/value pair that has a specified key.
boolean	previous() Moves the cursor to the previous key/value pair in the IData object (the pair that immediately precedes the cursor's current position).
boolean	previous(java.lang.String key) Moves the cursor to the previous key/value pair that has a specified key.
void	setErrorMode(int mode) Controls the behavior of error storage in cursors that are capable of generating errors.
void	setKey(java.lang.String key) Sets the key of the key/value pair at the cursor's current position to a specified String.
void	setValue(java.lang.Object value) Sets the value of the key/value pair at the cursor's current position.

Method Detail

setErrorMode

void setErrorMode(int mode)

Controls the behavior of error storage in cursors that are capable of generating errors. Two modes are supported:

• LAST stores only the most recent error.
• STACK stores a stack of the most recent errors in last-in-first-out order.

You may change the error mode at any point. When you change from LAST to STACK, if an error already exists in storage, that error becomes the oldest error in the stack. When you change from STACK to LAST, the current stack stays in memory until the next error occurs and the entire stack is replaced with the single error.

Parameters:

mode - an int specifying the error mode. Must be ERROR_MODE_LAST or ERROR_MODE_STACK.

getLastError

DataException getLastError()

Returns the most recent cursor error.

If the cursor's error mode is LAST, error storage will be emptied by this call. If the error mode is STACK, this method returns the most recent error and leaves it and all previous errors in storage.

Once an error has been retrieved, it cannot be retrieved again.

Returns:

An Exception representing an error or null if there are no errors in the cursor's error storage.

hasMoreErrors

boolean hasMoreErrors()

Reports whether there are any errors in error storage.

Returns:

true if a call to getLastError would return an error (a non-null value); false otherwise (i.e., a call to getLastError would return null).

getKey

java.lang.String getKey()

Returns a String object containing the key of the key/value pair at the cursor's current position. If the cursor has not yet been positioned with one of the cursor's positioning methods (e.g., next, previous, first), getKey generates an error (in cursors that generate errors) and returns null.

Note: This method might also return null if the key at the cursor position is null.

Returns:

A String containing the key at the cursor's current position or null if the cursor has not been positioned (or if the key itself is null).

See Also:

getValue(), setKey(java.lang.String)

getValue

java.lang.Object getValue()

Returns an Object containing the value of the key/value pair at the cursor's current position. If the cursor has not yet been positioned with one of the cursor's positioning methods (e.g., next, previous, first), getValue generates an error (in cursors that generate errors) and returns null.

Note: This method might also return null if the value at the cursor position is null.

Returns:

The value at the cursor's current position or null if the cursor has not been positioned (or if the value is itself null).

See Also:

getKey(), setValue(java.lang.Object)

setKey

void setKey(java.lang.String key)

Sets the key of the key/value pair at the cursor's current position to a specified String. If the cursor has not yet been positioned with one of the cursor's positioning methods (e.g., next, previous, first), setKey generates an error (in cursors that generate errors) and does nothing.

setKey will also generate an error (in cursors that generate errors) if an IData implementation adheres to a particular schema and the action performed by setKey violates the schema.

Note: When setKey generates an error, it makes no changes to the IData object.

Parameters:

key - a String that specifies the new key.

See Also:

setValue(java.lang.Object), getKey()

setValue

void setValue(java.lang.Object value)

Sets the value of the key/value pair at the cursor's current position. If the cursor has not yet been positioned with one of the cursor's positioning methods (e.g., next, previous, first), setValue generates an error (in cursors that generate errors) and does nothing.

setValue will also generate an error (in cursors that generate errors) if an IData implementation adheres to a particular schema and the action performed by setValue violates the schema.

Note: When setValue generates an error, it makes no changes to the IData object.

Parameters:

value - an Object that represents the value to be assigned at the current cursor position.

See Also:

setKey(java.lang.String), getValue()

delete

boolean delete()

Removes the key/value pair at the cursor's current position and positions the cursor on the key/pair value that immediately follows the one you removed.

• If no key/value pair follows the one you removed, but one precedes it, the cursor is positioned on that pair.
  
  
• If you remove the last remaining key/value pair in the IData object, the cursor reverts to an unpositioned state and remains unpositioned until you call a method that explicitly repositions it.
  
  
• If the cursor has not yet been positioned with one of the cursor's positioning methods (e.g., next, previous, first) or the IData object is empty, delete generates an error (in cursors that generate errors). The IData object is not altered.
  
  
• If an IData implementation adheres to a particular schema and the action performed by delete violates the schema, delete generates an error (in cursors that generate errors).
  
  
• If multiple cursors have been created for the same underlying IData, you will not be permitted to delete the key/value pair on which another cursor is positioned. If you attempt to do this, delete generates an error (in cursors that generate errors) and does nothing. The IData object is not altered.
  
  
• If one IData is nested within another IData and cursors exist for both IData instances, delete may, but need not, generate an error on attempting to delete the outer IData. The actual behavior will depend on the implementation of the outer IData and on whether the cursor is one that generates errors.
  
  

Returns:

true if a key/value pair was deleted and the cursor was moved to the following pair; false for all other cases (for example, the deleted pair had no elements following it so the cursor was positioned on the preceding pair or the deleted pair was the last remaining element in the IData object).

See Also:

insertBefore(java.lang.String, java.lang.Object), insertAfter(java.lang.String, java.lang.Object)

insertBefore

void insertBefore(java.lang.String key,
                  java.lang.Object value)

Inserts a new key/value pair immediately before the cursor's current position and positions the cursor on the new pair.

• If the IData object is not empty and the cursor has not yet been positioned, insertBefore adds the new name/value pair to the beginning of the IData object (the new key/value pair becomes the first key/value pair in the IData object).
  
  
• If the IData object is empty, insertBefore adds the new key/value pair to the empty IData object and positions the cursor on that name/value pair.
  
  
• If an IData implementation adheres to a particular schema and the action performed by insertBefore violates the schema, insertBefore generates an error (in cursors that generate errors).
  
  

Parameters:

key - a String that specifies the name of the key in the new key/value pair.

value - the Object that you want insertBefore to assign to the new key/value pair.

See Also:

insertDataBefore(java.lang.String), insertAfter(java.lang.String, java.lang.Object), delete()

insertAfter

void insertAfter(java.lang.String key,
                 java.lang.Object value)

Inserts a new key/value pair immediately after the cursor's current position. After inserting the new key/value pair, insertAfter positions the cursor on the new pair.

• If the IData object is not empty and the cursor has not yet been positioned, insertAfter adds the new name/value pair to the end of the IData object (the new key/value pair becomes the very last key/value pair in the IData object).
  
  
• If the IData object is empty, insertAfter adds the new key/value pair to the empty IData object and positions the cursor on that name/value pair.
  
  
• If an IData implementation adheres to a particular schema and the action performed by insertAfter violates the schema, insertAfter generates an error (in cursors that generate errors).
  
  

Parameters:

key - a String that specifies the name of the key for the new key/value pair.

value - the Object that you want insertAfter to assign to the new key/value pair.

See Also:

insertDataAfter(java.lang.String), insertBefore(java.lang.String, java.lang.Object), delete()

insertDataBefore

IData insertDataBefore(java.lang.String key)

Inserts a new key/value pair immediately before the cursor's current position. With this method, you specify only the key. The method provides the value, which is an object implementing the IData interface whose concrete class varies according to the concrete class of the IData object you are working with. This method supports the situation where the IData instance you are working with has to manage relationships among its constituent IData instances, and requires that a child IData instance be created in the context of a parent. It also supports the case where the IData instance can contain only IData instances of a particular concrete class, and the caller does not know or have access to the class.

After inserting the new key/value pair, insertDataBefore positions the cursor on the new pair.

• If the IData object is empty, insertDataBefore adds the new key/value pair to the empty IData object and positions the cursor on that name/value pair.
  
  
• If the IData object is not empty and the cursor has not yet been positioned, insertDataBefore adds the new name/value pair to the beginning of the IData object (the new key/value pair becomes the very first key/value pair in the IData object).
  
  
• If an IData implementation adheres to a particular schema and the action performed by insertDataBefore violates the schema, insertDataBefore generates an error (in cursors that generate errors).
  
  

Parameters:

key - a String that specifies the name of the key for the new key/value pair.

Returns:

An IData instance. This instance may be unpopulated, partially populated, or completely populated with key/value pairs, as governed by schema requirements and default behavior. Returns null when the method generates an error.

See Also:

insertBefore(java.lang.String, java.lang.Object), insertDataAfter(java.lang.String), delete()

insertDataAfter

IData insertDataAfter(java.lang.String key)

Inserts a new key/value pair immediately after the cursor's current position and positions the cursor on the new pair.

With this method, you specify only the key. The method provides the value, which is an object implementing the IData interface whose concrete class varies according to the concrete class of the IData object you are working with. This method supports the situation where the IData instance you are working with has to manage relationships among its constituent IData instances, and requires that a child IData instance be created in the context of a parent. It also supports the case where an IData instance can contain only IData instances of a particular concrete class, and the caller does not know or have access to the class.

• If the IData object is empty, insertDataAfter adds the new key/value pair to the empty IData object and positions the cursor on that name/value pair.
  
  
• If the IData object is not empty and the cursor has not yet been positioned, insertDataAfter adds the new name/value pair to the beginning of the IData object (the new key/value pair becomes the very first key/value pair in the IData object).
  
  
• If an IData implementation adheres to a particular schema and the action performed by insertDataAfter violates the schema, insertDataAfter generates an error (in cursors that generate errors.
  
  

Returns:

an IData instance. This instance may be unpopulated, partially populated, or completely populated with key/value pairs, as governed by schema requirements and default behavior. Returns null when the method generates an error.

See Also:

insertAfter(java.lang.String, java.lang.Object), insertDataBefore(java.lang.String), delete()

next

boolean next()

Moves the cursor to the next key/value pair in the IData object (to the key/value pair that immediately follows the cursor's current position).

• If the cursor is unpositioned and the IData object contains at least one key/value pair, next puts the cursor on the first element and returns true.
  
  
• If the cursor is already on the last element in the IData object, the cursor position remains unchanged and next returns false.
  
  
• If the IData object is empty, the cursor remains unpositioned and next returns false.
  
  

Returns:

true if the cursor was successfully moved to the next element in IData; false otherwise.

See Also:

next(), previous(String), first(String), last(String)

next

boolean next(java.lang.String key)

Moves the cursor to the next key/value pair that has a specified key.

Note: This method will not return the current key/value pair even if that pair has the proper key. It returns only a key/value pair that both follows the pair at the cursor's current position and has the key you specify.

• If the cursor has not yet been positioned within the IData object and the IData object contains at least one key/value pair matching the specified key, next puts the cursor on that element and returns true.
  
  
• If the cursor is already on the last key/value pair in the IData object, or if there are no subsequent pairs with the specified key, the cursor position remains unchanged and next returns false.
  
  
• If the IData object is empty, or if the IData object has no key/value pairs with the specified key, the state of the cursor remains unchanged and next returns false.
  
  

Parameters:

key - a String that specifies the name of the key to which you want the cursor moved. This parameter is case sensitive. The value you specify must match the key name exactly. A null parameter will match a key/value pair whose key is null.

Returns:

true if the cursor was successfully moved to an element with the specified key; false otherwise.

See Also:

next(), previous(String), first(String), last(String)

previous

boolean previous()

Moves the cursor to the previous key/value pair in the IData object (the pair that immediately precedes the cursor's current position).

• If the cursor is unpositioned and the IData object contains at least one key/value pair, previous moves the cursor to the last pair in the IData object and returns true.
  
  
• If the cursor is already on the first element in the IData object, the cursor position remains unchanged and previous returns false.
  
  
• If the IData object is empty, the cursor remains unpositioned and previous returns false.
  
  

Returns:

true if the cursor was successfully moved to the previous element in IData; false otherwise.

See Also:

previous(String), next(), first(), last()

previous

boolean previous(java.lang.String key)

Moves the cursor to the previous key/value pair that has a specified key.

Note: This method never returns the current key/value pair even if that pair has the specified key. It returns only a key/value pair that both follows the pair at the cursor's current position and has the key you specify.

• If the cursor is unpositioned and the IData object contains at least one key/value pair matching the specified key, previous moves the cursor to that element and returns true.
  
  
• If the cursor is already on the first key/value pair in the IData object, or if there are no preceding pairs with the specified key, the cursor position remains unchanged and previous returns false.
  
  
• If the IData object is empty, or if the IData object has no key/value pairs with the specified key, the state of the cursor remains unchanged and previous returns false.
  
  

Parameters:

key - a String that specifies the name of the key to which you want the cursor moved. This parameter is case-sensitive. The value you specify must match the key name exactly. A null parameter will match a key/value pair whose key is null.

Returns:

true if the cursor was successfully moved to an element with the specified key; false otherwise.

See Also:

previous(), next(String), first(String), last(String)

first

boolean first()

Moves the cursor to the first key/value pair in the IData object. If the object contains no key/value pairs, the cursor remains unpositioned and first returns false.

Returns:

true if the cursor was moved to the first key/value pair in the IData object; false otherwise.

See Also:

first(String), last(), next(), previous()

first

boolean first(java.lang.String key)

Moves the cursor to the first key/value pair that has a specified key.

• If the cursor is unpositioned and the IData object contains at least one key/value pair matching the specified key, first moves the cursor to that element and returns true.
  
  
• If the IData object is empty, or has no key/value pairs matching the specified key, the state of the cursor remains unchanged and first returns false.
  
  

Parameters:

key - a String that specifies the name of the key to which you want the cursor moved. This parameter is case sensitive. The value you specify must match the key name exactly. A null parameter will match a key/value pair whose key is null.

Returns:

true if the cursor was successfully moved to an element with the specified key; false otherwise.

See Also:

first(), last(String), next(String), previous(String)

last

boolean last()

Moves the cursor to the last key/value pair. If there are no entries in the IData object, the cursor remains unpositioned and last returns false.

Returns:

true if the cursor was successfully moved to the last key/value pair; false otherwise.

See Also:

last(String), first(), next(), previous()

last

boolean last(java.lang.String key)

Moves the cursor to the last key/value pair that has a specified key.

• If the cursor is unpositioned and the IData object contains at least one key/value pair matching the specified key, last puts the cursor on that element and returns true.
  
  
• If the IData object is empty, or has no key/value pairs matching the specified key, the state of the cursor remains unchanged and last returns false.
  
  

Parameters:

key - a String that specifies the name of the key to which you want the cursor moved. This parameter is case sensitive. The value you specify must match the key name exactly. A null parameter will match a key/value pair whose key is null.

Returns:

true if the cursor was successfully moved to an element with the specified key; false otherwise.

See Also:

last(), first(String), next(String), previous(String)

hasMoreData

boolean hasMoreData()

Indicates whether the cursor is on the last element in the IData object (i.e., indicates whether next, if executed, would move the cursor successfully).

Note: This method basically returns the same value as next would if it were called and it did not generate an error.

Note: Although the status returned by hasMoreData indicates the status that next would return if it were executed, the presence or absence of an error after hasMoreData is not an indication of whether next will produce an error. You cannot use the error status from hasMoreData to predict whether or not next

Returns:

true if there is at least one more element beyond the cursor's current position; false if the cursor is pointing to the last element or the object contains no key/value pairs at all.

See Also:

next()

destroy

void destroy()

Discards this IData cursor. You should always explicitly discard (destroy) a cursor when you are finished using it, even though the Java garbage collector will do this if you neglect to do so. Explicitly destroying the cursor will provide more efficient performance.

Note: If you are using webMethods standard IData implementation, the cursor is returned to a cache when you destroy it, so the object does not need to be recreated the next time the getCursor method is called.

See Also:

getCursorClone()

getCursorClone

IDataCursor getCursorClone()

Returns a new cursor that is identical in state and type to the cursor on which you call this method. The new cursor operates on the same IData object. A copy of the current cursor is useful for saving the current cursor position (similar to "bookmarking" that position).

Note:The cursor position in a clone is completely independent from the cursor position in the cursor from which it was copied and form cursor clones that you create. When you change the position of the cursor in one clone, you do not affect the cursor positions in the others.

Returns:

A copy of IDataCursor initialized to the same position as the current cursor.