com.plumtree.server
Interface IPTIndexer

public interface IPTIndexer

Interface for class which manages the indexing, updating, and deleting of cards, folders, and administrative objects. The methods in this interface are not intended for general custom use, they are intended for use by Plumtree server, crawler, and agent code.

Version:

$Revision$

Author:

MarcusM

Method Summary

void	ClearProfile() Clear the current profile query.
IPTIndexer	Clone() Create a new IPTIndexer object that is a copy of the current one.
java.lang.Object	CommitAll() "Assynchronous" commit - client doesn't need to wait to make sure that the request was fully processed by the search server.
java.lang.Object	CommitAll(int timeiout) Send any pending index, update, or delete requests to the Search Server.
java.lang.Object	CommitAsProfiled(int profileMode) Send any pending profile requests to the Search Server.
java.lang.Object	GetSettings(int lSettingID) Return the value of settings for the PTIndexer object.
void	IndexAdminObject(int nClassID, int nObjectID) Add a searchable representation of an administrative object to the current list of items awaiting indexing.
void	IndexCard(int nCardID, IPTCardPropertyValues pPropertyValues, IPTAccessList pCardBrowseACL, IPTAccessList pFolderBrowseACL, java.lang.Object vsaAncestors, java.lang.String bstrDocumentPath, java.lang.String bstrProvCLSID, boolean bSummarize) Add a searchable representation of a card to the current list of items awaiting indexing.
void	IndexFolder(int nFolderID, com.plumtree.openfoundation.util.IXPPropertyBag pFolderPropBag, IPTAccessList pBrowseACL, java.lang.Object vsaAncestors) Add a searchable representation of a folder to the current list of items awaiting indexing.
int	LoadQuery(java.lang.Object vSearchFilter) Load a query (in the form of an IPTFilter) into the current set of filter queries, returning an integer id that can be used to refer to the filter later.
boolean	Matched(int lCardID, int lQueryID) Check the current Profile results to determine if a given card matches a given query.
void	RemoveAdminObjects(int ClassID, java.lang.Object vsaObjectIDs) Request deletion of a set of objects of a given class, given the class id and an int[] array of object ids.
com.plumtree.openfoundation.util.IXPPropertyBag	RetrieveStatus() Return a PropertyBag containing status information about the indexing Search Server.
java.lang.Object	RunProfile(java.lang.String bstrFilePath) Deprecated.
boolean	RunSingleQueryProfile(java.lang.String bstrQuery, java.lang.String bstrFilePath) Deprecated.
void	SetSettings(int lSettingID, java.lang.Object pvValue) Set the value of settings for the PTIndexer object.
java.lang.String	SummarizeDocument(java.lang.String bstrPath) Only called during manual card submission, this method takes a full path to a file and extracts a String "summary" consisting of the first words of the full text found in the file.
void	UnindexCards(java.lang.Object vsaObjectIDs) Request deletion of a set of cards, given an int[] array of object ids.
void	UnindexFolders(java.lang.Object vsaObjectIDs) Request deletion of a set of folders, given an int[] array of object ids.
void	UpdateCard(int nCardID, IPTCardPropertyValues pPropertyValues, IPTAccessList pCardBrowseACL, IPTAccessList pFolderBrowseACL, java.lang.Object vsaAncestors) Add a searchable representation of a card to the current list of items awaiting property updating.
java.lang.String	waitForAllIndexRequestsToComplete(int timeout) Wait until all the index requests initiated by the client have been processed by the search server.

Method Detail

IndexCard

void IndexCard(int nCardID,
               IPTCardPropertyValues pPropertyValues,
               IPTAccessList pCardBrowseACL,
               IPTAccessList pFolderBrowseACL,
               java.lang.Object vsaAncestors,
               java.lang.String bstrDocumentPath,
               java.lang.String bstrProvCLSID,
               boolean bSummarize)

Add a searchable representation of a card to the current list of items awaiting indexing. Does not actually index the item in the search server, indexing is triggered by CommitAll().

Parameters:

nCardID - The object id of the card to index

pPropertyValues - IPTCardPropertyValues enumerating the properties of the card to index.

pCardBrowseACL - IPTAccessList of ACLs defining who can read this card.

pFolderBrowseACL - IPTAccessList of ACLs defining who can read the folder containing this card.

vsaAncestors - An int[] array. The vsaAncestors array passed into this code should contain a merged list of all immediate parent folder IDs and their ancestors. If an entry is negative, it is interpreted as an immediate parent folder id.

So if a card exists in folders 203, 210, and 230 and the folder structures appeared as follows...

• 200----(parent of)---->203
• 205----(parent of)---->207----(parent of)---->210
• 215----(parent of)---->216----(parent of)---->230 *

you would end up with a vsaAncestors array with entries as follows:
200,-203,205,207,-210,215,216,-230

bstrDocumentPath - Full path to a local file for the document underlying this card. Full text will be extracted from this file using OutsideIn.

bstrProvCLSID - CLSID of the provider for the data source of this card, this information is indexed along with the card.

bSummarize - If true, a summary will be extracted from the full-text content of the card. If false, the summary will be drawn from the card properties (blank if there is no summary property).

UpdateCard

void UpdateCard(int nCardID,
                IPTCardPropertyValues pPropertyValues,
                IPTAccessList pCardBrowseACL,
                IPTAccessList pFolderBrowseACL,
                java.lang.Object vsaAncestors)

Add a searchable representation of a card to the current list of items awaiting property updating. Does not actually index the item in the search server, indexing is triggered by CommitAll().

Parameters:

nCardID - The object id of the card to index

pPropertyValues - IPTCardPropertyValues enumerating the properties of the card to index.

pCardBrowseACL - IPTAccessList of ACLs defining who can read this card.

pFolderBrowseACL - IPTAccessList of ACLs defining who can read the folder containing this card.

vsaAncestors - An int[] array of ancestor folder ids, as described in IndexCard()

IndexFolder

void IndexFolder(int nFolderID,
                 com.plumtree.openfoundation.util.IXPPropertyBag pFolderPropBag,
                 IPTAccessList pBrowseACL,
                 java.lang.Object vsaAncestors)

Add a searchable representation of a folder to the current list of items awaiting indexing. Does not actually index the item in the search server, indexing is triggered by CommitAll().

Parameters:

nFolderID - Object id of the folder to index

pFolderPropBag - PropertyBag with folder properties

pBrowseACL - IPTAccessList determining who can read this folder

vsaAncestors - An int[] array of ancestor folder ids, as described in #IndexCard().

UnindexCards

void UnindexCards(java.lang.Object vsaObjectIDs)

Request deletion of a set of cards, given an int[] array of object ids. You must call CommitAll() for the request to be processed by the Search Server. This method has no effect if the object ids in question do not exist.

Parameters:

vsaObjectIDs - int[] array of object ids for the cards to delete. Throws PT_RESULTCODES.PT_E_INVALIDARG if passed something other than an int[] array. If the argument is null or empty, this method has no effect.

UnindexFolders

void UnindexFolders(java.lang.Object vsaObjectIDs)

Request deletion of a set of folders, given an int[] array of object ids. You must call CommitAll() for the request to be processed by the Search Server. This method has no effect if the object ids in question do not exist.

Parameters:

vsaObjectIDs - int[] array of object ids for the folders to delete. Throws PT_RESULTCODES.PT_E_INVALIDARG if passed something other than an int[] array. If the argument is null or empty, this method has no effect.

IndexAdminObject

void IndexAdminObject(int nClassID,
                      int nObjectID)

Add a searchable representation of an administrative object to the current list of items awaiting indexing. Does not actually index the item in the search server, indexing is triggered by CommitAll(). For portlets, there may be side-effect indexing of associated Content Server items.

Parameters:

nClassID - The class id of the object to index. Should be a value from PT_CLASSIDS.

nObjectID - The object id of the object to index. Should be greater than 0.

RemoveAdminObjects

void RemoveAdminObjects(int ClassID,
                        java.lang.Object vsaObjectIDs)

Request deletion of a set of objects of a given class, given the class id and an int[] array of object ids. You must call CommitAll() for the request to be processed by the Search Server. This method has no effect if the object ids in question do not exist.

Parameters:

ClassID - int Class id of the objects to delete.

vsaObjectIDs - int[] array of object ids for the objects to delete. Throws PT_RESULTCODES.PT_E_INVALIDARG if passed something other than an int[] array. If the argument is null or empty, this method has no effect.

CommitAll

java.lang.Object CommitAll(int timeiout)

Send any pending index, update, or delete requests to the Search Server. This method must be called in order for IndexCard(), IndexFolder(), IndexAdminObject(), and related update and delete methods to have any effect. If the Add request throws an OpenSearchConvertException, then we catch it and return valid failure information. If we throw some other kind of exception, then the data in the results array is undefined.

Parameters:

timeout - - time( in milliseconds to wait for a commit(index) request to be fully processed by the search server.

Returns:

A 2D array Object[][] with information about the results of processing each pending request. The first index addresses individual requests, and its range varies depending on the number of index/update/delete calls up to this point. The second index (always 4 dimensions) addresses the success/failure status, the type of request, the id of the searchable item, and the summary of the full text of the item as returned by OutsideIn.

For example, an array Object[totalItems][4] will be returned where totalItems = numAdded + numUpdated + numDeleted. The format of the entries is:

• results[i][0] - Integer (0 means a successful request, 1 means a failed request)
• results[i][1] - Integer for the type of request, always a value from the PT_DOC_ACTION_TYPES enumeration.
• results[i][2] - String ID of the searchable item that was processed. For portal objects, this id is of the form "X.Y" where X is the class id and Y is the object id of the item. For Collaboration Server or Content Server items, the ID has a different form that is outside the scope of this documentation.
• results[i][3] - String document summary. Never null, may be blank if no automatically generated summary was requested or if OutsideIn full-text extraction failed. This summary information is used when a number of indexing requests of documents are processed (e.g. in a crawl). The indexing requests are made with repeated calls to IndexCard(), then the summaries are extracted and returned when CommitAll() is called.

CommitAll

java.lang.Object CommitAll()

"Assynchronous" commit - client doesn't need to wait to make sure that the request was fully processed by the search server.

See Also:

CommitAll(int timeout)

GetSettings

java.lang.Object GetSettings(int lSettingID)

Return the value of settings for the PTIndexer object.

• PT_SEARCHCOLLECTION_LANGUAGE - String Language code used for tokenizing text that is indexed by this object.
• Note that no other setting can be retrieved.

Parameters:

lSettingID - Setting value from the PT_SEARCHCOLLECTION_SETTINGS enumeration. PT_SEARCHCOLLECTION_LANGUAGE is the only legal value, unrecognized values return null.

Returns:

Value of the desired setting.

SetSettings

void SetSettings(int lSettingID,
                 java.lang.Object pvValue)

Set the value of settings for the PTIndexer object.

• PT_SEARCHCOLLECTION_LANGUAGE - String Language code used for tokenizing text that is indexed by this object.
• PT_SEARCHCOLLECTION_PROPMAP_DIRTY - int When set to a nonzero value, indicates that a Property has been added or has changed type.
• PT_SEARCHCOLLECTION_CONNECT_PARAMS_DIRTY - int When set to a nonzero value, indicates that the Search Server host or port number has changed.
• Note that all other settings in the PT_SEARCHCOLLECTION_SETTINGS enumeration unused and deprecated.

Parameters:

lSettingID - Setting id from the PT_SEARCHCOLLECTION_SETTINGS enumeration.

vValue - Setting value, required type varies by id.

RetrieveStatus

com.plumtree.openfoundation.util.IXPPropertyBag RetrieveStatus()

Return a PropertyBag containing status information about the indexing Search Server.

Returns:

An IXPPropertyBag with attributes:

• CONNECTSTATUS - OK if connection to the indexing Search Server is successful
• CURRENTDIRECTORY
• INDEXDIRECTORY
• UPTIME
• TOTALINDEXEDDOCS
• TOTALLIVEDOCS
• TOTALDEADDOCS
• STATICARCHIVES
• DYNAMICARCHIVES
• STATICDYNMERGES
• STATICMERGES
• TOTALERRORS
• ERRORS
• HOSTNAME
• PORTNUMBER
• READONLY

Clone

IPTIndexer Clone()

Create a new IPTIndexer object that is a copy of the current one. The returned object has a reference to the same ProfileQuery (used for taxonomization) as the cloned object. The returned object has a reference to the cloned object as its "parent".

Returns:

IPTIndexer copy of the current instance.

LoadQuery

int LoadQuery(java.lang.Object vSearchFilter)

Load a query (in the form of an IPTFilter) into the current set of filter queries, returning an integer id that can be used to refer to the filter later. The caller should keep track of the integer ids generated in the course of calling LoadQuery() multiple times.

Parameters:

vSearchFilter - IPTFilter representing a filter query to be used for taxonomization. Should not be null.

Returns:

int ID of this query in the current set of filters. This id can be used later with the Matched(int,int) method to determine whether a particular card matched a particular filter.

CommitAsProfiled

java.lang.Object CommitAsProfiled(int profileMode)

Send any pending profile requests to the Search Server. Profile requests are similar to add requests, except that they simultaneously match the items in the request against a set of filters which were added using the LoadQuery(Object) method. The profile request returns results (stored inside the IPTIndexer object) that indicate which items matched which queries.

The usage pattern is for the caller to make

• multiple calls to LoadQuery(Object), loading up the filters to use for taxonomization
• multiple calls to IndexCard(), adding the cards to be taxonomized
• a call to CommitAsProfiled(int), which indexes the documents and matches them against the loaded filters
• multiple calls to Matched(int,int) to determine which documents matched which filters.

  Parameters:

  profileMode - int profiling mode identifier, passed through to the underlying profiling engine. Must be a value from the PT_PROFILER_MODE enumeration.

  Returns:

  A 2D array Object[][] with information about the results of processing each pending request. Same format as CommitAll().

Matched

boolean Matched(int lCardID,
                int lQueryID)

Check the current Profile results to determine if a given card matches a given query. Returns true if it matched, false otherwise. Should only be called after CommitAsProfiled(int)

Parameters:

lCardID - Object ID of the card to check.

lQueryID - int ID of the query to match against

Returns:

True if the card matched the query, false otherwise.

ClearProfile

void ClearProfile()

Clear the current profile query.

SummarizeDocument

java.lang.String SummarizeDocument(java.lang.String bstrPath)

Only called during manual card submission, this method takes a full path to a file and extracts a String "summary" consisting of the first words of the full text found in the file.

Parameters:

bstrPath - Full path to the file from which we'll extract the summary. Should not be null.

Returns:

String summary. May be blank if full-text extraction fails. Size of the summary is governed by the value of the server config setting PT_SERVER_CONFIG_SETTINGNAME.PT_SEARCH_DOCUMENT_SUMMARY_SIZE.

waitForAllIndexRequestsToComplete

java.lang.String waitForAllIndexRequestsToComplete(int timeout)
                                                   throws PTException

Wait until all the index requests initiated by the client have been processed by the search server. A client should invoke this method only if it must ensure that everything that it submitted over a period of time is searchable. This is not the way to simulate "synchronous" indexing. Use CommitAll(int timeout) instead. Us this method sparignly since it can potentialy create many search cluster status requests.

Parameters:

timeout - - amout of time to wait for everything to be processed

Returns:

current known fully processed(i.e searchable) transaction id

Throws:

PTException - if the timeout occurs

RunProfile

java.lang.Object RunProfile(java.lang.String bstrFilePath)

Deprecated.

Obsolete, based on unused taxonomization code.

RunSingleQueryProfile

boolean RunSingleQueryProfile(java.lang.String bstrQuery,
                              java.lang.String bstrFilePath)

Deprecated.

Obsolete, based on unused taxonomization code.