IFullTextSearchProvider

interface OCP\FullTextSearch\IFullTextSearchProvider
Interface IFullTextSearchProvider
This interface must be use when creating a Content Provider for FullTextSearch.

A Content Provider is an extension to the FullTextSearch that will extract and
provide content to the FullTextSearch.

There is no limit to the number of Content Provider that can be integrated to
FullTextSearch. Each Content Provider corresponding to a type of content
available in Nextcloud (files, bookmarks, notes, deck cards, mails, ...)

Content is split in document identified by an ID and the ID of the Content
Provider. The content is indexed by a Search Platform that will returns a
documentId as a result on a search request.


To oversimplify the mechanism:

- When indexing, FullTextSearch will ask for documents to every Content Provider.
- On search, results from the Search Platform, identified by documentId, will
be improved by each relative Content Provider.


The Content Provider is a PHP class that implement this interface and is defined
in appinfo/info.xml of the app that contains that class:

<fulltextsearch>
<provider>OCA\YourApp\YourContentProvider</provider>
</fulltextsearch>

Multiple Content Provider can be defined in a single app.
Source:lib/public/FullTextSearch/IFullTextSearchProvider.php#74

Methods

public OCP\FullTextSearch\IFullTextSearchProvider::getId()
Must returns a unique Id used to identify the Content Provider.
Id must contains only alphanumeric chars, with no space.
Source:lib/public/FullTextSearch/IFullTextSearchProvider.php#85
Since:15.0.0
Returns:string
public OCP\FullTextSearch\IFullTextSearchProvider::getName()
Must returns a descriptive name of the Content Provider.
This is used in multiple places, so better use a clear display name.
Source:lib/public/FullTextSearch/IFullTextSearchProvider.php#96
Since:15.0.0
Returns:string
public OCP\FullTextSearch\IFullTextSearchProvider::getConfiguration()
Should returns the current configuration of the Content Provider.
This is used to display the configuration when using the
./occ fulltextsearch:check command line.
Source:lib/public/FullTextSearch/IFullTextSearchProvider.php#108
Since:15.0.0
Returns:array
public OCP\FullTextSearch\IFullTextSearchProvider::getSearchTemplate()
Must returns a ISearchTemplate that contains displayable items and
available options to users when searching.
Source:lib/public/FullTextSearch/IFullTextSearchProvider.php#121
See:\OCP\FullTextSearch\Model\ISearchTemplate
Since:15.0.0
Returns:\OCP\FullTextSearch\Model\ISearchTemplate
public OCP\FullTextSearch\IFullTextSearchProvider::loadProvider()
Called when FullTextSearch is loading your Content Provider.
Source:lib/public/FullTextSearch/IFullTextSearchProvider.php#129
Since:15.0.0
public OCP\FullTextSearch\IFullTextSearchProvider::setRunner($runner)
Set the wrapper of the currently executed process.
Because the index process can be long and heavy, and because errors can
be encountered during the process, the IRunner is a wrapper that allow the
Content Provider to communicate with the process initiated by
FullTextSearch.

The IRunner is coming with some methods so the Content Provider can
returns important information and errors to be displayed to the admin.
Source:

lib/public/FullTextSearch/IFullTextSearchProvider.php#146
Parameters:
Since:

15.0.0
public OCP\FullTextSearch\IFullTextSearchProvider::setIndexOptions($options)
This method is called when the administrator specify options when running
the ./occ fulltextsearch:index or ./occ fulltextsearch:live
Source:

lib/public/FullTextSearch/IFullTextSearchProvider.php#157
Parameters:
Since:

15.0.0
public OCP\FullTextSearch\IFullTextSearchProvider::generateChunks($userId)
Allow the provider to generate a list of chunk to split a huge list of
indexable documents
During the indexing the generateIndexableDocuments method will be called
for each entry of the returned array.
If the returned array is empty, the generateIndexableDocuments() will be
called only once (per user).
Source:

lib/public/FullTextSearch/IFullTextSearchProvider.php#175
Parameters:
  • $userId (string)
Since:

16.0.0
Returns:

string[]
public OCP\FullTextSearch\IFullTextSearchProvider::generateIndexableDocuments($userId, $chunk)
Returns all indexable document for a user as an array of IIndexDocument.
There is no need to fill each IIndexDocument with content; at this point,
only fill the object with the minimum information to not waste memory while
still being able to identify the document it is referring to.

FullTextSearch will call 2 other methods of this interface for each
IIndexDocument of the array, prior to their indexing:

- first, to compare the date of the last index,
- then, to fill each IIndexDocument with complete data
Source:

lib/public/FullTextSearch/IFullTextSearchProvider.php#201
Parameters:
  • $userId (string)
  • $chunk (string)
See:

\OCP\FullTextSearch\Model\IIndexDocument
Since:

15.0.0 -> 16.0.0: the parameter “$chunk” was added
Returns:

\OCP\FullTextSearch\Model\IIndexDocument[]
public OCP\FullTextSearch\IFullTextSearchProvider::isDocumentUpToDate($document)
Called to verify that the document is not already indexed and that the
old index is not up-to-date, using the IIndex from
IIndexDocument->getIndex()
Returning true will not queue the current IIndexDocument to any further
operation and will continue on the next element from the list returned by
generateIndexableDocuments().
Source:

lib/public/FullTextSearch/IFullTextSearchProvider.php#219
Parameters:
Since:

15.0.0
Returns:

bool
public OCP\FullTextSearch\IFullTextSearchProvider::fillIndexDocument($document)
Must fill IIndexDocument with all information relative to the document,
before its indexing by the Search Platform.
Method is called for each element returned previously by
generateIndexableDocuments().
Source:

lib/public/FullTextSearch/IFullTextSearchProvider.php#235
Parameters:
See:

\OCP\FullTextSearch\Model\IIndexDocument
Since:

15.0.0
public OCP\FullTextSearch\IFullTextSearchProvider::updateDocument($index)
The Search Provider must create and return an IIndexDocument
based on the IIndex and its status. The IIndexDocument must contains all
information as it will be send for indexing.
Method is called during a cron or a ./occ fulltextsearch:live after a
new document is created, or an old document is set as modified.
Source:

lib/public/FullTextSearch/IFullTextSearchProvider.php#252
Parameters:
Since:

15.0.0
Returns:

\OCP\FullTextSearch\Model\IIndexDocument
public OCP\FullTextSearch\IFullTextSearchProvider::onInitializingIndex($platform)
Called when an index is initiated by the administrator.
This is should only be used in case of a specific mapping is needed.
(ie. _almost_ never)
Source:

lib/public/FullTextSearch/IFullTextSearchProvider.php#264
Parameters:
Since:

15.0.0
public OCP\FullTextSearch\IFullTextSearchProvider::onResettingIndex($platform)
Called when administrator is resetting the index.
This is should only be used in case of a specific mapping has been
created.
Source:

lib/public/FullTextSearch/IFullTextSearchProvider.php#276
Parameters:
Since:

15.0.0
public OCP\FullTextSearch\IFullTextSearchProvider::improveSearchRequest($searchRequest)
Method is called when a search request is initiated by a user, prior to
be sent to the Search Platform.
Your Content Provider can interact with the ISearchRequest to apply the
search options and make the search more precise.
Source:

lib/public/FullTextSearch/IFullTextSearchProvider.php#292
Parameters:
See:

\OCP\FullTextSearch\Model\ISearchRequest
Since:

15.0.0
public OCP\FullTextSearch\IFullTextSearchProvider::improveSearchResult($searchResult)
Method is called after results of a search are returned by the
Search Platform.
Your Content Provider can detail each entry with local data to improve
the display of the search result.
Source:

lib/public/FullTextSearch/IFullTextSearchProvider.php#308
Parameters:
See:

\OCP\FullTextSearch\Model\ISearchResult
Since:

15.0.0
public OCP\FullTextSearch\IFullTextSearchProvider::unloadProvider()
not used yet.
Source:lib/public/FullTextSearch/IFullTextSearchProvider.php#316
Since:15.0.0