com.bmc.arsys.fts

Interface FTSService

public interface FTSService

Interface for the wrapper that wraps the Apache Lucene indexing engine for use with AR FTS.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	FTSService.EntryData Object that is returned on FTS standard queries.
static class	FTSService.FTSResultSet Object that is returned by a getEntryIdsByGlobalQuery TODO: Consider having a method to get GlobalEntryData and have that method do the casting rather than having the item retriving it cast it.
static class	FTSService.GlobalEntryData Object that is returned inside FTSResultSet on MFS queries.
static class	FTSService.QuerySchemas Object that passed in as one of the parameters for getEntryIdsByGlobalQuery.
static class	FTSService.ReturnFilterFields Object that passed in as one of the parameters for getEntryIdsByGlobalQuery.

Field Summary

Fields

Modifier and Type	Field and Description
static String	AR_FTS_FIELD_NAME_CREATE_TIME
static String	AR_FTS_FIELD_NAME_MODIFIED_TIME
static String	AR_FTS_FIELD_NAME_TITLE
static int	AR_FTS_MULTIGET_EXCERPT_NONE
static int	AR_FTS_MULTIGET_RESULTOPT_DOCIDONLY
static int	AR_FTS_MULTIGET_RESULTOPT_EXCERPT
static int	AR_FTS_MULTIGET_RESULTOPT_NOENTRIES
static int	AR_FTS_MULTIGET_RESULTOPT_NONE
static int	AR_FTS_MULTIGET_RESULTOPT_WAH
static String	AR_FTS_MULTIGET_SORTBY_DATE_CREATE
static String	AR_FTS_MULTIGET_SORTBY_DATE_MODIFY
static String	AR_FTS_MULTIGET_SORTBY_ENTRYID
static String	AR_FTS_MULTIGET_SORTBY_EXCERPT
static String	AR_FTS_MULTIGET_SORTBY_SCHEMAID
static String	AR_FTS_MULTIGET_SORTBY_TITLE
static String	AR_FTS_MULTIGET_SORTBY_WEIGHT
static String	AR_SORT_ASCENDING
static String	AR_SORT_DESCENDING
static String	DOC_ID_FIELD
static String	ENTRY_ID_FIELD
static String	LOG_FILE_APPENDER
static String	SCHEMA_ID_FIELD
static String	SEPARATOR

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Safely closes any opened class resources.
void	commit() Commits the indexed data to disk.
void	deleteDocuments(String schemaId, boolean deleteIndexDir) close the index searcher, reader and writer, and delete the index directory of the schema
void	deleteDocumentsContainingField(String schemaId, String fieldName, String fieldValue) Deletes all documents which contain a specific field and field value.
void	deleteEntryDocument(String schemaId, String entryId) Deletes document with the docid = schemaId##entryId.
void	deleteIndexDir() Delete the contents of the index collection directory.
FTSService.FTSResultSet	getEntryIdsByGlobalQuery(String shouldQueryValue, String mustQueryValue, String notQueryValue, List<FTSService.QuerySchemas> querySchemas, String filterQuery, List<FTSService.ReturnFilterFields> returnFilterFields, String sortOrder, int resultOption, Map<String,String> returnEntries, int maxReturn) TODO: Remove when plugin moves to newer overload
FTSService.FTSResultSet	getEntryIdsByGlobalQuery(String shouldQueryValue, String mustQueryValue, String notQueryValue, List<FTSService.QuerySchemas> querySchemas, String filterQuery, List<FTSService.ReturnFilterFields> returnFilterFields, String sortOrder, int resultOption, Map<String,String> returnEntries, int maxReturn, String markupLeft, String markupRight) Returns an FTSResultSet which contains a list of EntryData objects resulting from a query.
List<FTSService.EntryData>	getEntryIdsByQuery(String schemaId, String[] queryFieldNames, String[] queryFieldValues, BitSet[] fullTextOption) Returns a list of EntryData objects resulting from a query.
com.bmc.arsys.fts.impl.lucene.IndexDocIterator	getIndexIterator(String schemaId) return an index iterator for the given schema.
void	indexAttachmentByPath(String schemaId, String entryId, float docBoost, String fieldNames, List<String> values, BitSet fullTextOptions, float fieldBoost, int doCommit)
void	indexEntryFields(String schemaId, String entryId, float docBoost, String[] fieldNames, String[] values, BitSet[] fullTextOptions, float[] fieldBoost, int doCommit) Indexes fields for a document.
void	init(com.bmc.arsys.fts.impl.FTSConfiguration ftsConfiguration) Initializes the FTSService ftsConfiguration provides the configuration information used in the initialization.
void	init(com.bmc.arsys.fts.impl.FTSConfiguration ftsConfiguration, boolean isWriter) Initializes the FTSService ftsConfiguration provides the configuration information used in the initialization.
void	reInitializeSearchEngines(String ftsPluginName) Reinitialize the search service references.
void	removeFieldFromDocumentsByQuery(String schemaId, String fieldName, String[] queryFieldNames, String[] queryFieldValues) Removes a field from the documents resulting from a query.
void	removeFieldFromDocumentsByQuery(String schemaId, String fieldName, String[] queryFieldNames, String[] queryFieldValues, int doCommit) Removes a field from the documents resulting from a query.
void	setDocBoost(String schemaId, String entryId, float docBoost) Set a document boost value.
void	updateConfiguration() Causes FTSAnalyzer to pick up any configuration changes and process with those changes from this point forward.

Field Detail

DOC_ID_FIELD

static final String DOC_ID_FIELD

See Also:

Constant Field Values

SCHEMA_ID_FIELD

static final String SCHEMA_ID_FIELD

See Also:

Constant Field Values

ENTRY_ID_FIELD

static final String ENTRY_ID_FIELD

See Also:

Constant Field Values

SEPARATOR

static final String SEPARATOR

See Also:

Constant Field Values

AR_FTS_FIELD_NAME_MODIFIED_TIME

static final String AR_FTS_FIELD_NAME_MODIFIED_TIME

See Also:

Constant Field Values

AR_FTS_FIELD_NAME_CREATE_TIME

static final String AR_FTS_FIELD_NAME_CREATE_TIME

See Also:

Constant Field Values

AR_FTS_FIELD_NAME_TITLE

static final String AR_FTS_FIELD_NAME_TITLE

See Also:

Constant Field Values

AR_FTS_MULTIGET_RESULTOPT_NONE

static final int AR_FTS_MULTIGET_RESULTOPT_NONE

See Also:

Constant Field Values

AR_FTS_MULTIGET_RESULTOPT_EXCERPT

static final int AR_FTS_MULTIGET_RESULTOPT_EXCERPT

See Also:

Constant Field Values

AR_FTS_MULTIGET_RESULTOPT_WAH

static final int AR_FTS_MULTIGET_RESULTOPT_WAH

See Also:

Constant Field Values

AR_FTS_MULTIGET_RESULTOPT_NOENTRIES

static final int AR_FTS_MULTIGET_RESULTOPT_NOENTRIES

See Also:

Constant Field Values

AR_FTS_MULTIGET_RESULTOPT_DOCIDONLY

static final int AR_FTS_MULTIGET_RESULTOPT_DOCIDONLY

See Also:

Constant Field Values

AR_FTS_MULTIGET_EXCERPT_NONE

static final int AR_FTS_MULTIGET_EXCERPT_NONE

See Also:

Constant Field Values

LOG_FILE_APPENDER

static final String LOG_FILE_APPENDER

See Also:

Constant Field Values

AR_FTS_MULTIGET_SORTBY_SCHEMAID

static final String AR_FTS_MULTIGET_SORTBY_SCHEMAID

See Also:

Constant Field Values

AR_FTS_MULTIGET_SORTBY_ENTRYID

static final String AR_FTS_MULTIGET_SORTBY_ENTRYID

See Also:

Constant Field Values

AR_FTS_MULTIGET_SORTBY_TITLE

static final String AR_FTS_MULTIGET_SORTBY_TITLE

See Also:

Constant Field Values

AR_FTS_MULTIGET_SORTBY_EXCERPT

static final String AR_FTS_MULTIGET_SORTBY_EXCERPT

See Also:

Constant Field Values

AR_FTS_MULTIGET_SORTBY_WEIGHT

static final String AR_FTS_MULTIGET_SORTBY_WEIGHT

See Also:

Constant Field Values

AR_FTS_MULTIGET_SORTBY_DATE_CREATE

static final String AR_FTS_MULTIGET_SORTBY_DATE_CREATE

See Also:

Constant Field Values

AR_FTS_MULTIGET_SORTBY_DATE_MODIFY

static final String AR_FTS_MULTIGET_SORTBY_DATE_MODIFY

See Also:

Constant Field Values

AR_SORT_ASCENDING

static final String AR_SORT_ASCENDING

See Also:

Constant Field Values

AR_SORT_DESCENDING

static final String AR_SORT_DESCENDING

See Also:

Constant Field Values

Method Detail

init

void init(com.bmc.arsys.fts.impl.FTSConfiguration ftsConfiguration)
          throws FTSServiceException

Initializes the FTSService ftsConfiguration provides the configuration information used in the initialization. This overload of the method will instantiate as a writer instance.

Parameters:

ftsConfiguration - configuration data.

Throws:

FTSServiceException

init

void init(com.bmc.arsys.fts.impl.FTSConfiguration ftsConfiguration,
        boolean isWriter)
          throws FTSServiceException

Initializes the FTSService ftsConfiguration provides the configuration information used in the initialization. isWriter declares if this instance is a writer or reader only.

Parameters:

ftsConfiguration - configuration data.

isReader - declare instance as a writer.

Throws:

FTSServiceException

indexEntryFields

void indexEntryFields(String schemaId,
                    String entryId,
                    float docBoost,
                    String[] fieldNames,
                    String[] values,
                    BitSet[] fullTextOptions,
                    float[] fieldBoost,
                    int doCommit)
                      throws FTSServiceException

Indexes fields for a document. fieldNames are indexed with fieldValues for the document associated with docId=schemaId_ entryId. The docId must be unique for each document in the system. If no document exists for the given docId, then a new document will be created. The following illustrates how fieldNames and fieldValues are indexed:

(fieldName1:fieldValue1) (fieldName2:fieldValue2)...(fieldNameX:fieldValueX)

Parameters:

schemaId - id of the schema.

entryId - id of the entry.

fieldValues - Map of all the entry field to index.

Throws:

FTSServiceException

indexAttachmentByPath

void indexAttachmentByPath(String schemaId,
                         String entryId,
                         float docBoost,
                         String fieldNames,
                         List<String> values,
                         BitSet fullTextOptions,
                         float fieldBoost,
                         int doCommit)
                           throws FTSServiceException

Throws:

FTSServiceException

setDocBoost

void setDocBoost(String schemaId,
               String entryId,
               float docBoost)
                 throws FTSServiceException

Set a document boost value. A document boost value allows that document (entry) to have a higher or lower score when it is included in a search result. Boosting a document is a way to improve this item's score against another when all other things are equal.

docBoost should be a value between 0 - 2 with 1 being the default of no boost. A value of 0 will make that item so that it is never found on a search. Anything lower than 1 will reduce a documents score. Anything above 1 will increase the score.

Parameters:

schemaId - the schema ID of the entry to boost.

entryId - the Entry ID of the entry to boost.

docBoost - the boost value to assign the entry.

Throws:

FTSServiceException

deleteIndexDir

void deleteIndexDir()
                    throws FTSServiceException

Delete the contents of the index collection directory. The directory itself will remain.

Throws:

FTSServiceException

getEntryIdsByQuery

List<FTSService.EntryData> getEntryIdsByQuery(String schemaId,
                                            String[] queryFieldNames,
                                            String[] queryFieldValues,
                                            BitSet[] fullTextOption)
                                              throws FTSServiceException

Returns a list of EntryData objects resulting from a query. A query is performed against multiple fields using the names and values in queryFieldName and queryFieldValues. The documents resulting from the query are used to return a list of entry id. If the given fieldName is not found or if no documents are found, then an empty list is returned. The following illustrates how queryFieldName and queryFieldValues are used to construct the query:

(queryFieldName:queryFieldValue1) (queryFieldName:queryFieldValue2)...(queryFieldName:queryFieldValueX)

Parameters:

schemaId - id of the schema.

queryFieldNames - Array of field names to query.

queryFieldValues - Array of field values to query.

fullTextOption - BitSet Array indicating literal or non literal status of field.

Returns:

An EntryData object list of string values for the given fieldName.

Throws:

FTSServiceException

getEntryIdsByGlobalQuery

FTSService.FTSResultSet getEntryIdsByGlobalQuery(String shouldQueryValue,
                                               String mustQueryValue,
                                               String notQueryValue,
                                               List<FTSService.QuerySchemas> querySchemas,
                                               String filterQuery,
                                               List<FTSService.ReturnFilterFields> returnFilterFields,
                                               String sortOrder,
                                               int resultOption,
                                               Map<String,String> returnEntries,
                                               int maxReturn,
                                               String markupLeft,
                                               String markupRight)
                                                 throws FTSServiceException

Returns an FTSResultSet which contains a list of EntryData objects resulting from a query. A query is performed against multiple schemas and mulitple fields. This method is very flexible and can return different data based on the parameters used.

The shouldQueryValue, mustQueryValue, notQueryValue are opoitonal but either a shouldQueryValue or a mustQueryValue is required to get a search result. The notQueryValue must also have a shouldQueryValue or a mustQueryValue value defined.

This method can be used for a single search request, or a two phase search request to falicitate performance. The resultOption and returnEntries parameters define if it is a two phase query and which phase. If resultOption is set to AR_FTS_MULTIGET_RESULTOPT_DOCIDONLY then this indicates phase one and therefore the results will only return the schemaId, entryId, and score so that some post processing can be done to pick the desired result set. Then a phase two is initiatied by sending the same parameters except changing resultOption to one of the other choices (generally requesting WAH), and supplying the desired entries for return in the returnEntries parameter which will only return the requested items.

Parameters:

shouldQueryValue - words that should (may/OR) be in the result. May be NULL.

mustQueryValue - words that must be in the resultt. May be NULL.

notQueryValue - words that must not be in the result. May be NULL.

querySchemas - ArrayList that indicate the schemas and the corresponding fields to be searched. It is required for all queries.

filterQuery - filters the query to only search against items that match the filter. May be NULL. If provided only items in the index that match it will be used to search against. It is a string of the form: ('somefield' = "somevalue" OR ('anotherfield' = "anothervalue" AND 'yetanotherfield' = "yetanothervalue")).

returnFilterFields - ArrayList of optional fields to return (filter fields). May be NULL.

sortOrder - indicate the sort order to return the data. May be NULL. If no value is supplied then the returned values are sorted by score. This is a string of the form: field;sortorder;field;sortorder;etc.

resultOption - indicates what data is to be returned. Options include sending no excerpt, sending an excerpt (first 30 words of the text), sending Words Around Hits, sending result count only, and returning schemaId, entryId, and score only for use in a 2 phase query.

returnEntries - what specific entries should be returned (used for phase 2 of query). May be NULL. This is a string of the form: schemaId##entryId@@score;schemaId##entryId@@score.

maxReturn - maximum number of results to return. 0 = unlimited. If the value is smaller than the configuration threshold value then threshold number is returned.

Returns:

An FTSResultSet object that contains the results.

Throws:

FTSServiceException

getEntryIdsByGlobalQuery

FTSService.FTSResultSet getEntryIdsByGlobalQuery(String shouldQueryValue,
                                               String mustQueryValue,
                                               String notQueryValue,
                                               List<FTSService.QuerySchemas> querySchemas,
                                               String filterQuery,
                                               List<FTSService.ReturnFilterFields> returnFilterFields,
                                               String sortOrder,
                                               int resultOption,
                                               Map<String,String> returnEntries,
                                               int maxReturn)
                                                 throws FTSServiceException

TODO: Remove when plugin moves to newer overload

Throws:

FTSServiceException

removeFieldFromDocumentsByQuery

void removeFieldFromDocumentsByQuery(String schemaId,
                                   String fieldName,
                                   String[] queryFieldNames,
                                   String[] queryFieldValues)
                                     throws FTSServiceException

Removes a field from the documents resulting from a query. A query is performed against multiple fields using the names and values in queryFieldNames and queryFieldValues. The field given by fieldName is removed from the documents resulting from the query. This overload will always commit the action at the time it is requested. The following illustrates how queryFieldNames and queryFieldValues are used to construct the query:

(queryFieldName1:queryFieldValue1) (queryFieldName2:queryFieldValue2)...(queryFieldNameX:queryFieldValueX)

Parameters:

schemaId - the id of the schema that containing the field

fieldName - Name of the field to remove.

queryFieldNames - Array of field names to query.

queryFieldValues - Array of field values to query.

Throws:

FTSServiceException

removeFieldFromDocumentsByQuery

void removeFieldFromDocumentsByQuery(String schemaId,
                                   String fieldName,
                                   String[] queryFieldNames,
                                   String[] queryFieldValues,
                                   int doCommit)
                                     throws FTSServiceException

Removes a field from the documents resulting from a query. A query is performed against multiple fields using the names and values in queryFieldNames and queryFieldValues. The field given by fieldName is removed from the documents resulting from the query. This overload requires stating if a commit should happen or not upon the requested action. The following illustrates how queryFieldNames and queryFieldValues are used to construct the query:

(queryFieldName1:queryFieldValue1) (queryFieldName2:queryFieldValue2)...(queryFieldNameX:queryFieldValueX)

Parameters:

schemaId - the id of the schema that containing the field

fieldName - Name of the field to remove.

queryFieldNames - Array of field names to query.

queryFieldValues - Array of field values to query.

doCommit - indicates if a commit should happen following this action.

Throws:

FTSServiceException

deleteDocumentsContainingField

void deleteDocumentsContainingField(String schemaId,
                                  String fieldName,
                                  String fieldValue)
                                    throws FTSServiceException

Deletes all documents which contain a specific field and field value. Those documents containing the field, fieldName, and the value for that field, fieldValue, are deleted.

Parameters:

fieldName - Name of the field.

fieldValue - Value of the field.

Throws:

FTSServiceException

deleteEntryDocument

void deleteEntryDocument(String schemaId,
                       String entryId)
                         throws FTSServiceException

Deletes document with the docid = schemaId##entryId.

Parameters:

schemaId - id of the schema.

entryId - id of the entry.

Throws:

FTSServiceException

deleteDocuments

void deleteDocuments(String schemaId,
                   boolean deleteIndexDir)
                     throws FTSServiceException

close the index searcher, reader and writer, and delete the index directory of the schema

Parameters:

schemaId - the id of the schema whose index will be deleted.

deleteIndexDir - if the index directory is deleted as well.

Throws:

FTSServiceException

updateConfiguration

void updateConfiguration()
                         throws FTSServiceException

Causes FTSAnalyzer to pick up any configuration changes and process with those changes from this point forward.

Throws:

FTSServiceException

close

void close()
           throws FTSServiceException

Safely closes any opened class resources. This method should be called before any instance of this class is garbage collected.

Throws:

FTSServiceException

commit

void commit()
            throws FTSServiceException

Commits the indexed data to disk. This method is required to improve the performance in case of bulk indexing. Application is required to call this interface when bulk indexing operation is complete.

Throws:

FTSServiceException

getIndexIterator

com.bmc.arsys.fts.impl.lucene.IndexDocIterator getIndexIterator(String schemaId)
                                                                throws FTSServiceException

return an index iterator for the given schema. The iterator allows users to iterate through all indexes created for the schema.

Parameters:

schemaId - the id of the schema whose indexes we want to iterate through

Returns:

the IndexDocumentIterator of the given schema

Throws:

FTSServiceException

reInitializeSearchEngines

void reInitializeSearchEngines(String ftsPluginName)

Reinitialize the search service references.

Parameters:

ftsPluginName - FTS plugin name