com.wm.data

Interface IDataSharedCursor

public interface IDataSharedCursor

A single instance of IDataSharedCursor cannot be accessed concurrently from multiple different threads. A single instance of IData can be accessed concurrently from multiple different threads, provided that the IData has a threadsafe implementation and that each thread has its own cursor. If any method of IDataSharedCursor throws a DataException, both the cursor's position and the IData underlying the cursor will not have been changed as a result of the method call. Both the IData and the cursor will remain valid and usable after the exception is thrown.

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.
IDataSharedCursor	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 the key in the key/value pair on which the cursor is currently positioned.
java.lang.Object	getValue() Returns the value of the key/value pair on which the cursor is currently positioned.
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).
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.
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	setKey(java.lang.String key) Sets the key of the key/value pair on which the cursor is currently positioned.
void	setValue(java.lang.Object value) Sets the value of the key/value pair on which the cursor is currently positioned.

Method Detail

getKey

java.lang.String getKey()
                 throws DataException

Returns the key in the key/value pair on which the cursor is currently positioned. If the cursor has not yet been positioned with one of the cursor's positioning methods (e.g., next, previous, first), getKey> throws a DataException.

Returns:

A String containing the key of a key/value pair. In some implementations of IData it may be acceptable for the key of a key/value pair to be null. A null return never signifies an empty IData, since the method throws an exception when the IData is empty.

Throws:

DataException

See Also:

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

getValue

java.lang.Object getValue()
                   throws DataException

Returns the value of the key/value pair on which the cursor is currently positioned. If the cursor was not previously positioned on a key/value pair via another cursor method, getValue throws a DataException.

Returns:

An Object containing the value of a key/value pair. In some implementations of IData it may be acceptable for the value of a key/value pair to be null. A null return never signifies an empty IData, since the method throws an exception when the IData is empty.

Throws:

DataException

See Also:

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

setKey

void setKey(java.lang.String key)
     throws DataException

Sets the key of the key/value pair on which the cursor is currently positioned. If the cursor has not yet been positioned with one of the cursor's positioning methods (e.g., next, previous, first), setKey throws a DataException.

setKey will also throw a DataException if an IData implementation adheres to a particular schema and the action performed by setKey violates the schema.

Parameters:

key - a String that specifies the new key.

Throws:

DataException

See Also:

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

setValue

void setValue(java.lang.Object value)
       throws DataException

Sets the value of the key/value pair on which the cursor is currently positioned. If the cursor has not yet been positioned with one of the cursor's positioning methods (e.g., next, previous, first), setValue throws a DataException.

setValue will also throw a DataException if an IData implementation adheres to a particular schema and the action performed by setValue violates the schema.

Parameters:

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

Throws:

DataException

See Also:

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

delete

boolean delete()
        throws DataException

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 throws a DataException. 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 will throw a DataException.
  
  
• 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 throws a DataException. 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, throw a DataException on attempting to delete the outer IData. The actual behavior depends 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.)

Throws:

DataException

insertBefore

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

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 very 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 will throw a DataException.
  
  

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.

Throws:

DataException

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)
          throws DataException

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 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 will throw a DataException.
  
  

Parameters:

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

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

Throws:

DataException

See Also:

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

insertDataBefore

IData insertDataBefore(java.lang.String key)
                throws DataException

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 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 will throw a DataException.
  
  

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.

Throws:

DataException

See Also:

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

insertDataAfter

IData insertDataAfter(java.lang.String key)
               throws DataException

Inserts a new key/value pair immediately after 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 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.

• After inserting the new key/value pair, insertDataBefore positions the cursor on the new pair.
  
  
• 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 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 will throw a DataException.
  
  

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.

Throws:

DataException

See Also:

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

next

boolean next()
      throws DataException

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.

Throws:

DataException

See Also:

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

next

boolean next(java.lang.String key)
      throws DataException

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.

Throws:

DataException

See Also:

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

previous

boolean previous()
          throws DataException

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.

Throws:

DataException

See Also:

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

previous

boolean previous(java.lang.String key)
          throws DataException

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.

Throws:

DataException

See Also:

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

first

boolean first()
       throws DataException

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.

Throws:

DataException

See Also:

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

first

boolean first(java.lang.String key)
       throws DataException

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.

Throws:

DataException

See Also:

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

last

boolean last()
      throws DataException

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.

Throws:

DataException

See Also:

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

last

boolean last(java.lang.String key)
      throws DataException

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.

Throws:

DataException

See Also:

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

hasMoreData

boolean hasMoreData()
             throws DataException

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.

Throws:

DataException

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.

getCursorClone

IDataSharedCursor getCursorClone()
                          throws DataException

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 IDataSharedCursor initialized to the same position as the current cursor.

Throws:

DataException