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
 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.

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.

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.

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.

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.

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).

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.

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).

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.

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.

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.

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