diff options
Diffstat (limited to 'lib/public/FullTextSearch/IFullTextSearchProvider.php')
| -rw-r--r-- | lib/public/FullTextSearch/IFullTextSearchProvider.php | 295 |
1 files changed, 295 insertions, 0 deletions
diff --git a/lib/public/FullTextSearch/IFullTextSearchProvider.php b/lib/public/FullTextSearch/IFullTextSearchProvider.php new file mode 100644 index 00000000000..b1ee3b66274 --- /dev/null +++ b/lib/public/FullTextSearch/IFullTextSearchProvider.php @@ -0,0 +1,295 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch; + +use OCP\FullTextSearch\Model\IIndex; +use OCP\FullTextSearch\Model\IIndexDocument; +use OCP\FullTextSearch\Model\IIndexOptions; +use OCP\FullTextSearch\Model\IRunner; +use OCP\FullTextSearch\Model\ISearchRequest; +use OCP\FullTextSearch\Model\ISearchResult; +use OCP\FullTextSearch\Model\ISearchTemplate; + +/** + * 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. + * + * @since 15.0.0 + * + */ +interface IFullTextSearchProvider { + /** + * Must returns a unique Id used to identify the Content Provider. + * Id must contains only alphanumeric chars, with no space. + * + * @since 15.0.0 + * + * @return string + */ + public function getId(): string; + + + /** + * Must returns a descriptive name of the Content Provider. + * This is used in multiple places, so better use a clear display name. + * + * @since 15.0.0 + * + * @return string + */ + public function getName(): string; + + + /** + * Should returns the current configuration of the Content Provider. + * This is used to display the configuration when using the + * ./occ fulltextsearch:check command line. + * + * @since 15.0.0 + * + * @return array + */ + public function getConfiguration(): array; + + + /** + * Must returns a ISearchTemplate that contains displayable items and + * available options to users when searching. + * + * @see ISearchTemplate + * + * @since 15.0.0 + * + * @return ISearchTemplate + */ + public function getSearchTemplate(): ISearchTemplate; + + + /** + * Called when FullTextSearch is loading your Content Provider. + * + * @since 15.0.0 + */ + public function loadProvider(); + + + /** + * 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. + * + * @since 15.0.0 + * + * @param IRunner $runner + */ + public function setRunner(IRunner $runner); + + + /** + * This method is called when the administrator specify options when running + * the ./occ fulltextsearch:index or ./occ fulltextsearch:live + * + * @since 15.0.0 + * + * @param IIndexOptions $options + */ + public function setIndexOptions(IIndexOptions $options); + + + /** + * 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). + * + * @since 16.0.0 + * + * @param string $userId + * + * @return string[] + */ + public function generateChunks(string $userId): array; + + + /** + * 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 + * + * @see IIndexDocument + * + * @since 15.0.0 + * -> 16.0.0: the parameter "$chunk" was added + * + * @param string $userId + * @param string $chunk + * + * @return IIndexDocument[] + */ + public function generateIndexableDocuments(string $userId, string $chunk): array; + + + /** + * 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(). + * + * @since 15.0.0 + * + * @param IIndexDocument $document + * + * @return bool + */ + public function isDocumentUpToDate(IIndexDocument $document): bool; + + + /** + * 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(). + * + * @see IIndexDocument + * + * @since 15.0.0 + * + * @param IIndexDocument $document + */ + public function fillIndexDocument(IIndexDocument $document); + + + /** + * 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. + * + * @since 15.0.0 + * + * @param IIndex $index + * + * @return IIndexDocument + */ + public function updateDocument(IIndex $index): IIndexDocument; + + + /** + * 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) + * + * @since 15.0.0 + * + * @param IFullTextSearchPlatform $platform + */ + public function onInitializingIndex(IFullTextSearchPlatform $platform); + + + /** + * Called when administrator is resetting the index. + * This is should only be used in case of a specific mapping has been + * created. + * + * @since 15.0.0 + * + * @param IFullTextSearchPlatform $platform + */ + public function onResettingIndex(IFullTextSearchPlatform $platform); + + + /** + * 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. + * + * @see ISearchRequest + * + * @since 15.0.0 + * + * @param ISearchRequest $searchRequest + */ + public function improveSearchRequest(ISearchRequest $searchRequest); + + + /** + * 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. + * + * @see ISearchResult + * + * @since 15.0.0 + * + * @param ISearchResult $searchResult + */ + public function improveSearchResult(ISearchResult $searchResult); + + + /** + * not used yet. + * + * @since 15.0.0 + */ + public function unloadProvider(); +} |