com.plumtree.server
Interface IPTSearchResponse

All Superinterfaces:

IPTUnknown

public interface IPTSearchResponse
extends IPTUnknown

IPTSearchResponse contains the results of a single search; it is returned by IPTSearchRequest.Search() and FollowupSearch(). It contains methods to retrieve information about items matching the search, categories (groups) identified, and spelling corrections made in the course of executing the search.

Version:

$Revision$

Author:

CraigS

Method Summary

void	Clear() Clears this object and releases memory associated with it, which may be substantial.
java.lang.String	GetCorrectedToken(int nMisspellingIndex, int nCorrectionIndex) Returns a single spelling correction for a single misspelled token.
int	GetCorrectionFrequency(int nMisspellingIndex, int nCorrectionIndex) Returns the number of search results in which the selected correction appears.
double	GetFieldsAsDouble(int nRank, int nPropertyID) Returns the value of a single field (property) in a single search result.
int	GetFieldsAsInt(int nRank, int nPropertyID) Returns the value of a single field (property) in a single search result.
java.lang.Object	GetFieldsAsObject(int nRank, int nPropertyID) Returns the value of a single field (property) in a single search result.
java.lang.String	GetFieldsAsString(int nRank, int nPropertyID) Returns the value of a single field (property) in a single search result.
com.plumtree.openfoundation.util.XPDateTime	GetFieldsAsXPDateTime(int nRank, int nPropertyID) Returns the value of a single field (property) in a single search result.
java.lang.String	GetGroupLabel(int nGroupIndex) Returns a label for a single group.
boolean	GetIsBestBet(int nRank) Returns true if the result appears in the result set (or if its rank was affected) because of a Best Bet.
double	GetKWICFieldsAsDouble(int nRank, int nPropertyID) Behaves identically to GetFieldsAsDouble; call that method instead.
int	GetKWICFieldsAsInt(int nRank, int nPropertyID) Behaves identically to GetFieldsAsInt; call that method instead.
java.lang.Object	GetKWICFieldsAsObject(int nRank, int nPropertyID) Call GetFieldsAsObject() or GetKWICFieldsAsString() instead, depending on what you want.
java.lang.String	GetKWICFieldsAsString(int nRank, int nPropertyID) Returns keyword-in-context ("KWIC") information for the given result and property.
com.plumtree.openfoundation.util.XPDateTime	GetKWICFieldsAsXPDateTime(int nRank, int nPropertyID) Behaves identically to GetFieldsAsXPDateTime; call that method instead.
java.lang.String	GetMisspelledToken(int nIndex) Returns one misspelled token.
int	GetNumCorrections(int nIndex) Returns the number of spelling corrections found for the given misspelled token.
int	GetNumGroups() Returns the number of categories into which the results were divided.
int	GetNumMisspelledTokens() Returns the number of tokens (words) in the user's query that were spell corrected.
IPTSearchQuery	GetQueryForAllOthers() Like GetQueryForGroup(), returns an IPTSearchQuery that may be used to drill down into the "all others" set of results that did not fall in any coherent group.
IPTSearchQuery	GetQueryForGroup(int nGroupIndex) Returns an IPTSearchQuery that may be passed to IPTSearchRequest.FollowupSearch() (along with the original query/queries used to generate this IPTSearchResponse) to drill down into the indicated group.
int	GetRank(int nGroup, int nRowWithinGroup) Maps from the result ranking within a group to the overall (ungrouped) result ranking.
int	GetRankForUncategorizedDoc(int rankWithinAllOthers) Like GetRank(), maps from the rank in the uncategorized "all others" set to the overall result ranking.
java.lang.String	GetResultAbsType(int nRank) Abstractified, cross-application type of the result: "DOCUMENT", "CONTAINER", or "OTHER".
java.lang.String	GetResultACL(int nRank) Returns the ACL of the result (for portal objects only), or the list of Collab roles that have access to the result (for Collab objects only).
java.lang.String	GetResultApp(int nRank) Returns the application that indexed this result: one of PTPORTAL (portal items), PTCONTENT (Content Server), PTCONTENTTEMPLATE (Branding Engine), or PTCOLLAB (Collaboration Server).
java.lang.String	GetResultFolderACL(int nRank) Returns the ACL of the result's folder (for portal objects only).
java.lang.String	GetResultInternalField(int nRank, int nInternalFieldID) Returns the value of one of several "internal fields" that don't correspond to properties and that aren't important enough to merit their own method.
java.lang.String	GetResultPath(int nRank) Returns the full path to the object, in text form.
int	GetResultSize(int nRank) Returns the size of the result in bytes, or a negative value if unknown.
int	GetResultsReturned() Get the number of results returned.
java.lang.String	GetResultSubType(int nRank) Returns the application-specific type of the result.
int	GetReturnedResultsInGroup(int nGroupIndex) Returns the number of results in the group that are available for display.
int	GetReturnedResultsNotInAnyGroup() Returns the number of displayable results that did not fall in any group.
int	GetSkipped() Returns the number of results skipped before beginning to return results.
int	GetTotalMatches() Get the total number of matches for the query.
java.lang.String	GetTotalResultsInGroup(int nGroupIndex) Returns the total number of results in the indicated group, or an estimate in some cases.
java.lang.Object	GetTotalResultsNotInAnyGroup() Returns an estimate the number of results in the overall result set (not just those displayed) that did not fall into any group.
int	GetWarning() Returns a code indicating whether any warnings were issued in the course of running the search.

Methods inherited from interface com.plumtree.server.IPTUnknown

GetInterfaces

Method Detail

GetResultsReturned

int GetResultsReturned()

Get the number of results returned. This is NOT the same as the total number of matches for the query (see GetTotalMatches() for that); this is the number of items for which complete information was returned. (If the UI says "Results 1-10 of 123", this method returns 10.)

Returns:

number of returned results

GetSkipped

int GetSkipped()

Returns the number of results skipped before beginning to return results. For example, if you requested results 11 through 20, this method will return 10.

Returns:

number of results skipped

GetTotalMatches

int GetTotalMatches()

Get the total number of matches for the query. Not all of these are necessarily returned; call GetResultsReturned() for that. If the UI says "Results 1-10 of 123", this method returns 123.

Returns:

total number of matches

GetWarning

int GetWarning()

Returns a code indicating whether any warnings were issued in the course of running the search. Warnings indicate that the search ran and some results may have been returned, but not necessarily all results, and that the user should be informed of the reason. See the PT_SEARCH_WARNING enumeration for a list of codes.

Returns:

PT_SEARCH_WARNING code

GetNumMisspelledTokens

int GetNumMisspelledTokens()

Returns the number of tokens (words) in the user's query that were spell corrected.

Returns:

number of spellcorrected terms

GetMisspelledToken

java.lang.String GetMisspelledToken(int nIndex)

Returns one misspelled token.

Parameters:

nIndex - Index of desired token, from 0 to (GetNumMisspelledTokens()-1).

Returns:

Misspelled token, lowercased.

GetNumCorrections

int GetNumCorrections(int nIndex)

Returns the number of spelling corrections found for the given misspelled token.

Parameters:

nIndex - Index of token, from 0 to (GetNumMisspelledTokens()-1).

Returns:

number of corrections for this token.

GetCorrectedToken

java.lang.String GetCorrectedToken(int nMisspellingIndex,
                                   int nCorrectionIndex)

Returns a single spelling correction for a single misspelled token.

Parameters:

nMisspellingIndex - Index of original token, from 0 to (GetNumMisspelledTokens()-1).

nCorrectionIndex - Index of desired correction, from 0 to (GetNumCorrections(nMisspellingIndex)-1).

Returns:

Corrected token, lowercased.

GetCorrectionFrequency

int GetCorrectionFrequency(int nMisspellingIndex,
                           int nCorrectionIndex)

Returns the number of search results in which the selected correction appears. This helps the UI decide which corrections to display and in what order.

Parameters:

nMisspellingIndex - Index of original token, from 0 to (GetNumMisspelledTokens()-1).

nCorrectionIndex - Index of desired correction, from 0 to (GetNumCorrections(nMisspellingIndex)-1).

Returns:

number of search results in which the selected correction appears (may be 0).

GetNumGroups

int GetNumGroups()

Returns the number of categories into which the results were divided. "All Others" (uncategorized results) are not considered a separate group. If the GROUPBY setting was not used on the original search request, this method will return 0.

Returns:

number of categories (groups) into which the results were divided

GetGroupLabel

java.lang.String GetGroupLabel(int nGroupIndex)

Returns a label for a single group. If results were categorized by folder, this will be a localized name for a single folder, or "Unknown Folder" if the folder lookup fails. If results were categorized by object type, this method will return a string like "PTCOMMUNITY" that must be mapped to a localized equivalent before being displayed to an end user.

Parameters:

nGroupIndex - Desired group, from 0 to (GetNumGroups()-1).

Returns:

label for group

GetTotalResultsInGroup

java.lang.String GetTotalResultsInGroup(int nGroupIndex)

Returns the total number of results in the indicated group, or an estimate in some cases. Estimates are indicated by "~", for example, "~ 1000". This is the total over the entire result set, not the number available for display.

Parameters:

nGroupIndex - Desired group, from 0 to (GetNumGroups()-1).

Returns:

total number of results in group, in a printable String form

GetReturnedResultsInGroup

int GetReturnedResultsInGroup(int nGroupIndex)

Returns the number of results in the group that are available for display. Will always be equal to or less than the value returned by GetReturnedResults().

Parameters:

nGroupIndex - Desired group, from 0 to (GetNumGroups()-1).

Returns:

number of returned results in the group

GetQueryForGroup

IPTSearchQuery GetQueryForGroup(int nGroupIndex)

Returns an IPTSearchQuery that may be passed to IPTSearchRequest.FollowupSearch() (along with the original query/queries used to generate this IPTSearchResponse) to drill down into the indicated group. "Drilling down" means that all results from this followup search are members of the group.

Parameters:

nGroupIndex - Desired group, from 0 to (GetNumGroups()-1).

Returns:

query to use to drilldown into the group

GetRank

int GetRank(int nGroup,
            int nRowWithinGroup)

Maps from the result ranking within a group to the overall (ungrouped) result ranking. For example, the highest ranking result in group 2 might be the 4th-ranked result overall. In this case, GetRank(2,0) would return 3 (note ranking is zero-based). Note that methods like GetFields() index results by the ungrouped ranking, so if you are presenting results by group this will probably be the first method you call for each result row.

Parameters:

nGroupIndex - Desired group, from 0 to (GetNumGroups()-1).

nRowWithinGroup - Result within the group, from 0 to (GetReturnedResultsInGroup(nGroupIndex)-1).

Returns:

overall rank of the result.

GetReturnedResultsNotInAnyGroup

int GetReturnedResultsNotInAnyGroup()

Returns the number of displayable results that did not fall in any group.

Returns:

the number of displayable results that did not fall in any group.

GetQueryForAllOthers

IPTSearchQuery GetQueryForAllOthers()

Like GetQueryForGroup(), returns an IPTSearchQuery that may be used to drill down into the "all others" set of results that did not fall in any coherent group.

Returns:

query for drilldown into the uncategorized set.

GetRankForUncategorizedDoc

int GetRankForUncategorizedDoc(int rankWithinAllOthers)

Like GetRank(), maps from the rank in the uncategorized "all others" set to the overall result ranking.

Parameters:

rankWithinAllOthers - rank in uncategorized set, from 0 to (GetReturnedResultsNotInAnyGroup()-1).

Returns:

overall rank of the result.

GetTotalResultsNotInAnyGroup

java.lang.Object GetTotalResultsNotInAnyGroup()

Returns an estimate the number of results in the overall result set (not just those displayed) that did not fall into any group. The estimate is a string of the form "~ 1000".

Returns:

a String estimate of the total results not in any group.

GetFieldsAsInt

int GetFieldsAsInt(int nRank,
                   int nPropertyID)

Returns the value of a single field (property) in a single search result.

This is the method to call if you want the Object ID of a search result - pass PT_INTRINSICS.PT_PROPERTY_OBJECTID for nPropertyID.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

nPropertyID - ID of the property desired, or one of the special-case pseudoproperties given by PT_INTRINSICS in the ranges [1,8] and [51,58]. Must be an integer-valued property.

Returns:

the property value.

GetFieldsAsString

java.lang.String GetFieldsAsString(int nRank,
                                   int nPropertyID)

Returns the value of a single field (property) in a single search result.

This is the method to call if you want the name of a search result - pass PT_INTRINSICS.PT_PROPERTY_OBJECTNAME for nPropertyID.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

nPropertyID - ID of the property desired, or one of the special-case pseudoproperties given by PT_INTRINSICS in the ranges [1,8] and [51,58]. Must be a text property.

Returns:

the property value.

GetFieldsAsXPDateTime

com.plumtree.openfoundation.util.XPDateTime GetFieldsAsXPDateTime(int nRank,
                                                                  int nPropertyID)

Returns the value of a single field (property) in a single search result.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

nPropertyID - ID of the property desired, or one of the special-case pseudoproperties given by PT_INTRINSICS in the ranges [1,8] and [51,58]. Must be a date-valued property.

Note: PT_INTRINSICS.PT_PROPERTY_OBJECTCREATED and PT_INTRINSICS.PT_PROPERTY_OBJECTLASTMODIFIED have special-case behavior; despite being dates they are returned as type Double. Instead of this method call GetFieldsAsDouble(), then SearchResultModel.ConvertSearchDateTimeToXPDateTime() to convert to date.

Returns:

the property value.

GetFieldsAsDouble

double GetFieldsAsDouble(int nRank,
                         int nPropertyID)

Returns the value of a single field (property) in a single search result.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

nPropertyID - ID of the property desired, or one of the special-case pseudoproperties given by PT_INTRINSICS in the ranges [1,8] and [51,58]. Must be a double-valued property (or the OBJECTCREATED or OBJECTLASTMODIFIED intrinsics, see the comment for GetFieldsAsXPDateTime).

Returns:

the property value.

GetFieldsAsObject

java.lang.Object GetFieldsAsObject(int nRank,
                                   int nPropertyID)

Returns the value of a single field (property) in a single search result.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

nPropertyID - ID of the property desired, or one of the special-case pseudoproperties given by PT_INTRINSICS in the ranges [1,8] and [51,58].

Returns:

the property value; the property type determines the return type.

GetKWICFieldsAsInt

int GetKWICFieldsAsInt(int nRank,
                       int nPropertyID)

Behaves identically to GetFieldsAsInt; call that method instead.

GetKWICFieldsAsString

java.lang.String GetKWICFieldsAsString(int nRank,
                                       int nPropertyID)

Returns keyword-in-context ("KWIC") information for the given result and property. This is a String containing snippets of text from the given result; search keywords from the original query are enclosed in highlight tags that specify an HTML span of style listHiliteText.

This method is usually called with PT_INTRINSICS.PT_PROPERTY_OBJECTSUMMARY, in which case it has special-case behavior to find the best KWIC information from the OBJECTSUMMARY and full-text content fields. This is how the portal generates the summaries that appear below the result title. However, you may call it with any other property used to constrain the search, and it will return KWIC info for that property if it exists.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

nPropertyID - PT_INTRINSICS.PT_PROPERTY_OBJECTSUMMARY or another text property ID

Returns:

keyword-in-context string with search keywords enclosed in listHiliteText span tags

GetKWICFieldsAsXPDateTime

com.plumtree.openfoundation.util.XPDateTime GetKWICFieldsAsXPDateTime(int nRank,
                                                                      int nPropertyID)

Behaves identically to GetFieldsAsXPDateTime; call that method instead.

GetKWICFieldsAsDouble

double GetKWICFieldsAsDouble(int nRank,
                             int nPropertyID)

Behaves identically to GetFieldsAsDouble; call that method instead.

GetKWICFieldsAsObject

java.lang.Object GetKWICFieldsAsObject(int nRank,
                                       int nPropertyID)

Call GetFieldsAsObject() or GetKWICFieldsAsString() instead, depending on what you want.

GetResultPath

java.lang.String GetResultPath(int nRank)

Returns the full path to the object, in text form.

Portal documents may live in more than one folder. If so, this method returns one folder path chosen more or less at random, and there is no guarantee that the user has rights to this particular folder (although s/he must have rights to one of the doc's folders). To check this, call GetResultInternalField() and request PT_SEARCH_INTERNAL_FIELD.PT_SEARCH_IF_PARENTIDS; if there is more than one parent (i.e. a space appears in this string) you should not display the path.

Also, the path may not be localized to the user's current locale.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

Returns:

the path, with the caveats listed above

GetResultApp

java.lang.String GetResultApp(int nRank)

Returns the application that indexed this result: one of PTPORTAL (portal items), PTCONTENT (Content Server), PTCONTENTTEMPLATE (Branding Engine), or PTCOLLAB (Collaboration Server).

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

Returns:

one of PTPORTAL, PTCONTENT, PTCONTENTTEMPLATE, PTCOLLAB

GetResultSubType

java.lang.String GetResultSubType(int nRank)

Returns the application-specific type of the result.

For portal objects, possible values are currently: PTUSER, PTGROUP, PTAUTHSOURCE, PTPROFILESOURCE, PTFOLDER, PTCARD, PTADMINFOLDER, PTFILTER, PTSAVEDSEARCH, PTDATASOURCE, PTCARDPROPERTY, PTDOCUMENTTYPE, PTCRAWLER, PTGADGET, PTINVITATION, PTFEDPORTAL, PTGADGETSERVER, PTCOMMTEMPLATE, PTGADGETBUNDLE, PTPAGETEMPLATE, PTWEBSERVICE, PTEXTOPERATION, PTGADGETTEMPLATE, PTJOB, PTCOMMUNITY.

For Collaboration Server items, returns PTCOLLAB.

For Content Server items, returns PTCONTENT.

For Branding Engine items, returns PTCOMMUNITY, so these items appear in the "community" category.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

Returns:

app-specific type of the result, listed above.

GetResultAbsType

java.lang.String GetResultAbsType(int nRank)

Abstractified, cross-application type of the result: "DOCUMENT", "CONTAINER", or "OTHER".

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

Returns:

DOCUMENT, CONTAINER, or OTHER.

GetResultSize

int GetResultSize(int nRank)

Returns the size of the result in bytes, or a negative value if unknown.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

Returns:

result size, or a negative value if unknown

GetIsBestBet

boolean GetIsBestBet(int nRank)

Returns true if the result appears in the result set (or if its rank was affected) because of a Best Bet.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

Returns:

whether the result was affected by a Best Bet

GetResultACL

java.lang.String GetResultACL(int nRank)

Returns the ACL of the result (for portal objects only), or the list of Collab roles that have access to the result (for Collab objects only).

For portal objects, both the ACL and folder ACL must match the user's access rights. Portal ACLs are returned as a space-separated string of group IDs and user IDs, where the user IDs are prefixed with the character 'u'.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

Returns:

the result's ACL

GetResultFolderACL

java.lang.String GetResultFolderACL(int nRank)

Returns the ACL of the result's folder (for portal objects only). Both the ACL and folder ACL must match the user's access rights. The folder ACL is returned as a space-separated string of group IDs and user IDs, where the user IDs are prefixed with the character 'u'.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

Returns:

the result's folder's ACL

GetResultInternalField

java.lang.String GetResultInternalField(int nRank,
                                        int nInternalFieldID)

Returns the value of one of several "internal fields" that don't correspond to properties and that aren't important enough to merit their own method. See the PT_SEARCH_INTERNAL_FIELD enumeration for a list of these.

Parameters:

nRank - Ungrouped result rank, in the range 0 to (GetReturnedResults()-1).

nInternalFieldID - Internal field ID, one of the members of PT_SEARCH_INTERNAL_FIELD.

Returns:

internal field value

Clear

void Clear()

Clears this object and releases memory associated with it, which may be substantial. In the COM implementation, calling this as soon as possible avoids filling the unmanaged COM heap with large search results that wouldn't be freed until a garbage collection runs (possibly much later). No other method on this object may be called after Clear().