diff options
Diffstat (limited to 'lib/public/FullTextSearch')
18 files changed, 3186 insertions, 0 deletions
diff --git a/lib/public/FullTextSearch/Exceptions/FullTextSearchAppNotAvailableException.php b/lib/public/FullTextSearch/Exceptions/FullTextSearchAppNotAvailableException.php new file mode 100644 index 00000000000..11c7fc62de9 --- /dev/null +++ b/lib/public/FullTextSearch/Exceptions/FullTextSearchAppNotAvailableException.php @@ -0,0 +1,18 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Exceptions; + +/** + * @since 15.0.0 + * + * Class FullTextSearchAppNotAvailableException + * + */ +class FullTextSearchAppNotAvailableException extends \Exception { +} diff --git a/lib/public/FullTextSearch/Exceptions/FullTextSearchIndexNotAvailableException.php b/lib/public/FullTextSearch/Exceptions/FullTextSearchIndexNotAvailableException.php new file mode 100644 index 00000000000..a2222fe57cb --- /dev/null +++ b/lib/public/FullTextSearch/Exceptions/FullTextSearchIndexNotAvailableException.php @@ -0,0 +1,18 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Exceptions; + +/** + * @since 28.0.0 + * + * Class FullTextSearchIndexNotAvailableException + * + */ +class FullTextSearchIndexNotAvailableException extends \Exception { +} diff --git a/lib/public/FullTextSearch/IFullTextSearchManager.php b/lib/public/FullTextSearch/IFullTextSearchManager.php new file mode 100644 index 00000000000..db7a50adabb --- /dev/null +++ b/lib/public/FullTextSearch/IFullTextSearchManager.php @@ -0,0 +1,166 @@ +<?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\ISearchResult; +use OCP\FullTextSearch\Service\IIndexService; +use OCP\FullTextSearch\Service\IProviderService; +use OCP\FullTextSearch\Service\ISearchService; + +/** + * Interface IFullTextSearchManager + * + * Should be used to manage FullTextSearch from the app that contains your + * Content Provider/Search Platform. + * + * @since 15.0.0 + * + */ +interface IFullTextSearchManager { + /** + * Register a IProviderService. + * + * @since 15.0.0 + * + * @param IProviderService $providerService + */ + public function registerProviderService(IProviderService $providerService); + + /** + * Register a IIndexService. + * + * @since 15.0.0 + * + * @param IIndexService $indexService + */ + public function registerIndexService(IIndexService $indexService); + + /** + * Register a ISearchService. + * + * @since 15.0.0 + * + * @param ISearchService $searchService + */ + public function registerSearchService(ISearchService $searchService); + + /** + * returns true is Full Text Search is available (app is present and Service + * are registered) + * + * @since 16.0.0 + * + * @return bool + */ + public function isAvailable(): bool; + + + /** + * Add the Javascript API in the navigation page of an app. + * Needed to replace the default search. + * + * @since 15.0.0 + */ + public function addJavascriptAPI(); + + + /** + * Check if the provider $providerId is already indexed. + * + * @since 15.0.0 + * + * @param string $providerId + * + * @return bool + */ + public function isProviderIndexed(string $providerId): bool; + + + /** + * Retrieve an Index from the database, based on the Id of the Provider + * and the Id of the Document + * + * @since 15.0.0 + * + * @param string $providerId + * @param string $documentId + * + * @return IIndex + */ + public function getIndex(string $providerId, string $documentId): IIndex; + + + /** + * Create a new Index. + * + * This method must be called when a new document is created. + * + * @since 15.0.0 + * + * @param string $providerId + * @param string $documentId + * @param string $userId + * @param int $status + * + * @return IIndex + */ + public function createIndex(string $providerId, string $documentId, string $userId, int $status = 0): IIndex; + + + /** + * Update the status of an Index. status is a bitflag, setting $reset to + * true will reset the status to the value defined in the parameter. + * + * @since 15.0.0 + * + * @param string $providerId + * @param string $documentId + * @param int $status + * @param bool $reset + */ + public function updateIndexStatus(string $providerId, string $documentId, int $status, bool $reset = false); + + + /** + * Update the status of an array of Index. status is a bit flag, setting $reset to + * true will reset the status to the value defined in the parameter. + * + * @since 15.0.0 + * + * @param string $providerId + * @param array $documentIds + * @param int $status + * @param bool $reset + */ + public function updateIndexesStatus(string $providerId, array $documentIds, int $status, bool $reset = false); + + /** + * Update an array of Index. + * + * @since 15.0.0 + * + * @param IIndex[] $indexes + */ + public function updateIndexes(array $indexes); + + /** + * Search using an array as request. If $userId is empty, will use the + * current session. + * + * @see ISearchService::generateSearchRequest + * + * @since 15.0.0 + * + * @param array $request + * @param string $userId + * @return ISearchResult[] + */ + public function search(array $request, string $userId = ''): array; +} diff --git a/lib/public/FullTextSearch/IFullTextSearchPlatform.php b/lib/public/FullTextSearch/IFullTextSearchPlatform.php new file mode 100644 index 00000000000..62b3070d5f2 --- /dev/null +++ b/lib/public/FullTextSearch/IFullTextSearchPlatform.php @@ -0,0 +1,196 @@ +<?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\IDocumentAccess; +use OCP\FullTextSearch\Model\IIndex; +use OCP\FullTextSearch\Model\IIndexDocument; +use OCP\FullTextSearch\Model\IRunner; +use OCP\FullTextSearch\Model\ISearchResult; + +/** + * Interface IFullTextSearchPlatform + * + * This interface must be use when creating a Search Platform for FullTextSearch. + * + * A Search Platform is an extension to the FullTextSearch that will act as a + * a gateway between FullTextSearch and a search server (ie. ElasticSearch, + * Solr, ...) + * + * Multiple Search Platform can exist at the same time in Nextcloud, however only + * one Search Platform will be used by FullTextSearch. + * Administrator must select at least one Search Platform to be used by + * FullTextSearch in the admin settings page. + * + * The content provided by FullTextSearch comes in chunk from multiple Content + * Provider. Each chunk is identified by the ID of the Content Provider, and the + * ID of the document. + * + * + * To oversimplify the mechanism: + * + * - When indexing, FullTextSearch will send providerId, documentId, content. + * - When searching within the content of a Content Provider, identified by its + * providerId, FullTextSearch expect documentId as result. + * + * + * The Search Platform ia a PHP class that implement this interface and is defined + * in appinfo/info.xml of the app that contains that class: + * + * <fulltextsearch> + * <platform>OCA\YourApp\YourSearchPlatform</platform> + * </fulltextsearch> + * + * Multiple Search Platform can be defined in a single app. + * + * @since 15.0.0 + * + */ +interface IFullTextSearchPlatform { + /** + * Must returns a unique Id used to identify the Search Platform. + * 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 Search Platform. + * This is used mainly in the admin settings page to display the list of + * available Search Platform + * + * @since 15.0.0 + * + * @return string + */ + public function getName(): string; + + + /** + * should returns the current configuration of the Search Platform. + * 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; + + + /** + * 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 + * Search Platform to communicate with the process initiated by + * FullTextSearch. + * + * The IRunner is coming with some methods so the Search Platform can + * returns important information and errors to be displayed to the admin. + * + * @since 15.0.0 + * + * @param IRunner $runner + */ + public function setRunner(IRunner $runner); + + + /** + * Called when FullTextSearch is loading your Search Platform. + * + * @since 15.0.0 + */ + public function loadPlatform(); + + + /** + * Called to check that your Search Platform is correctly configured and that + * This is also the right place to check that the Search Service is available. + * + * @since 15.0.0 + * + * @return bool + */ + public function testPlatform(): bool; + + + /** + * Called before an index is initiated. + * Best place to initiate some stuff on the Search Server (mapping, ...) + * + * @since 15.0.0 + */ + public function initializeIndex(); + + + /** + * Reset the indexes for a specific providerId. + * $providerId can be 'all' if it is a global reset. + * + * @since 15.0.0 + * + * @param string $providerId + */ + public function resetIndex(string $providerId); + + + /** + * Deleting some IIndex, sent in an array + * + * @see IIndex + * + * @since 15.0.0 + * + * @param IIndex[] $indexes + */ + public function deleteIndexes(array $indexes); + + + /** + * Indexing a document. + * + * @see IndexDocument + * + * @since 15.0.0 + * + * @param IIndexDocument $document + * + * @return IIndex + */ + public function indexDocument(IIndexDocument $document): IIndex; + + + /** + * Searching documents, ISearchResult should be updated with the result of + * the search. + * + * @since 15.0.0 + * + * @param ISearchResult $result + * @param IDocumentAccess $access + */ + public function searchRequest(ISearchResult $result, IDocumentAccess $access); + + + /** + * Return a document based on its Id and the Provider. + * This is used when an admin execute ./occ fulltextsearch:document:platform + * + * @since 15.0.0 + * + * @param string $providerId + * @param string $documentId + * + * @return IIndexDocument + */ + public function getDocument(string $providerId, string $documentId): IIndexDocument; +} 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(); +} diff --git a/lib/public/FullTextSearch/Model/IDocumentAccess.php b/lib/public/FullTextSearch/Model/IDocumentAccess.php new file mode 100644 index 00000000000..407f0f2bb28 --- /dev/null +++ b/lib/public/FullTextSearch/Model/IDocumentAccess.php @@ -0,0 +1,235 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Model; + +/** + * Interface IDocumentAccess + * + * This object is used as a data transfer object when + * + * - indexing a document, + * - generating a search request. + * + * During the index, it is used to define which users, groups, circles, ... + * have access to the IIndexDocument + * + * During the search, it is internally use to define to which group, circles, ... + * a user that perform the search belongs to. + * + * @see IIndexDocument::setAccess + * + * @since 16.0.0 + * + */ +interface IDocumentAccess { + /** + * Owner of the document can be set at the init of the object. + * + * @since 16.0.0 + * + * IDocumentAccess constructor. + * + * @param string $ownerId + */ + public function __construct(string $ownerId = ''); + + + /** + * Set the Owner of the document. + * + * @since 16.0.0 + * + * @param string $ownerId + * + * @return IDocumentAccess + */ + public function setOwnerId(string $ownerId): IDocumentAccess; + + /** + * Get the Owner of the document. + * + * @since 16.0.0 + * + * @return string + */ + public function getOwnerId(): string; + + + /** + * Set the viewer of the document. + * + * @since 16.0.0 + * + * @param string $viewerId + * + * @return IDocumentAccess + */ + public function setViewerId(string $viewerId): IDocumentAccess; + + /** + * Get the viewer of the document. + * + * @since 16.0.0 + * + * @return string + */ + public function getViewerId(): string; + + + /** + * Set the list of users that have read access to the document. + * + * @since 16.0.0 + * + * @param array $users + * + * @return IDocumentAccess + */ + public function setUsers(array $users): IDocumentAccess; + + /** + * Add an entry to the list of users that have read access to the document. + * + * @since 16.0.0 + * + * @param string $user + * + * @return IDocumentAccess + */ + public function addUser(string $user): IDocumentAccess; + + /** + * Add multiple entries to the list of users that have read access to the + * document. + * + * @since 16.0.0 + * + * @param array $users + * + * @return IDocumentAccess + */ + public function addUsers($users): IDocumentAccess; + + /** + * Get the complete list of users that have read access to the document. + * + * @since 16.0.0 + * + * @return array + */ + public function getUsers(): array; + + + /** + * Set the list of groups that have read access to the document. + * + * @since 16.0.0 + * + * @param array $groups + * + * @return IDocumentAccess + */ + public function setGroups(array $groups): IDocumentAccess; + + /** + * Add an entry to the list of groups that have read access to the document. + * + * @since 16.0.0 + * + * @param string $group + * + * @return IDocumentAccess + */ + public function addGroup(string $group): IDocumentAccess; + + /** + * Add multiple entries to the list of groups that have read access to the + * document. + * + * @since 16.0.0 + * + * @param array $groups + * + * @return IDocumentAccess + */ + public function addGroups(array $groups); + + /** + * Get the complete list of groups that have read access to the document. + * + * @since 16.0.0 + * + * @return array + */ + public function getGroups(): array; + + + /** + * Set the list of circles that have read access to the document. + * + * @since 16.0.0 + * + * @param array $circles + * + * @return IDocumentAccess + */ + public function setCircles(array $circles): IDocumentAccess; + + /** + * Add an entry to the list of circles that have read access to the document. + * + * @since 16.0.0 + * + * @param string $circle + * + * @return IDocumentAccess + */ + public function addCircle(string $circle): IDocumentAccess; + + /** + * Add multiple entries to the list of groups that have read access to the + * document. + * + * @since 16.0.0 + * + * @param array $circles + * + * @return IDocumentAccess + */ + public function addCircles(array $circles): IDocumentAccess; + + /** + * Get the complete list of circles that have read access to the document. + * + * @since 16.0.0 + * + * @return array + */ + public function getCircles(): array; + + + /** + * Set the list of links that have read access to the document. + * + * @since 16.0.0 + * + * @param array $links + * + * @return IDocumentAccess + */ + public function setLinks(array $links): IDocumentAccess; + + /** + * Get the list of links that have read access to the document. + * + * @since 16.0.0 + * + * @return array + */ + public function getLinks(): array; +} diff --git a/lib/public/FullTextSearch/Model/IIndex.php b/lib/public/FullTextSearch/Model/IIndex.php new file mode 100644 index 00000000000..13aee916498 --- /dev/null +++ b/lib/public/FullTextSearch/Model/IIndex.php @@ -0,0 +1,333 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Model; + +/** + * Interface IIndex + * + * Index are generated by FullTextSearch to manage the status of a document + * regarding the date of the last index and the date of the last modification + * of the original document. + * + * The uniqueness of an IIndexDocument is made by the Id of the Content Provider + * and the Id of the original document within the Content Provider. + * + * We will call original document the source from which the IIndexDocument is + * generated. As an example, an original document can be a file, a mail, ... + * + * @since 15.0.0 + * + */ +interface IIndex { + /** + * @since 15.0.0 + */ + public const INDEX_OK = 1; + + /** + * @since 15.0.0 + */ + public const INDEX_IGNORE = 2; + + /** + * @since 15.0.0 + */ + public const INDEX_META = 4; + + /** + * @since 15.0.0 + */ + public const INDEX_CONTENT = 8; + + /** + * @since 16.0.0 + */ + public const INDEX_PARTS = 16; + + /** + * @since 15.0.0 + */ + public const INDEX_FULL = 28; + + /** + * @since 15.0.0 + */ + public const INDEX_REMOVE = 32; + + /** + * @since 15.0.0 + */ + public const INDEX_DONE = 64; + + /** + * @since 15.0.0 + */ + public const INDEX_FAILED = 128; + + /** + * @since 15.0.0 + */ + public const ERROR_FAILED = 1; + + /** + * @since 15.0.0 + */ + public const ERROR_FAILED2 = 2; + + /** + * @since 15.0.0 + */ + public const ERROR_FAILED3 = 4; + + /** + * @since 15.0.0 + */ + public const ERROR_SEV_1 = 1; + + /** + * @since 15.0.0 + */ + public const ERROR_SEV_2 = 2; + + /** + * @since 15.0.0 + */ + public const ERROR_SEV_3 = 3; + + /** + * @since 15.0.0 + */ + public const ERROR_SEV_4 = 4; + + + /** + * Get the Id of the Content Provider. + * + * @since 15.0.0 + * + * @return string + */ + public function getProviderId(): string; + + + /** + * Get the Id of the original document. + * + * @since 15.0.0 + * + * @return string + */ + public function getDocumentId(): string; + + + /** + * Get the collection of the index. + * If empty (''), means collection is the default one used by the internal framework + * + * @since 24.0.0 + * + * @return string + */ + public function getCollection(): string; + + + /** + * Set the source of the original document. + * + * @since 15.0.0 + * + * @param string $source + * + * @return IIndex + */ + public function setSource(string $source): IIndex; + + /** + * Get the source of the original document. + * + * @since 15.0.0 + * + * @return string + */ + public function getSource(): string; + + + /** + * Set the owner of the original document. + * + * @since 15.0.0 + * + * @param string $ownerId + * + * @return IIndex + */ + public function setOwnerId(string $ownerId): IIndex; + + /** + * Get the owner of the original document. + * + * @since 15.0.0 + * + * @return string + */ + public function getOwnerId(): string; + + + /** + * Set the current index status (bit flag) of the original document. + * If $reset is true, the status is reset to the defined value. + * + * @since 15.0.0 + * + * @param int $status + * @param bool $reset + * + * @return IIndex + */ + public function setStatus(int $status, bool $reset = false): IIndex; + + /** + * Get the current index status of the original document. + * + * @since 15.0.0 + * + * @return int + */ + public function getStatus(): int; + + /** + * Check if the document fit a specific status. + * + * @since 15.0.0 + * + * @param int $status + * + * @return bool + */ + public function isStatus(int $status): bool; + + /** + * Remove a status. + * + * @since 15.0.0 + * + * @param int $status + * + * @return IIndex + */ + public function unsetStatus(int $status): IIndex; + + + /** + * Add an option related to the original document (as string). + * + * @since 15.0.0 + * + * @param string $option + * @param string $value + * + * @return IIndex + */ + public function addOption(string $option, string $value): IIndex; + + /** + * Add an option related to the original document (as integer). + * + * @since 15.0.0 + * + * @param string $option + * @param int $value + * + * @return IIndex + */ + public function addOptionInt(string $option, int $value): IIndex; + + /** + * Get the option related to the original document (as string). + * + * @since 15.0.0 + * + * @param string $option + * @param string $default + * + * @return string + */ + public function getOption(string $option, string $default = ''): string; + + /** + * Get the option related to the original document (as integer). + * + * @since 15.0.0 + * + * @param string $option + * @param int $default + * + * @return int + */ + public function getOptionInt(string $option, int $default = 0): int; + + /** + * Get all options related to the original document. + * + * @since 15.0.0 + * + * @return array + */ + public function getOptions(): array; + + + /** + * Add an error log related to the Index. + * + * @since 15.0.0 + * + * @param string $message + * @param string $exception + * @param int $sev + * + * @return IIndex + */ + public function addError(string $message, string $exception = '', int $sev = self::ERROR_SEV_3): IIndex; + + /** + * Returns the number of known errors related to the Index. + * + * @since 15.0.0 + * + * @return int + */ + public function getErrorCount(): int; + + /** + * Reset all error logs related to the Index. + * + * @since 15.0.0 + */ + public function resetErrors(): IIndex; + + + /** + * Set the date of the last index. + * + * @since 15.0.0 + * + * @param int $lastIndex + * + * @return IIndex + */ + public function setLastIndex(int $lastIndex = -1): IIndex; + + /** + * Get the date of the last index. + * + * @since 15.0.0 + * + * @return int + */ + public function getLastIndex(): int; +} diff --git a/lib/public/FullTextSearch/Model/IIndexDocument.php b/lib/public/FullTextSearch/Model/IIndexDocument.php new file mode 100644 index 00000000000..ae93272d246 --- /dev/null +++ b/lib/public/FullTextSearch/Model/IIndexDocument.php @@ -0,0 +1,613 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Model; + +/** + * Class IIndexDocument + * + * This is one of the main class of the FullTextSearch, used as a data transfer + * object. An IIndexDocument is created to manage documents around FullTextSearch, + * during an index and during a search. + * The uniqueness of an IIndexDocument is made by the Id of the Content Provider + * and the Id of the original document within the Content Provider. + * + * We will call original document the source from which the IIndexDocument is + * generated. As an example, an original document can be a file, a mail, ... + * + * @since 15.0.0 + */ +interface IIndexDocument { + /** + * @since 15.0.0 + */ + public const NOT_ENCODED = 0; + + /** + * @since 15.0.0 + */ + public const ENCODED_BASE64 = 1; + + + + /** + * Returns the Id of the original document. + * + * @since 15.0.0 + * + * @return string + */ + public function getId(): string; + + + /** + * Returns the Id of the provider. + * + * @since 15.0.0 + * + * @return string + */ + public function getProviderId(): string; + + + /** + * Set the Index related to the IIndexDocument. + * + * @see IIndex + * + * @since 15.0.0 + * + * @param IIndex $index + * + * @return IIndexDocument + */ + public function setIndex(IIndex $index): IIndexDocument; + + /** + * Get the Index. + * + * @since 15.0.0 + * + * @return IIndex + */ + public function getIndex(): IIndex; + + /** + * return if Index is defined. + * + * @since 16.0.0 + * + * @return bool + */ + public function hasIndex(): bool; + + + /** + * Set the modified time of the original document. + * + * @since 15.0.0 + * + * @param int $modifiedTime + * + * @return IIndexDocument + */ + public function setModifiedTime(int $modifiedTime): IIndexDocument; + + /** + * Get the modified time of the original document. + * + * @since 15.0.0 + * + * @return int + */ + public function getModifiedTime(): int; + + /** + * Check if the original document of the IIndexDocument is older than $time. + * + * @since 15.0.0 + * + * @param int $time + * + * @return bool + */ + public function isOlderThan(int $time): bool; + + + /** + * Set the read rights of the original document using a IDocumentAccess. + * + * @see IDocumentAccess + * + * @since 15.0.0 + * + * @param IDocumentAccess $access + * + * @return $this + */ + public function setAccess(IDocumentAccess $access): IIndexDocument; + + /** + * Get the IDocumentAccess related to the original document. + * + * @since 15.0.0 + * + * @return IDocumentAccess + */ + public function getAccess(): IDocumentAccess; + + + /** + * Add a tag to the list. + * + * @since 15.0.0 + * + * @param string $tag + * + * @return IIndexDocument + */ + public function addTag(string $tag): IIndexDocument; + + /** + * Set the list of tags assigned to the original document. + * + * @since 15.0.0 + * + * @param array $tags + * + * @return IIndexDocument + */ + public function setTags(array $tags): IIndexDocument; + + /** + * Get the list of tags assigned to the original document. + * + * @since 15.0.0 + * + * @return array + */ + public function getTags(): array; + + + /** + * Add a meta tag to the list. + * + * @since 15.0.0 + * + * @param string $tag + * + * @return IIndexDocument + */ + public function addMetaTag(string $tag): IIndexDocument; + + /** + * Set the list of meta tags assigned to the original document. + * + * @since 15.0.0 + * + * @param array $tags + * + * @return IIndexDocument + */ + public function setMetaTags(array $tags): IIndexDocument; + + /** + * Get the list of meta tags assigned to the original document. + * + * @since 15.0.0 + * + * @return array + */ + public function getMetaTags(): array; + + + /** + * Add a sub tag to the list. + * + * @since 15.0.0 + * + * @param string $sub + * @param string $tag + * + * @return IIndexDocument + */ + public function addSubTag(string $sub, string $tag): IIndexDocument; + + /** + * Set the list of sub tags assigned to the original document. + * + * @since 15.0.0 + * + * @param array $tags + * + * @return IIndexDocument + */ + public function setSubTags(array $tags): IIndexDocument; + + /** + * Get the list of sub tags assigned to the original document. + * If $formatted is true, the result will be formatted in a one + * dimensional array. + * + * @since 15.0.0 + * + * @param bool $formatted + * + * @return array + */ + public function getSubTags(bool $formatted = false): array; + + + /** + * Set the source of the original document. + * + * @since 15.0.0 + * + * @param string $source + * + * @return IIndexDocument + */ + public function setSource(string $source): IIndexDocument; + + /** + * Get the source of the original document. + * + * @since 15.0.0 + * + * @return string + */ + public function getSource(): string; + + + /** + * Set the title of the original document. + * + * @since 15.0.0 + * + * @param string $title + * + * @return IIndexDocument + */ + public function setTitle(string $title): IIndexDocument; + + /** + * Get the title of the original document. + * + * @since 15.0.0 + * + * @return string + */ + public function getTitle(): string; + + + /** + * Set the content of the document. + * $encoded can be NOT_ENCODED or ENCODED_BASE64 if the content is raw or + * encoded in base64. + * + * @since 15.0.0 + * + * @param string $content + * @param int $encoded + * + * @return IIndexDocument + */ + public function setContent(string $content, int $encoded = 0): IIndexDocument; + + /** + * Get the content of the original document. + * + * @since 15.0.0 + * + * @return string + */ + public function getContent(): string; + + /** + * Returns the type of the encoding on the content. + * + * @since 15.0.0 + * + * @return int + */ + public function isContentEncoded(): int; + + /** + * Return the size of the content. + * + * @since 15.0.0 + * + * @return int + */ + public function getContentSize(): int; + + + /** + * Generate an hash, based on the content of the original document. + * + * @since 15.0.0 + * + * @return IIndexDocument + */ + public function initHash(): IIndexDocument; + + /** + * Set the hash of the original document. + * + * @since 15.0.0 + * + * @param string $hash + * + * @return IIndexDocument + */ + public function setHash(string $hash): IIndexDocument; + + /** + * Get the hash of the original document. + * + * @since 15.0.0 + * + * @return string + */ + public function getHash(): string; + + + /** + * Add a part, identified by a string, and its content. + * + * It is strongly advised to use alphanumerical chars with no space in the + * $part string. + * + * @since 15.0.0 + * + * @param string $part + * @param string $content + * + * @return IIndexDocument + */ + public function addPart(string $part, string $content): IIndexDocument; + + /** + * Set all parts and their content. + * + * @since 15.0.0 + * + * @param array $parts + * + * @return IIndexDocument + */ + public function setParts(array $parts): IIndexDocument; + + /** + * Get all parts of the IIndexDocument. + * + * @since 15.0.0 + * + * @return array + */ + public function getParts(): array; + + + /** + * Add a link, usable by the frontend. + * + * @since 15.0.0 + * + * @param string $link + * + * @return IIndexDocument + */ + public function setLink(string $link): IIndexDocument; + + /** + * Get the link. + * + * @since 15.0.0 + * + * @return string + */ + public function getLink(): string; + + + /** + * Set more information that couldn't be set using other method. + * + * @since 15.0.0 + * + * @param array $more + * + * @return IIndexDocument + */ + public function setMore(array $more): IIndexDocument; + + /** + * Get more information. + * + * @since 15.0.0 + * + * @return array + */ + public function getMore(): array; + + + /** + * Add some excerpt of the content of the original document, usually based + * on the search request. + * + * @since 16.0.0 + * + * @param string $source + * @param string $excerpt + * + * @return IIndexDocument + */ + public function addExcerpt(string $source, string $excerpt): IIndexDocument; + + /** + * Set all excerpts of the content of the original document. + * + * @since 16.0.0 + * + * @param array $excerpts + * + * @return IIndexDocument + */ + public function setExcerpts(array $excerpts): IIndexDocument; + + /** + * Get all excerpts of the content of the original document. + * + * @since 15.0.0 + * + * @return array + */ + public function getExcerpts(): array; + + + /** + * Set the score to the result assigned to this document during a search + * request. + * + * @since 15.0.0 + * + * @param string $score + * + * @return IIndexDocument + */ + public function setScore(string $score): IIndexDocument; + + /** + * Get the score. + * + * @since 15.0.0 + * + * @return string + */ + public function getScore(): string; + + + /** + * Set some information about the original document that will be available + * to the front-end when displaying search result. (as string) + * Because this information will not be indexed, this method can also be + * used to manage some data while filling the IIndexDocument before its + * indexing. + * + * @since 15.0.0 + * + * @param string $info + * @param string $value + * + * @return IIndexDocument + */ + public function setInfo(string $info, string $value): IIndexDocument; + + /** + * Get an information about a document. (string) + * + * @since 15.0.0 + * + * @param string $info + * @param string $default + * + * @return string + */ + public function getInfo(string $info, string $default = ''): string; + + /** + * Set some information about the original document that will be available + * to the front-end when displaying search result. (as array) + * Because this information will not be indexed, this method can also be + * used to manage some data while filling the IIndexDocument before its + * indexing. + * + * @since 15.0.0 + * + * @param string $info + * @param array $value + * + * @return IIndexDocument + */ + public function setInfoArray(string $info, array $value): IIndexDocument; + + /** + * Get an information about a document. (array) + * + * @since 15.0.0 + * + * @param string $info + * @param array $default + * + * @return array + */ + public function getInfoArray(string $info, array $default = []): array; + + /** + * Set some information about the original document that will be available + * to the front-end when displaying search result. (as int) + * Because this information will not be indexed, this method can also be + * used to manage some data while filling the IIndexDocument before its + * indexing. + * + * @since 15.0.0 + * + * @param string $info + * @param int $value + * + * @return IIndexDocument + */ + public function setInfoInt(string $info, int $value): IIndexDocument; + + /** + * Get an information about a document. (int) + * + * @since 15.0.0 + * + * @param string $info + * @param int $default + * + * @return int + */ + public function getInfoInt(string $info, int $default = 0): int; + + /** + * Set some information about the original document that will be available + * to the front-end when displaying search result. (as bool) + * Because this information will not be indexed, this method can also be + * used to manage some data while filling the IIndexDocument before its + * indexing. + * + * @since 15.0.0 + * + * @param string $info + * @param bool $value + * + * @return IIndexDocument + */ + public function setInfoBool(string $info, bool $value): IIndexDocument; + + /** + * Get an information about a document. (bool) + * + * @since 15.0.0 + * + * @param string $info + * @param bool $default + * + * @return bool + */ + public function getInfoBool(string $info, bool $default = false): bool; + + /** + * Get all info. + * + * @since 15.0.0 + * + * @return array + */ + public function getInfoAll(): array; +} diff --git a/lib/public/FullTextSearch/Model/IIndexOptions.php b/lib/public/FullTextSearch/Model/IIndexOptions.php new file mode 100644 index 00000000000..951da3b9a76 --- /dev/null +++ b/lib/public/FullTextSearch/Model/IIndexOptions.php @@ -0,0 +1,57 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Model; + +/** + * Interface IIndexOptions + * + * IndexOptions are created in FullTextSearch when an admin initiate an index + * from the command line: + * + * ./occ fulltextsearch:index "{\"option1\": \"value\", \"option2\": true}" + * + * @since 15.0.0 + * + */ +interface IIndexOptions { + /** + * Get the value (as a string) for an option. + * + * @since 15.0.0 + * + * @param string $option + * @param string $default + * + * @return string + */ + public function getOption(string $option, string $default = ''): string; + + /** + * Get the value (as an array) for an option. + * + * @since 15.0.0 + * + * @param string $option + * @param array $default + * + * @return array + */ + public function getOptionArray(string $option, array $default = []): array; + + /** + * Get the value (as an boolean) for an option. + * + * @since 15.0.0 + * + * @param string $option + * @param bool $default + * + * @return bool + */ + public function getOptionBool(string $option, bool $default): bool; +} diff --git a/lib/public/FullTextSearch/Model/IRunner.php b/lib/public/FullTextSearch/Model/IRunner.php new file mode 100644 index 00000000000..3ea7de43dd7 --- /dev/null +++ b/lib/public/FullTextSearch/Model/IRunner.php @@ -0,0 +1,123 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Model; + +/** + * Interface IRunner + * + * The indexing process can be long and heavy, and because errors can + * be encountered the process is wrapped using this interface. + * It allows the any extension of FullTextSearch to communicate with the process. + * + * The IRunner is coming with some methods so the Search Platform can + * returns important information and errors to be displayed to the admin. + * + * @since 15.0.0 + * + */ +interface IRunner { + /** + * @since 15.0.0 + */ + public const RESULT_TYPE_SUCCESS = 1; + + /** + * @since 15.0.0 + */ + public const RESULT_TYPE_WARNING = 4; + + /** + * @since 15.0.0 + */ + public const RESULT_TYPE_FAIL = 9; + + + /** + * Info are displayed in the user interface when an admin execute the + * ./occ fulltextsearch:index command. + * + * quick list of info that can be edited: + * 'documentId', 'info', 'title', 'resultIndex', 'resultStatus', + * 'content', 'documentCurrent', 'documentTotal', 'progressStatus', + * 'errorCurrent', 'errorException', 'errorIndex'. + * + * List of all editable info can be find in the Command\Index.php of the + * FullTextSearch app. + * (look for a comment 'full list of info that can be edited') + * + * @since 15.0.0 + * + * @param string $info + * @param string $value + */ + public function setInfo(string $info, string $value); + + + /** + * This method should be used when editing multiple info to avoid too many + * refresh of the interface. + * + * @since 15.0.0 + * + * @param array $data + */ + public function setInfoArray(array $data); + + + /** + * Method used to update the current Action when an index is running. + * + * This method should be used instead of manually update the 'action' using + * setInfo()/setInfoArray() as it is also used to keep the process alive, + * manage the input, and some statistics of the load of the process. + * + * $action is a string with no space + * $force should be set to true if the action is heavy while being executed + * multiple times + * + * @since 15.0.0 + * + * @param string $action + * @param bool $force + * + * @return string + * @throws \Exception + */ + public function updateAction(string $action = '', bool $force = false): string; + + + /** + * Call this method in a Search Platform or Content Provider if there is an + * issue while generating a document or while indexing the current document. + * This is used to store and display errors in the UI during an index to help + * admin to keep track of errors. + * + * @since 15.0.0 + * + * @param IIndex $index + * @param string $message + * @param string $class + * @param int $sev + */ + public function newIndexError(IIndex $index, string $message, string $class = '', int $sev = 3); + + + /** + * Call this method only in a Search Platform after an index of a document. + * This is used to store and display results (good or bad) in the UI during + * an index to help admin to keep track of fail and successful indexes. + * + * @since 15.0.0 + * + * @param IIndex $index + * @param string $message + * @param string $status + * @param int $type + */ + public function newIndexResult(IIndex $index, string $message, string $status, int $type); +} diff --git a/lib/public/FullTextSearch/Model/ISearchOption.php b/lib/public/FullTextSearch/Model/ISearchOption.php new file mode 100644 index 00000000000..50e2cb5010a --- /dev/null +++ b/lib/public/FullTextSearch/Model/ISearchOption.php @@ -0,0 +1,143 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Model; + +/** + * @since 16.0.0 + * + * Interface ISearchOption + * + */ +interface ISearchOption { + /** + * @since 16.0.0 + */ + public const CHECKBOX = 'checkbox'; + + /** + * @since 16.0.0 + */ + public const INPUT = 'input'; + + /** + * @since 16.0.0 + */ + public const INPUT_SMALL = 'small'; + + + /** + * Set the name/key of the option. + * The string should only contains alphanumerical chars and underscore. + * The key can be retrieve when using ISearchRequest::getOption + * + * @see ISearchRequest::getOption + * + * @since 16.0.0 + * + * @param string $name + * + * @return ISearchOption + */ + public function setName(string $name): ISearchOption; + + /** + * Get the name/key of the option. + * + * @since 16.0.0 + * + * @return string + */ + public function getName(): string; + + + /** + * Set the title/display name of the option. + * + * @since 16.0.0 + * + * @param string $title + * + * @return ISearchOption + */ + public function setTitle(string $title): ISearchOption; + + /** + * Get the title of the option. + * + * @since 16.0.0 + * + * @return string + */ + public function getTitle(): string; + + + /** + * Set the type of the option. + * $type can be ISearchOption::CHECKBOX or ISearchOption::INPUT + * + * @since 16.0.0 + * + * @param string $type + * + * @return ISearchOption + */ + public function setType(string $type): ISearchOption; + + /** + * Get the type of the option. + * + * @since 16.0.0 + * + * @return string + */ + public function getType(): string; + + + /** + * In case of Type is INPUT, set the size of the input field. + * Value can be ISearchOption::INPUT_SMALL or not defined. + * + * @since 16.0.0 + * + * @param string $size + * + * @return ISearchOption + */ + public function setSize(string $size): ISearchOption; + + /** + * Get the size of the INPUT. + * + * @since 16.0.0 + * + * @return string + */ + public function getSize(): string; + + + /** + * In case of Type is , set the placeholder to be displayed in the input + * field. + * + * @since 16.0.0 + * + * @param string $placeholder + * + * @return ISearchOption + */ + public function setPlaceholder(string $placeholder): ISearchOption; + + /** + * Get the placeholder. + * + * @since 16.0.0 + * + * @return string + */ + public function getPlaceholder(): string; +} diff --git a/lib/public/FullTextSearch/Model/ISearchRequest.php b/lib/public/FullTextSearch/Model/ISearchRequest.php new file mode 100644 index 00000000000..9dc9613c407 --- /dev/null +++ b/lib/public/FullTextSearch/Model/ISearchRequest.php @@ -0,0 +1,339 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Model; + +/** + * Interface ISearchRequest + * + * When a search request is initiated, from a request from the front-end or using + * the IFullTextSearchManager::search() method, FullTextSearch will create a + * SearchRequest object, based on this interface. + * + * The object will be passed to the targeted Content Provider so it can convert + * search options using available method. + * + * The object is then encapsulated in a SearchResult and send to the + * Search Platform. + * + * @since 15.0.0 + * + * + */ +interface ISearchRequest { + /** + * Get the maximum number of results to be returns by the Search Platform. + * + * @since 15.0.0 + * + * @return int + */ + public function getSize(): int; + + + /** + * Get the current page. + * Used by pagination. + * + * @since 15.0.0 + * + * @return int + */ + public function getPage(): int; + + + /** + * Get the author of the request. + * + * @since 15.0.0 + * + * @return string + */ + public function getAuthor(): string; + + /** + * Get the searched string. + * + * @since 15.0.0 + * + * @return string + */ + public function getSearch(): string; + + /** + * Set the searched string. + * + * @param string $search + * + * @since 17.0.0 + * + * @return ISearchRequest + */ + public function setSearch(string $search): ISearchRequest; + + /** + * Extends the searched string. + * + * @since 17.0.0 + * + * @param string $search + * + * @return ISearchRequest + */ + public function addSearch(string $search): ISearchRequest; + + + /** + * Get the value of an option (as string). + * + * @since 15.0.0 + * + * @param string $option + * @param string $default + * + * @return string + */ + public function getOption(string $option, string $default = ''): string; + + /** + * Get the value of an option (as array). + * + * @since 15.0.0 + * + * @param string $option + * @param array $default + * + * @return array + */ + public function getOptionArray(string $option, array $default = []): array; + + + /** + * Limit the search to a part of the document. + * + * @since 15.0.0 + * + * @param string $part + * + * @return ISearchRequest + */ + public function addPart(string $part): ISearchRequest; + + /** + * Limit the search to an array of parts of the document. + * + * @since 15.0.0 + * + * @param array $parts + * + * @return ISearchRequest + */ + public function setParts(array $parts): ISearchRequest; + + /** + * Get the parts the search is limited to. + * + * @since 15.0.0 + * + * @return array + */ + public function getParts(): array; + + + /** + * Limit the search to a specific meta tag. + * + * @since 15.0.0 + * + * @param string $tag + * + * @return ISearchRequest + */ + public function addMetaTag(string $tag): ISearchRequest; + + /** + * Get the meta tags the search is limited to. + * + * @since 15.0.0 + * + * @return array + */ + public function getMetaTags(): array; + + /** + * Limit the search to an array of meta tags. + * + * @since 15.0.0 + * + * @param array $tags + * + * @return ISearchRequest + */ + public function setMetaTags(array $tags): ISearchRequest; + + + /** + * Limit the search to a specific sub tag. + * + * @since 15.0.0 + * + * @param string $source + * @param string $tag + * + * @return ISearchRequest + */ + public function addSubTag(string $source, string $tag): ISearchRequest; + + /** + * Get the sub tags the search is limited to. + * + * @since 15.0.0 + * + * @param bool $formatted + * + * @return array + */ + public function getSubTags(bool $formatted): array; + + /** + * Limit the search to an array of sub tags. + * + * @since 15.0.0 + * + * @param array $tags + * + * @return ISearchRequest + */ + public function setSubTags(array $tags): ISearchRequest; + + + /** + * Limit the search to a specific field of the mapping, using a full string. + * + * @since 15.0.0 + * + * @param string $field + * + * @return ISearchRequest + */ + public function addLimitField(string $field): ISearchRequest; + + /** + * Get the fields the search is limited to. + * + * @since 15.0.0 + * + * @return array + */ + public function getLimitFields(): array; + + + /** + * Limit the search to a specific field of the mapping, using a wildcard on + * the search string. + * + * @since 15.0.0 + * + * @param string $field + * + * @return ISearchRequest + */ + public function addWildcardField(string $field): ISearchRequest; + + /** + * Get the limit to field of the mapping. + * + * @since 15.0.0 + * + * @return array + */ + public function getWildcardFields(): array; + + + /** + * Filter the results, based on a group of field, using regex + * + * @since 15.0.0 + * + * @param array $filters + * + * @return ISearchRequest + */ + public function addRegexFilters(array $filters): ISearchRequest; + + /** + * Get the regex filters the search is limit to. + * + * @since 15.0.0 + * + * @return array + */ + public function getRegexFilters(): array; + + + /** + * Filter the results, based on a group of field, using wildcard + * + * @since 15.0.0 + * + * @param array $filter + * + * @return ISearchRequest + */ + public function addWildcardFilter(array $filter): ISearchRequest; + + /** + * Get the wildcard filters the search is limit to. + * + * @since 15.0.0 + * + * @return array + */ + public function getWildcardFilters(): array; + + + /** + * Add an extra field to the search. + * + * @since 15.0.0 + * + * @param string $field + * + * @return ISearchRequest + */ + public function addField(string $field): ISearchRequest; + + /** + * Get the list of extra field to search into. + * + * @since 15.0.0 + * + * @return array + */ + public function getFields(): array; + + + + /** + * Add a MUST search on an extra field + * + * @param ISearchRequestSimpleQuery $query + * + * @return ISearchRequest + * @since 17.0.0 + */ + public function addSimpleQuery(ISearchRequestSimpleQuery $query): ISearchRequest; + + + /** + * Get the list of queries on extra field. + * + * @return ISearchRequestSimpleQuery[] + * @since 17.0.0 + */ + public function getSimpleQueries(): array; +} diff --git a/lib/public/FullTextSearch/Model/ISearchRequestSimpleQuery.php b/lib/public/FullTextSearch/Model/ISearchRequestSimpleQuery.php new file mode 100644 index 00000000000..3a6217398b6 --- /dev/null +++ b/lib/public/FullTextSearch/Model/ISearchRequestSimpleQuery.php @@ -0,0 +1,153 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Model; + +/** + * Interface ISearchRequestSimpleQuery + * + * Add a Query during a Search Request... + * - on a specific field, + * - using a specific value, + * - with a specific comparison + * + * @since 17.0.0 + * + */ +interface ISearchRequestSimpleQuery { + /** + * @since 17.0.0 + */ + public const COMPARE_TYPE_TEXT = 1; + + /** + * @since 17.0.0 + */ + public const COMPARE_TYPE_KEYWORD = 2; + + /** + * @since 17.0.0 + */ + public const COMPARE_TYPE_INT_EQ = 3; + + /** + * @since 17.0.0 + */ + public const COMPARE_TYPE_INT_GTE = 4; + + /** + * @since 17.0.0 + */ + public const COMPARE_TYPE_INT_GT = 5; + + /** + * @since 17.0.0 + */ + public const COMPARE_TYPE_INT_LTE = 6; + + /** + * @since 17.0.0 + */ + public const COMPARE_TYPE_INT_LT = 7; + + /** + * @since 17.0.0 + */ + public const COMPARE_TYPE_BOOL = 8; + + /** + * @since 17.0.0 + */ + public const COMPARE_TYPE_ARRAY = 9; + + /** + * @since 17.0.0 + */ + public const COMPARE_TYPE_REGEX = 10; + + /** + * @since 17.0.0 + */ + public const COMPARE_TYPE_WILDCARD = 11; + + + /** + * Get the compare type of the query + * + * @return int + * @since 17.0.0 + */ + public function getType(): int; + + + /** + * Get the field to apply query + * + * @return string + * @since 17.0.0 + */ + public function getField(): string; + + /** + * Set the field to apply query + * + * @param string $field + * + * @return ISearchRequestSimpleQuery + * @since 17.0.0 + */ + public function setField(string $field): ISearchRequestSimpleQuery; + + + /** + * Get the all values to compare + * + * @return array + * @since 17.0.0 + */ + public function getValues(): array; + + /** + * Add value to compare (string) + * + * @param string $value + * + * @return ISearchRequestSimpleQuery + * @since 17.0.0 + */ + public function addValue(string $value): ISearchRequestSimpleQuery; + + /** + * Add value to compare (int) + * + * @param int $value + * + * @return ISearchRequestSimpleQuery + * @since 17.0.0 + */ + public function addValueInt(int $value): ISearchRequestSimpleQuery; + + /** + * Add value to compare (array) + * + * @param array $value + * + * @return ISearchRequestSimpleQuery + * @since 17.0.0 + */ + public function addValueArray(array $value): ISearchRequestSimpleQuery; + + /** + * Add value to compare (bool) + * + * @param bool $value + * + * @return ISearchRequestSimpleQuery + * @since 17.0.0 + */ + public function addValueBool(bool $value): ISearchRequestSimpleQuery; +} diff --git a/lib/public/FullTextSearch/Model/ISearchResult.php b/lib/public/FullTextSearch/Model/ISearchResult.php new file mode 100644 index 00000000000..cf902835a4c --- /dev/null +++ b/lib/public/FullTextSearch/Model/ISearchResult.php @@ -0,0 +1,168 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Model; + +use OCP\FullTextSearch\IFullTextSearchProvider; + +/** + * Interface ISearchResult + * + * When a search request is initiated, FullTextSearch will create a SearchResult + * object, based on this interface, containing the SearchRequest and the targeted + * Content Provider. + * + * The object will be passed to the Search Platform, which will proceed to the + * search and fill the SearchResult object with results. + * + * Then, the object will be passed to the targeted Content Provider that will + * improve the Search Results with detailed information. + * + * Finally, the SearchResult is returned to the original search request. + * + * @since 15.0.0 + * + */ +interface ISearchResult { + /** + * Get the original SearchRequest. + * + * @see ISearchRequest + * + * @since 15.0.0 + * + * @return ISearchRequest + */ + public function getRequest(): ISearchRequest; + + /** + * Get the targeted Content Provider. + * + * @since 15.0.0 + * + * @return IFullTextSearchProvider + */ + public function getProvider(): IFullTextSearchProvider; + + + /** + * Add an IIndexDocument as one of the result of the search request. + * + * @since 15.0.0 + * + * @param IIndexDocument $document + * + * @return ISearchResult + */ + public function addDocument(IIndexDocument $document): ISearchResult; + + /** + * Returns all result of the search request, in an array of IIndexDocument. + * + * @since 15.0.0 + * + * @return IIndexDocument[] + */ + public function getDocuments(): array; + + /** + * Set an array of IIndexDocument as the result of the search request. + * + * @since 15.0.0 + * + * @param IIndexDocument[] $documents + * + * @return ISearchResult + */ + public function setDocuments(array $documents): ISearchResult; + + + /** + * Add an aggregation to the result. + * + * @since 15.0.0 + * + * @param string $category + * @param string $value + * @param int $count + * + * @return ISearchResult + */ + public function addAggregation(string $category, string $value, int $count): ISearchResult; + + /** + * Get all aggregations. + * + * @since 15.0.0 + * + * @param string $category + * + * @return array + */ + public function getAggregations(string $category): array; + + + /** + * Set the raw result of the request. + * + * @since 15.0.0 + * + * @param string $result + * + * @return ISearchResult + */ + public function setRawResult(string $result): ISearchResult; + + + /** + * Set the total number of results for the search request. + * Used by pagination. + * + * @since 15.0.0 + * + * @param int $total + * + * @return ISearchResult + */ + public function setTotal(int $total): ISearchResult; + + + /** + * Set the top score for the search request. + * + * @since 15.0.0 + * + * @param int $score + * + * @return ISearchResult + */ + public function setMaxScore(int $score): ISearchResult; + + + /** + * Set the time spent by the request to perform the search. + * + * @since 15.0.0 + * + * @param int $time + * + * @return ISearchResult + */ + public function setTime(int $time): ISearchResult; + + + /** + * Set to true if the request timed out. + * + * @since 15.0.0 + * + * @param bool $timedOut + * + * @return ISearchResult + */ + public function setTimedOut(bool $timedOut): ISearchResult; +} diff --git a/lib/public/FullTextSearch/Model/ISearchTemplate.php b/lib/public/FullTextSearch/Model/ISearchTemplate.php new file mode 100644 index 00000000000..89f683ca013 --- /dev/null +++ b/lib/public/FullTextSearch/Model/ISearchTemplate.php @@ -0,0 +1,149 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Model; + +use OCP\FullTextSearch\IFullTextSearchProvider; + +/** + * Class ISearchTemplate + * + * This is a data transfer object that should be created by Content Provider + * when the getSearchTemplate() method is called. + * + * The object will contain templates to be displayed, and the list of the different + * options to be available to the user when they start a new search. + * + * The display of the Options is generated by the FullTextSearch app and Options + * can be displayed in 2 places: + * + * - the navigation page of the app that generate the indexed content. + * (files, bookmarks, deck, mails, ...) + * - the navigation page of the FullTextSearch app. + * + * Both pages will have different Options, and only the first one can integrate + * a specific template. + * + * @see IFullTextSearchProvider::getSearchTemplate + * + * @since 16.0.0 + * + */ +interface ISearchTemplate { + /** + * Set the class of the icon to be displayed in the left panel of the + * FullTextSearch navigation page, in front of the related Content Provider. + * + * @since 16.0.0 + * + * @param string $class + * + * @return ISearchTemplate + */ + public function setIcon(string $class): ISearchTemplate; + + /** + * Get the class of the icon. + * + * @since 16.0.0 + * + * @return string + */ + public function getIcon(): string; + + + /** + * Set the path of a CSS file that will be loaded when needed. + * + * @since 16.0.0 + * + * @param string $css + * + * @return ISearchTemplate + */ + public function setCss(string $css): ISearchTemplate; + + /** + * Get the path of the CSS file. + * + * @since 16.0.0 + * + * @return string + */ + public function getCss(): string; + + + /** + * Set the path of the file of a template that the HTML will be displayed + * below the Options. + * This should only be used if your Content Provider needs to set options in + * a way not generated by FullTextSearch + * + * @since 16.0.0 + * + * @param string $template + * + * @return ISearchTemplate + */ + public function setTemplate(string $template): ISearchTemplate; + + /** + * Get the path of the template file. + * + * @since 16.0.0 + * + * @return string + */ + public function getTemplate(): string; + + + /** + * Add an option in the Panel that is displayed when the user start a search + * within the app that generate the content. + * + * @see ISearchOption + * + * @since 16.0.0 + * + * @param ISearchOption $option + * + * @return ISearchTemplate + */ + public function addPanelOption(ISearchOption $option): ISearchTemplate; + + /** + * Get all options to be displayed in the Panel. + * + * @since 16.0.0 + * + * @return ISearchOption[] + */ + public function getPanelOptions(): array; + + + /** + * Add an option in the left panel of the FullTextSearch navigation page. + * + * @see ISearchOption + * + * @since 16.0.0 + * + * @param ISearchOption $option + * + * @return ISearchTemplate + */ + public function addNavigationOption(ISearchOption $option): ISearchTemplate; + + /** + * Get all options to be displayed in the FullTextSearch navigation page. + * + * @since 16.0.0 + * + * @return array + */ + public function getNavigationOptions(): array; +} diff --git a/lib/public/FullTextSearch/Service/IIndexService.php b/lib/public/FullTextSearch/Service/IIndexService.php new file mode 100644 index 00000000000..c4d1a9f8172 --- /dev/null +++ b/lib/public/FullTextSearch/Service/IIndexService.php @@ -0,0 +1,84 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Service; + +use OCP\FullTextSearch\Model\IIndex; + +/** + * Interface IIndexService + * + * @since 15.0.0 + * + */ +interface IIndexService { + /** + * Create an Index + * + * @since 15.0.1 + * + * @param string $providerId + * @param string $documentId + * @param string $userId + * @param int $status + * @return IIndex + */ + public function createIndex(string $providerId, string $documentId, string $userId, int $status): IIndex; + + + /** + * Retrieve an Index from the database, based on the Id of the Provider + * and the Id of the Document + * + * @since 15.0.0 + * + * @param string $providerId + * @param string $documentId + * + * @return IIndex + */ + public function getIndex(string $providerId, string $documentId): IIndex; + + + /** + * Update the status of an Index. status is a bit flag, setting $reset to + * true will reset the status to the value defined in the parameter. + * + * @since 15.0.0 + * + * @param string $providerId + * @param string $documentId + * @param int $status + * @param bool $reset + */ + public function updateIndexStatus(string $providerId, string $documentId, int $status, bool $reset = false); + + + /** + * Update the status of an array of Index. status is a bit flag, setting $reset to + * true will reset the status to the value defined in the parameter. + * + * @since 15.0.0 + * + * @param string $providerId + * @param array $documentIds + * @param int $status + * @param bool $reset + */ + public function updateIndexesStatus(string $providerId, array $documentIds, int $status, bool $reset = false); + + + /** + * Update an array of Index. + * + * @since 15.0.0 + * + * @param array $indexes + */ + public function updateIndexes(array $indexes); +} diff --git a/lib/public/FullTextSearch/Service/IProviderService.php b/lib/public/FullTextSearch/Service/IProviderService.php new file mode 100644 index 00000000000..e6036b1eb7d --- /dev/null +++ b/lib/public/FullTextSearch/Service/IProviderService.php @@ -0,0 +1,36 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Service; + +/** + * Interface IProviderService + * + * @since 15.0.0 + * + */ +interface IProviderService { + /** + * Check if the provider $providerId is already indexed. + * + * @since 15.0.0 + * + * @param string $providerId + * + * @return bool + */ + public function isProviderIndexed(string $providerId); + + + /** + * Add the Javascript API in the navigation page of an app. + * + * @since 15.0.0 + */ + public function addJavascriptAPI(); +} diff --git a/lib/public/FullTextSearch/Service/ISearchService.php b/lib/public/FullTextSearch/Service/ISearchService.php new file mode 100644 index 00000000000..ab3ec953789 --- /dev/null +++ b/lib/public/FullTextSearch/Service/ISearchService.php @@ -0,0 +1,60 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\FullTextSearch\Service; + +use OCP\FullTextSearch\Model\ISearchRequest; +use OCP\FullTextSearch\Model\ISearchResult; + +/** + * Interface ISearchService + * + * @since 15.0.0 + * + */ +interface ISearchService { + /** + * generate a search request, based on an array: + * + * $request = + * [ + * 'providers' => (string/array) 'all' + * 'author' => (string) owner of the document. + * 'search' => (string) search string, + * 'size' => (int) number of items to be return + * 'page' => (int) page + * 'parts' => (array) parts of document to search within, + * 'options' = (array) search options, + * 'tags' => (array) tags, + * 'metatags' => (array) metatags, + * 'subtags' => (array) subtags + * ] + * + * 'providers' can be an array of providerIds + * + * @since 15.0.0 + * + * @param array $request + * + * @return ISearchRequest + */ + public function generateSearchRequest(array $request): ISearchRequest; + + + /** + * Search documents + * + * @since 15.0.0 + * + * @param string $userId + * @param ISearchRequest $searchRequest + * + * @return ISearchResult[] + */ + public function search(string $userId, ISearchRequest $searchRequest): array; +} |