Enterprise Information Portal APIs

com.ibm.mm.sdk.common
Interface dkResultSetCursor

All Known Subinterfaces:
dkResultSetCursorScrollable
All Known Implementing Classes:
dkAbstractResultSetCursor

public interface dkResultSetCursor

dkResultSetCursor is a datastore cursor that manages a collection of DDO objects. The collection contains the results of a query submitted to the datstore. Elements are not added to the collection until a datastore fetch operation is executed.

dkResultSetCursor is an interface that requires a specific implementation for the target datastore. For example:

To enable the use of the addObject, deleteObject, or updateObject methods, you must set the datastore option DK_CM_OPT_ACCESS_MODE to DK_CM_READWRITE for those datastore that are not read only and support this function.


Method Summary
 void addObject(DKDDO ddo)
          Adds an element to the datastore
 int cardinality()
          Gets the number of query results if supported.
 void close()
          Close the cursor and invalidates the result set.
 java.lang.String datastoreName()
          Gets the datastore name
 java.lang.String datastoreType()
          Gets the datastore type
 void deleteObject()
          Deletes element at the current cursor position from the datastore
 void destroy()
          Destroys the cursor.
 DKDDO fetchNext()
          Sets cursor to point to the position of the next data object and fetches the element in the cursor at that position
 java.lang.Object fetchNextByName(java.lang.String dataItemName)
          Sets cursor to point to the position of the next data object and fetches the data item value in the cursor at that position by data item name.
 boolean fetchNextN(int how_many, dkCollection collection)
          Fetches the next N elements of the cursor and inserts them into the given collection
 boolean fetchNextNByName(java.lang.String dataItemName, int how_many, java.lang.Object[] array)
          Fetches the next N data item values of the cursor and inserts them into the given array
 DKDDO fetchObject()
          Fetches the element in the cursor at the current position
 java.lang.Object fetchObjectByName(java.lang.String dataItemName)
          Fetches the data item value in the cursor at the current position by data item name
 DKDDO findObject(int position, java.lang.String predicate)
          Deprecated. No replacement
 int getPosition()
          Gets the current cursor position
 DKHandle handle(int type)
          Deprecated. Replace by handle(String type)
 DKHandle handle(java.lang.String type)
          Gets a cursor handle
 boolean isBegin()
          Begin indicator
 boolean isEnd()
          End indicator
 boolean isInBetween()
          Between data objects in cursor indicator
 boolean isOpen()
          Open indicator
 boolean isScrollable()
          Scrollable indicator
 boolean isUpdatable()
          Updatable indicator
 boolean isValid()
          Valid indicator
 DKDDO newObject()
          Constructs a new DDO of the same type as the items in the result
 java.lang.String objectType()
          Gets the cursor object type
 void open()
          Opens the cursor.
 void open(DKNVPair[] parms)
          Opens the cursor.
 void setPosition(int position, java.lang.Object value)
          Sets the cursor position
 void setToNext()
          Sets cursor to point to the position of the next data object in the cursor
 void updateObject(DKDDO ddo)
          Updates element at the current cursor position from the datastore
 

Method Detail

isScrollable

public boolean isScrollable()
                     throws DKException,
                            java.lang.Exception
Scrollable indicator
Returns:
true if cursor can be scrolled forward and backward

isUpdatable

public boolean isUpdatable()
                    throws DKException,
                           java.lang.Exception
Updatable indicator
Returns:
true if cursor is updatable

isValid

public boolean isValid()
                throws DKException,
                       java.lang.Exception
Valid indicator
Returns:
true if cursor is valid

isOpen

public boolean isOpen()
               throws DKException,
                      java.lang.Exception
Open indicator
Returns:
true is cursor is in an opened state

isBegin

public boolean isBegin()
                throws DKException,
                       java.lang.Exception
Begin indicator
Returns:
true if cursor is positioned at the beginning

isEnd

public boolean isEnd()
              throws DKException,
                     java.lang.Exception
End indicator
Returns:
true if cursor is positioned at the end.

isInBetween

public boolean isInBetween()
                    throws DKException,
                           java.lang.Exception
Between data objects in cursor indicator
Returns:
true if cursor is in between data objects in the cursor.

getPosition

public int getPosition()
                throws DKException,
                       java.lang.Exception
Gets the current cursor position
Returns:
cursor position

setPosition

public void setPosition(int position,
                        java.lang.Object value)
                 throws DKException,
                        java.lang.Exception
Sets the cursor position
Parameters:
position - cursor position option
  • DK_CM_ABSOLUTE (only scrollable cursors)
  • DK_CM_RELATIVE
  • DK_CM_BEGIN (only scrollable cursors)
  • DK_CM_END (only scrollable cursors)
  • DK_CM_FIRST (only scrollable cursors)
  • DK_CM_LAST (only scrollable cursors)
  • DK_CM_NEXT
  • DK_CM_PREVIOUS (only scrollable cursors)
value - cursor position value (optional). This value should be set when the position is DK_CM_ABSOLUTE or DK_CM_RELATIVE. This value is an Integer value.

setToNext

public void setToNext()
               throws DKException,
                      java.lang.Exception
Sets cursor to point to the position of the next data object in the cursor

fetchObject

public DKDDO fetchObject()
                  throws DKException,
                         java.lang.Exception
Fetches the element in the cursor at the current position
Returns:
DDO

fetchNext

public DKDDO fetchNext()
                throws DKException,
                       java.lang.Exception
Sets cursor to point to the position of the next data object and fetches the element in the cursor at that position
Returns:
DDO

fetchNextN

public boolean fetchNextN(int how_many,
                          dkCollection collection)
                   throws DKException,
                          java.lang.Exception
Fetches the next N elements of the cursor and inserts them into the given collection
Parameters:
how_many - how many elements the user wants to be returned in the collection.
collection - the collection where elements that are fetched are stored.
Returns:
false when no more data objects to return.

fetchObjectByName

public java.lang.Object fetchObjectByName(java.lang.String dataItemName)
                                   throws DKException,
                                          java.lang.Exception
Fetches the data item value in the cursor at the current position by data item name
Parameters:
dataItemName - data item name
Returns:
data item value

fetchNextByName

public java.lang.Object fetchNextByName(java.lang.String dataItemName)
                                 throws DKException,
                                        java.lang.Exception
Sets cursor to point to the position of the next data object and fetches the data item value in the cursor at that position by data item name.
Parameters:
dataItemName - data item name
Returns:
data item value

fetchNextNByName

public boolean fetchNextNByName(java.lang.String dataItemName,
                                int how_many,
                                java.lang.Object[] array)
                         throws DKException,
                                java.lang.Exception
Fetches the next N data item values of the cursor and inserts them into the given array
Parameters:
dataItemName - data item name
how_many - how many data item values the user wants to be returned in the collection.
array - the array where the data item values that are fetched are stored.
Returns:
false when no more data item values to return.

findObject

public DKDDO findObject(int position,
                        java.lang.String predicate)
                 throws DKException,
                        java.lang.Exception
Deprecated. No replacement

Find the data object which satisfies the given predicate, move the cursor to that position, fetch

Note:DKUsageError exception thrown if method is not implemented

Parameters:
position - cursor position
predicate - search predicate.
Returns:
DDO

deleteObject

public void deleteObject()
                  throws DKException,
                         java.lang.Exception
Deletes element at the current cursor position from the datastore

Note:DKUsageError exception thrown if method is not implemented


updateObject

public void updateObject(DKDDO ddo)
                  throws DKException,
                         java.lang.Exception
Updates element at the current cursor position from the datastore

Note:DKUsageError exception thrown if method is not implemented

Parameters:
ddo - the ddo to update

newObject

public DKDDO newObject()
                throws DKException,
                       java.lang.Exception
Constructs a new DDO of the same type as the items in the result

Note:DKUsageError exception thrown if method is not implemented

Returns:
DDO

addObject

public void addObject(DKDDO ddo)
               throws DKException,
                      java.lang.Exception
Adds an element to the datastore

Note:DKUsageError exception thrown if method is not implemented

Parameters:
ddo - the ddo to add

open

public void open()
          throws DKException,
                 java.lang.Exception
Opens the cursor. This reexcutes the query and repositions the cursor to the beginning.

close

public void close()
           throws DKException,
                  java.lang.Exception
Close the cursor and invalidates the result set.

destroy

public void destroy()
             throws DKException,
                    java.lang.Exception
Destroys the cursor. This method allows for cleanup, before garbage-collection is done on this class.

open

public void open(DKNVPair[] parms)
          throws DKException,
                 java.lang.Exception
Opens the cursor. This reexecutes the query and repositions the cursor to the beginning.
Parameters:
parms - allows for parameters to be passed in for the reexecution of the query.

datastoreName

public java.lang.String datastoreName()
                               throws java.lang.Exception
Gets the datastore name
Returns:
datastore name

datastoreType

public java.lang.String datastoreType()
                               throws java.lang.Exception
Gets the datastore type
Returns:
datastore type

handle

public DKHandle handle(int type)
                throws java.lang.Exception
Deprecated. Replace by handle(String type)

Gets a cursor handle
Parameters:
type - type of cursor handle wanted
Returns:
a cursor handle
See Also:
handle(java.lang.String)

handle

public DKHandle handle(java.lang.String type)
                throws java.lang.Exception
Gets a cursor handle
Parameters:
type - type of cursor handle wanted
Returns:
a cursor handle

cardinality

public int cardinality()
                throws DKException,
                       java.lang.Exception
Gets the number of query results if supported. This number may be an approximation for some back end datastores.

Note:DKUsageError exception thrown if method is not implemented

Returns:
number of query results. May be approximation.

objectType

public java.lang.String objectType()
                            throws java.lang.Exception
Gets the cursor object type
Returns:
cursor object type

EIP Java APIs

(c) Copyright International Business Machines Corporation 1996, 2002. IBM Corp. All rights reserved.