Enterprise Information Portal APIs

com.ibm.mm.sdk.server
Class DKResultSetCursorICM

java.lang.Object
  |
  +--com.ibm.mm.sdk.server.dkAbstractResultSetCursor
        |
        +--com.ibm.mm.sdk.server.DKResultSetCursorICM
All Implemented Interfaces:
DKConstant, DKMessageId, dkResultSetCursor

public class DKResultSetCursorICM
extends dkAbstractResultSetCursor

DKResultSetCursorICM class provides sequential access to results of a query such that, out of the whole result set, only items that have been specifically requested by the user are actually retrieved from the datastore. The remaining items in the result set are not retrieved until the user decides to do so.

To close the result set cursor, call one of the following methods: DKResultSetCursorICM.close (), DKResultSetCursorICM.destroy (). To completely clean up the result set cursor, it is suggested that you use DKResultSetCursorICM.destroy (). All open result set cursors are closed when either DKDatastoreICM.disconnect () or DKDatastoreICM.destroy () are called.

Note that, at this time, the DKDatastoreICM class does not support concurrent access from multiple threads in a multi-threaded program. You need to synchronize concurrent access to the datastore instance in your application. It is recommended that you use one instance of the datastore for each thread.

Currently, there are some restrictions on the functionality of ICM's result set cursor. For example, determining cardinality, scrolling, and updating the result set cursor is not supported. Refer to the javadoc under the specific methods for the most updated information.

Result set cursor can be used to optimize performance when the result set is expected to be large, and the user may only be interested in the first few elements in the result set. In such case, instead of retrieving the whole result set, the user retrieves the first block of results and makes a determination on whether to retrieve the rest.


Fields inherited from interface com.ibm.mm.sdk.common.DKConstant
    For details, see the class or interface
 
Fields inherited from interface com.ibm.mm.sdk.common.DKMessageId
    For details, see the class or interface
 
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)
          Find the data object which satisfies the given predicate, move the cursor to that position, fetch
 int getPosition()
          Gets the current cursor position
 DKHandle handle(int type)
          Gets a cursor handle
 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
 java.lang.String objectType()
          Gets the cursor object type
 void open()
          Opens the cursor.
 void open(DKNVPair[] parms)
          Opens the cursor.
 void retrieveObjects(dkCollection ddo, DKNVPair[] options)
           
 void retrieveObjects(dkCollection ddo, int option)
           
 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
 
Methods inherited from class com.ibm.mm.sdk.server.dkAbstractResultSetCursor
newObject
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

isScrollable

public boolean isScrollable()
                     throws DKException,
                            java.lang.Exception
Description copied from interface: dkResultSetCursor
Scrollable indicator
Overrides:
isScrollable in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
true if cursor can be scrolled forward and backward

isUpdatable

public boolean isUpdatable()
                    throws DKException,
                           java.lang.Exception
Description copied from interface: dkResultSetCursor
Updatable indicator
Overrides:
isUpdatable in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
true if cursor is updatable

isValid

public boolean isValid()
                throws DKException,
                       java.lang.Exception
Description copied from interface: dkResultSetCursor
Valid indicator
Overrides:
isValid in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
true if cursor is valid

isOpen

public boolean isOpen()
               throws DKException,
                      java.lang.Exception
Description copied from interface: dkResultSetCursor
Open indicator
Overrides:
isOpen in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
true is cursor is in an opened state

isBegin

public boolean isBegin()
                throws DKException,
                       java.lang.Exception
Description copied from interface: dkResultSetCursor
Begin indicator
Overrides:
isBegin in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
true if cursor is positioned at the beginning

isEnd

public boolean isEnd()
              throws DKException,
                     java.lang.Exception
Description copied from interface: dkResultSetCursor
End indicator
Overrides:
isEnd in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
true if cursor is positioned at the end.

isInBetween

public boolean isInBetween()
                    throws DKException,
                           java.lang.Exception
Description copied from interface: dkResultSetCursor
Between data objects in cursor indicator
Overrides:
isInBetween in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
true if cursor is in between data objects in the cursor.

getPosition

public int getPosition()
                throws DKException,
                       java.lang.Exception
Description copied from interface: dkResultSetCursor
Gets the current cursor position
Overrides:
getPosition in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
cursor position

setPosition

public void setPosition(int position,
                        java.lang.Object value)
                 throws DKException,
                        java.lang.Exception
Description copied from interface: dkResultSetCursor
Sets the cursor position
Overrides:
setPosition in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
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
Description copied from interface: dkResultSetCursor
Sets cursor to point to the position of the next data object in the cursor
Overrides:
setToNext in class dkAbstractResultSetCursor

fetchObject

public DKDDO fetchObject()
                  throws DKException,
                         java.lang.Exception
Description copied from interface: dkResultSetCursor
Fetches the element in the cursor at the current position
Overrides:
fetchObject in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
DDO

fetchNext

public DKDDO fetchNext()
                throws DKException,
                       java.lang.Exception
Description copied from interface: dkResultSetCursor
Sets cursor to point to the position of the next data object and fetches the element in the cursor at that position
Overrides:
fetchNext in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
DDO

fetchNextN

public boolean fetchNextN(int how_many,
                          dkCollection collection)
                   throws DKException,
                          java.lang.Exception
Description copied from interface: dkResultSetCursor
Fetches the next N elements of the cursor and inserts them into the given collection
Overrides:
fetchNextN in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
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
Description copied from interface: dkResultSetCursor
Fetches the data item value in the cursor at the current position by data item name
Overrides:
fetchObjectByName in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Parameters:
dataItemName - data item name
Returns:
data item value

fetchNextByName

public java.lang.Object fetchNextByName(java.lang.String dataItemName)
                                 throws DKException,
                                        java.lang.Exception
Description copied from interface: dkResultSetCursor
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.
Overrides:
fetchNextByName in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
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
Description copied from interface: dkResultSetCursor
Fetches the next N data item values of the cursor and inserts them into the given array
Overrides:
fetchNextNByName in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
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
Description copied from interface: dkResultSetCursor
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

Overrides:
findObject in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Parameters:
position - cursor position
predicate - search predicate.
Returns:
DDO

deleteObject

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

Note:DKUsageError exception thrown if method is not implemented

Overrides:
deleteObject in class dkAbstractResultSetCursor

updateObject

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

Note:DKUsageError exception thrown if method is not implemented

Overrides:
updateObject in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Parameters:
ddo - the ddo to update

addObject

public void addObject(DKDDO ddo)
               throws DKException,
                      java.lang.Exception
Description copied from interface: dkResultSetCursor
Adds an element to the datastore

Note:DKUsageError exception thrown if method is not implemented

Overrides:
addObject in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Parameters:
ddo - the ddo to add

open

public void open()
          throws DKException,
                 java.lang.Exception
Description copied from interface: dkResultSetCursor
Opens the cursor. This reexcutes the query and repositions the cursor to the beginning.
Overrides:
open in class dkAbstractResultSetCursor

close

public void close()
           throws DKException,
                  java.lang.Exception
Description copied from interface: dkResultSetCursor
Close the cursor and invalidates the result set.
Overrides:
close in class dkAbstractResultSetCursor

destroy

public void destroy()
             throws DKException,
                    java.lang.Exception
Description copied from interface: dkResultSetCursor
Destroys the cursor. This method allows for cleanup, before garbage-collection is done on this class.
Overrides:
destroy in class dkAbstractResultSetCursor

open

public void open(DKNVPair[] parms)
          throws DKException,
                 java.lang.Exception
Description copied from interface: dkResultSetCursor
Opens the cursor. This reexecutes the query and repositions the cursor to the beginning.
Overrides:
open in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
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
Description copied from interface: dkResultSetCursor
Gets the datastore name
Overrides:
datastoreName in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
datastore name

datastoreType

public java.lang.String datastoreType()
                               throws java.lang.Exception
Description copied from interface: dkResultSetCursor
Gets the datastore type
Overrides:
datastoreType in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
datastore type

handle

public DKHandle handle(int type)
                throws java.lang.Exception
Description copied from interface: dkResultSetCursor
Gets a cursor handle
Overrides:
handle in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Parameters:
type - type of cursor handle wanted
Returns:
a cursor handle
See Also:
dkResultSetCursor.handle(java.lang.String)

handle

public DKHandle handle(java.lang.String type)
                throws java.lang.Exception
Description copied from interface: dkResultSetCursor
Gets a cursor handle
Overrides:
handle in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Parameters:
type - type of cursor handle wanted
Returns:
a cursor handle

cardinality

public int cardinality()
                throws java.lang.Exception
Description copied from interface: dkResultSetCursor
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

Overrides:
cardinality in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
number of query results. May be approximation.

objectType

public java.lang.String objectType()
                            throws java.lang.Exception
Description copied from interface: dkResultSetCursor
Gets the cursor object type
Overrides:
objectType in class dkAbstractResultSetCursor
Following copied from interface: com.ibm.mm.sdk.common.dkResultSetCursor
Returns:
cursor object type

retrieveObjects

public void retrieveObjects(dkCollection ddo,
                            int option)
                     throws java.lang.Exception

retrieveObjects

public void retrieveObjects(dkCollection ddo,
                            DKNVPair[] options)
                     throws java.lang.Exception

EIP Java APIs

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