nextcloud/lib/public/FullTextSearch/IFullTextSearchProvider.php

318 lines
8.5 KiB
PHP
Raw Normal View History

<?php
declare(strict_types=1);
/**
* @copyright 2018
*
* @author Maxence Lange <maxence@artificial-owl.com>
* @author Roeland Jago Douma <roeland@famdouma.nl>
*
* @license GNU AGPL version 3 or any later version
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*/
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();
}