Enterprise Information Portal APIs

com.ibm.mm.beans
Class CMBSearchResults

java.lang.Object
  |
  +--com.ibm.mm.beans.CMBSearchResults
All Implemented Interfaces:
CMBBaseConstant, CMBConnectionReplyListener, CMBSearchReplyListener, java.util.EventListener, java.beans.PropertyChangeListener, java.io.Serializable

public class CMBSearchResults
extends java.lang.Object
implements java.io.Serializable, java.beans.PropertyChangeListener, CMBConnectionReplyListener, CMBSearchReplyListener, CMBBaseConstant

The CMBSearchResults bean manages search results. For asynchronous searches, CMBSearchResults listens to CMBSearchReplyEvents from CMBQueryService or CMBSearchTemplate. Alternatively, for synchronous searches, results can be passed from CMBQueryService to CMBSearchResults using the following logic:

      searchResults.newResults(queryService.getResults());
 
CMBSearchResults emits CMBResultEvent events when a page's number of hits are obtained (see setPageSize). Methods on CMBSearchResults can also be used to read the results individually, or obtain all hits as an array. CMBItem objects represent each hit in the search results.

Delayed Attribute Retrieval

CMBSearchResults supports delayed attribute retrieval. For those servers that support multi-item retrieve (such as CMv8), this feature can be used to efficiently retrieve only attribute information for those hits being displayed to the user. The page size property determines the number of hits that will be retrieved at a time. When an attribute is read from any hit in the hit list, the attributes of that item, and all other items on that page, will be retrieved from the server.

Summary of properties and events:

   imported properties   traceEnabled, defaulting off, will not veto
   exported properties   none
   standalone properties pageSize, currentHitItem
   interested in events  CMBSConnectionReplyEvent - to get connection handle
                         CMBSearchReplyEvent      - to get results
                         PropertyChangeEvent      - to import traceEnabled
   source of events      CMBResultEvent           - to broadcast result changes
                         CMBExceptionEvent        - to post exception
                         CMBTraceEvent            - to let logger trace
 

Since:
6.1
See Also:
, Serialized Form

Fields inherited from interface com.ibm.mm.beans.CMBBaseConstant
ANNOTATION_MIME_TYPE, CMB_CLASS_ICM_DOC_MODEL, CMB_CLASS_ICM_DOC_PART, CMB_CLASS_ITEM, CMB_CLASS_RESOURCE_ITEM, CMB_CLASS_UNDEFINED, CMB_CONNTYPE_DYNAMIC, CMB_CONNTYPE_LOCAL, CMB_CONNTYPE_REMOTE, CMB_CONTENT_ATTRONLY, CMB_CONTENT_CHILDREN, CMB_CONTENT_ITEMTREE, CMB_CONTENT_LINKS_INBOUND, CMB_CONTENT_LINKS_OUTBOUND, CMB_CONTENT_YES, CMB_DATATYPE_COLLECTION, CMB_DATATYPE_COLLECTION_DDO, CMB_DATATYPE_COLLECTION_XDO, CMB_DATATYPE_DATAOBJECTBASE, CMB_DATATYPE_DATE, CMB_DATATYPE_DECIMAL, CMB_DATATYPE_DOUBLE, CMB_DATATYPE_FLOAT, CMB_DATATYPE_FSTRING, CMB_DATATYPE_ITEM, CMB_DATATYPE_ITEM_COLLECTION, CMB_DATATYPE_LONG, CMB_DATATYPE_OBJECT, CMB_DATATYPE_OBJECT_COLLECTION, CMB_DATATYPE_SHORT, CMB_DATATYPE_TIME, CMB_DATATYPE_TIMESTAMP, CMB_DATATYPE_UNDEFINED, CMB_DATATYPE_VSTRING, CMB_DSTYPE_CM, CMB_DSTYPE_DB2, CMB_DSTYPE_DES, CMB_DSTYPE_DJ, CMB_DSTYPE_DL, CMB_DSTYPE_DOMDOC, CMB_DSTYPE_FED, CMB_DSTYPE_FN, CMB_DSTYPE_IC, CMB_DSTYPE_ICM, CMB_DSTYPE_IP390, CMB_DSTYPE_JDBC, CMB_DSTYPE_OD, CMB_DSTYPE_VI400, CMB_EIP_LOGOUT, CMB_OBJTYPE_CMBITEM, CMB_OBJTYPE_CMBOBJECT, CMB_OP_AND, CMB_OP_BETWEEN, CMB_OP_CONTAINS_TEXT, CMB_OP_CONTAINS_TEXT_IN_CONTENT, CMB_OP_EQUAL, CMB_OP_GREATER, CMB_OP_GREATER_EQUAL, CMB_OP_IN, CMB_OP_LESS, CMB_OP_LESS_EQUAL, CMB_OP_LIKE, CMB_OP_NOT, CMB_OP_NOT_BETWEEN, CMB_OP_NOT_EQUAL, CMB_OP_NOT_IN, CMB_OP_NOT_LIKE, CMB_OP_OR, CMB_OP_UNDEFINED, CMB_QS_TYPE_COMBINED, CMB_QS_TYPE_DES, CMB_QS_TYPE_FEDERATED, CMB_QS_TYPE_IMAGE, CMB_QS_TYPE_PARAMETRIC, CMB_QS_TYPE_SQL, CMB_QS_TYPE_TEMPLATE, CMB_QS_TYPE_TEXT, CMB_QS_TYPE_UNKNOWN, CMB_QS_TYPE_XPATH, CMB_ST_SKIP_ALWAYS, CMB_ST_SKIP_NEVER, CMB_ST_SKIP_WITH_PROMPT, CMB_STATUS_FAILED, CMB_STATUS_OK, CMB_STATUS_RESULT_END, CMB_STATUS_RESULT_MORE, CMB_STATUS_RESULT_NEW, CMB_TIMESTAMP_UNDEFINED, CMB_TYPE_DOCUMENT, CMB_TYPE_FOLDER, CMB_TYPE_ITEM, CMB_TYPE_UNKNOWN, CMB_USERID_UNDEFINED, CMB_VERSION_CONTROL_ALWAYS_NEW, CMB_VERSION_CONTROL_BY_APP, CMB_VERSION_CONTROL_NEVER, CMB_VERSION_KEYWORD, CMB_VERSION_LATEST, CMB_VERSION_NEW, PROP_CACHE_ENABLED, PROP_CC2MIME_URL, PROP_CONNECTION, PROP_CONNECTION_TYPE, PROP_DATA_MANAGEMENT_ENABLED, PROP_DSTYPE, PROP_LOCAL_SERVER, PROP_NAME, PROP_NEW_PASSWORD, PROP_PASSWORD, PROP_PORT_NUMBER, PROP_QUERY_CALLBACK_THRESHOLD, PROP_QUERY_MAX_RESULTS, PROP_RESULT_PAGESIZE, PROP_RMI_HOSTNAME, PROP_SCHEMA_MANAGEMENT_ENABLED, PROP_SEARCH_ASYNCH, PROP_SEARCH_MULTI_CHARS_WILDCARD, PROP_SEARCH_PARAMETRIC_WILDCARD, PROP_SEARCH_SINGLE_CHAR_WILDCARD, PROP_SEARCH_SKIP_SERVER, PROP_SEARCH_TIMEOUT, PROP_SERVER_NAME, PROP_SV_CONNECTION_TYPE, PROP_SV_PORT_NUMBER, PROP_SV_RMI_HOSTNAME, PROP_TRACE_ENABLED, PROP_USERID
 
Constructor Summary
CMBSearchResults()
          Default constructor.
 
Method Summary
 void addCMBExceptionListener(CMBExceptionListener listener)
          CMBExceptionEvent registration method.
 void addCMBResultListener(CMBResultListener listener)
          CMBResultEvent registration method.
 void addCMBTraceListener(CMBTraceListener listener)
          CMBTraceEvent registration method.
 void appendResults(java.lang.Object resultList)
          Adds a new set of search results to current search results.
 void clearResults()
          Clears current search results from memory.
 CMBConnection getConnection()
          Gets the connection bean reference.
 int getCount()
          Gets the total hit count.
 CMBHitItem getCurrentHitItem()
          Gets the current hit item.
 CMBExceptionEvent getExceptionEvent()
          Gets the exceptionEvent.
 CMBHitItem[] getHitItem()
          Gets all the hit items from the search results.
 CMBHitItem getHitItem(int index)
          Gets a specific hit item by index.
 CMBItem[] getItem()
          Gets all the items from the search results.
 CMBItem getItem(int index)
          Gets a specific item by index.
 CMBItem getItem(java.lang.String pidString)
          Gets specified item.
 CMBItem[] getNewItem()
          Gets the new items since the last time you asked for new items.
 CMBHitItem getNextHitItem()
          Gets the next hit item.
 CMBHitItem[] getNextRangeHitItem(int range)
          Gets the next range of hit item.
 int getPageSize()
          Gets the default number of hit items in a page.
 java.lang.String getPidString()
          Gets the current hit item ID.
 CMBResultEvent getResultEvent()
          Gets the resultEvent.
 CMBTraceEvent getTraceEvent()
          Gets the traceEvent.
 boolean isResultsComplete()
          Returns whether the the results are complete.
 boolean isTraceEnabled()
          Indicates if trace is enabled on the bean.
 void newResults(java.lang.Object resultObj)
          Adds a new set of search results.
 void onCMBConnectionReply(CMBConnectionReplyEvent evt)
          Implementation of connection reply service method: update the connection handle accordingly.
 void onCMBSearchReply(CMBSearchReplyEvent evt)
          Implementation of search reply service method.
 void propertyChange(java.beans.PropertyChangeEvent evt)
          On a property change, imports the traceEnabled property value.
 void removeCMBExceptionListener(CMBExceptionListener listener)
          CMBExceptionEvent unregistration method.
 void removeCMBResultListener(CMBResultListener listener)
          CMBResultEvent unregistration method.
 void removeCMBTraceListener(CMBTraceListener listener)
          CMBTraceEvent unregistration method.
 void removeItem(int index)
          Removes the hit item at the given index from the hit list.
 void resetCurrentHitItem()
          Resets the current hit item to the first in the result list.
 void resetNewItemIndex()
          Resets index of item returned from getNewItem() to the first item.
 void setConnection(CMBConnection conn)
          Sets the connection handle from the CMBConnection bean.
 void setCurrentHitItem(CMBHitItem item)
          Sets current hit item.
 void setCurrentSearchTemplate(CMBSearchTemplate stObj)
          Sets the current search template object.
 void setPageSize(int newSize)
          Sets the default number of hit items in a page.
 void setResultsComplete(boolean newResults)
          Sets property flag indicating that results are complete.
 void setTraceEnabled(boolean newValue)
          Sets whether trace is on or off.
 void sort(java.lang.String attribute, boolean ascending)
          Sorts the search results.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CMBSearchResults

public CMBSearchResults()
Default constructor.
Method Detail

onCMBConnectionReply

public void onCMBConnectionReply(CMBConnectionReplyEvent evt)
Implementation of connection reply service method: update the connection handle accordingly.
Specified by:
onCMBConnectionReply in interface CMBConnectionReplyListener
Parameters:
evt - a CMBConnectionReplyEvent

onCMBSearchReply

public void onCMBSearchReply(CMBSearchReplyEvent evt)
Implementation of search reply service method. This gets the search result from the event. See CMBSearchReplyEvent for result type.
Specified by:
onCMBSearchReply in interface CMBSearchReplyListener
Parameters:
evt - a CMBSearchReplyEvent

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent evt)
On a property change, imports the traceEnabled property value.
Specified by:
propertyChange in interface java.beans.PropertyChangeListener
Parameters:
evt - a property changed event

addCMBExceptionListener

public void addCMBExceptionListener(CMBExceptionListener listener)
CMBExceptionEvent registration method. It ignores a registration request if the listener is already registered.
Parameters:
listener - listener to be registered

removeCMBExceptionListener

public void removeCMBExceptionListener(CMBExceptionListener listener)
CMBExceptionEvent unregistration method.
Parameters:
listener - listener to be unregistered

addCMBTraceListener

public void addCMBTraceListener(CMBTraceListener listener)
CMBTraceEvent registration method. It ignores a registration request if the listener is already registered.
Parameters:
listener - listener to be registered

removeCMBTraceListener

public void removeCMBTraceListener(CMBTraceListener listener)
CMBTraceEvent unregistration method.
Parameters:
listener - listener to be unregistered

addCMBResultListener

public void addCMBResultListener(CMBResultListener listener)
CMBResultEvent registration method. It ignores a registration request if the listener is already registered.
Parameters:
listener - listener to be registered

removeCMBResultListener

public void removeCMBResultListener(CMBResultListener listener)
CMBResultEvent unregistration method.
Parameters:
listener - listener to be unregistered

isTraceEnabled

public boolean isTraceEnabled()
Indicates if trace is enabled on the bean.
Returns:
true if trace is enabled.

setResultsComplete

public void setResultsComplete(boolean newResults)
Sets property flag indicating that results are complete.
Parameters:
newReusults - new value of results complete flag
Returns:
void

isResultsComplete

public boolean isResultsComplete()
Returns whether the the results are complete.
Returns:
resultsCompleted property value

setTraceEnabled

public void setTraceEnabled(boolean newValue)
Sets whether trace is on or off.
Parameters:
newValue - new trace option value

getPageSize

public int getPageSize()
Gets the default number of hit items in a page.
Returns:
int page size

setPageSize

public void setPageSize(int newSize)
Sets the default number of hit items in a page.
Parameters:
newSize - number of hit items

setConnection

public void setConnection(CMBConnection conn)
Sets the connection handle from the CMBConnection bean.
Parameters:
conn - reference of connection bean

getConnection

public CMBConnection getConnection()
Gets the connection bean reference.
Returns:
the reference to the CMBConnection object.

getCount

public int getCount()
Gets the total hit count.
Returns:
total hits

resetCurrentHitItem

public void resetCurrentHitItem()
Resets the current hit item to the first in the result list.

getCurrentHitItem

public CMBHitItem getCurrentHitItem()
                             throws java.lang.ArrayIndexOutOfBoundsException,
                                    CMBException
Gets the current hit item. This method does NOT update the currenHitItem.
Parameters:
index - hit item location within current search results
Returns:
a CMBHitItem object
Throws:
java.lang.ArrayIndexOutOfBoundsException - if index is invalid
CMBException - if there is an error occurred in the Content Server. Call CMBException.getErrorData() to get the original exception object.

setCurrentHitItem

public void setCurrentHitItem(CMBHitItem item)
                       throws CMBException
Sets current hit item.
Parameters:
item - hit item
Throws:
CMBException - if item could not be found in the hit list.
CMBException - if there is an error occurred in the Content Server. Call CMBException.getErrorData() to get the original exception object.

getPidString

public java.lang.String getPidString()
                              throws java.lang.Exception
Gets the current hit item ID.
Returns:
PID string

getHitItem

public CMBHitItem[] getHitItem()
                        throws CMBException
Gets all the hit items from the search results. This method does NOT update the currentHitItem property.
Returns:
an array of CMBHitItem objects
Throws:
CMBException - if there is an error occurred in the Content Server. Call CMBException.getErrorData() to get the original exception object.

getHitItem

public CMBHitItem getHitItem(int index)
                      throws java.lang.ArrayIndexOutOfBoundsException,
                             CMBException
Gets a specific hit item by index. This method does NOT update the currentHitItem property.
Parameters:
index - hit item location within current search results
Returns:
a CMBHitItem object
Throws:
java.lang.ArrayIndexOutOfBoundsException - if index is invalid
CMBException - if there is an error occurred in the Content Server. Call CMBException.getErrorData() to get the original exception object.

getNextHitItem

public CMBHitItem getNextHitItem()
                          throws java.lang.ArrayIndexOutOfBoundsException,
                                 CMBException
Gets the next hit item. This method updates the currenHitItem.
Parameters:
index - hit item location within current search results.
Returns:
a CMBHitItem object, null is returned if result set is empty.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if index is invalid.
CMBException - if there is an error occurred in the Content Server. Call CMBException.getErrorData() to get the original exception object.

getNextRangeHitItem

public CMBHitItem[] getNextRangeHitItem(int range)
                                 throws java.lang.ArrayIndexOutOfBoundsException,
                                        CMBException
Gets the next range of hit item. This method updates the currenHitItem to the last item of the range.
Parameters:
range - range of hit items
Returns:
a CMBHitItem object
Throws:
java.lang.ArrayIndexOutOfBoundsException - if index is invalid
CMBException - if there is an error occurred in the Content Server. Call CMBException.getErrorData() to get the original exception object.

getItem

public CMBItem getItem(java.lang.String pidString)
Gets specified item.
Parameters:
pidString - item ID
Returns:
an CMBItem object, null will be returned if item does not exist.

resetNewItemIndex

public void resetNewItemIndex()
Resets index of item returned from getNewItem() to the first item.

getNewItem

public CMBItem[] getNewItem()
Gets the new items since the last time you asked for new items.
Parameters:
index - item location within current search results
Returns:
an array of CMBItem objects
Throws:
java.lang.ArrayIndexOutOfBoundsException - if index is invalid

getItem

public CMBItem getItem(int index)
                throws java.lang.ArrayIndexOutOfBoundsException
Gets a specific item by index. This method does NOT update the currentItem.
Parameters:
index - item location within current search results
Returns:
a CMBItem object
Throws:
java.lang.ArrayIndexOutOfBoundsException - if index is invalid

getItem

public CMBItem[] getItem()
Gets all the items from the search results. This method does NOT update the currentItem.
Returns:
an array of CMBItem objects, empty array will be returned if result set is empty.

removeItem

public void removeItem(int index)
                throws java.lang.ArrayIndexOutOfBoundsException
Removes the hit item at the given index from the hit list.
Parameters:
index - hit item location within current search results.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if index is invalid.
CMBException - if an error occurred in the Content Server. Call CMBException.getErrorData() to get the original exception object.
Since:
8.1

newResults

public void newResults(java.lang.Object resultObj)
                throws CMBNoConnectionException,
                       CMBException
Adds a new set of search results. Clears out the current search results.
Parameters:
resultObj - new search results as one of the following types which is usually the returned type from CMBSearchTemplate.getResults() method.
  • Vector of com.ibm.mm.sdk.common.DKDDO objects
  • com.ibm.mm.sdk.common.DKResults, or
  • CMBResultSetCursor
Throws:
CMBNoConnectionException - if setConnection() method has not been called.
CMBException - when an error is received from servers. Call getErrorData() to get reference to the original exception from OO API.
See Also:
CMBSearchTemplate

appendResults

public void appendResults(java.lang.Object resultList)
                   throws CMBNoConnectionException,
                          CMBException
Adds a new set of search results to current search results.
Parameters:
resultList - new search results as one of the following types which is usually the returned type from CMBSearchTemplate.getResults() method:
  • CMBResultData object
  • Vector of com.ibm.mm.sdk.common.DKDDO objects
  • Vector of CMBItem objects
  • com.ibm.mm.sdk.common.DKResults, or
  • CMBResultSetCursor
Throws:
CMBNoConnectionException - if setConnection() method has not been called.
CMBException - when an error is received from servers. Call getErrorData() to get reference to the original exception from OO API.
See Also:
CMBSearchTemplate

clearResults

public void clearResults()
Clears current search results from memory.

setCurrentSearchTemplate

public void setCurrentSearchTemplate(CMBSearchTemplate stObj)
                              throws CMBNoConnectionException,
                                     CMBException,
                                     java.lang.IllegalArgumentException
Sets the current search template object.
Parameters:
stObj - CMBSearchTemplate object
Throws:
CMBNoConnectionException - is thrown if CMBConnection bean is not already set. setConnection() method needs to called first.
java.lang.IllegalArgumentException - is thrown when stObj is null.

sort

public void sort(java.lang.String attribute,
                 boolean ascending)
Sorts the search results. This sort does not change the position of two items unless they must be changed to order the items. This allows multiple sort operations to be performed to cause the list to be sorted by multiple attributes: sort first by the secondary key, then by the primary key.
Note: This resets the current hit item.
Parameters:
attribute - the name of the attribute to sort by.
ascending - if true, the sort will be ascending. If false, descending.

getResultEvent

public CMBResultEvent getResultEvent()
Gets the resultEvent. To support VisualCafe 3.0 "Add Interaction..."
Returns:
a CMBResultEvent

getTraceEvent

public CMBTraceEvent getTraceEvent()
Gets the traceEvent. To support VisualCafe 3.0 "Add Interaction..."
Returns:
a CMBTraceEvent

getExceptionEvent

public CMBExceptionEvent getExceptionEvent()
Gets the exceptionEvent. To support VisualCafe 3.0 "Add Interaction..."
Returns:
a CMBExceptionEvent

EIP JavaBeans

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