1
0

IFullTextSearchPlatform.php 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-License-Identifier: AGPL-3.0-or-later
  6. */
  7. namespace OCP\FullTextSearch;
  8. use OCP\FullTextSearch\Model\IDocumentAccess;
  9. use OCP\FullTextSearch\Model\IIndex;
  10. use OCP\FullTextSearch\Model\IIndexDocument;
  11. use OCP\FullTextSearch\Model\IRunner;
  12. use OCP\FullTextSearch\Model\ISearchResult;
  13. /**
  14. * Interface IFullTextSearchPlatform
  15. *
  16. * This interface must be use when creating a Search Platform for FullTextSearch.
  17. *
  18. * A Search Platform is an extension to the FullTextSearch that will act as a
  19. * a gateway between FullTextSearch and a search server (ie. ElasticSearch,
  20. * Solr, ...)
  21. *
  22. * Multiple Search Platform can exist at the same time in Nextcloud, however only
  23. * one Search Platform will be used by FullTextSearch.
  24. * Administrator must select at least one Search Platform to be used by
  25. * FullTextSearch in the admin settings page.
  26. *
  27. * The content provided by FullTextSearch comes in chunk from multiple Content
  28. * Provider. Each chunk is identified by the ID of the Content Provider, and the
  29. * ID of the document.
  30. *
  31. *
  32. * To oversimplify the mechanism:
  33. *
  34. * - When indexing, FullTextSearch will send providerId, documentId, content.
  35. * - When searching within the content of a Content Provider, identified by its
  36. * providerId, FullTextSearch expect documentId as result.
  37. *
  38. *
  39. * The Search Platform ia a PHP class that implement this interface and is defined
  40. * in appinfo/info.xml of the app that contains that class:
  41. *
  42. * <fulltextsearch>
  43. * <platform>OCA\YourApp\YourSearchPlatform</platform>
  44. * </fulltextsearch>
  45. *
  46. * Multiple Search Platform can be defined in a single app.
  47. *
  48. * @since 15.0.0
  49. *
  50. */
  51. interface IFullTextSearchPlatform {
  52. /**
  53. * Must returns a unique Id used to identify the Search Platform.
  54. * Id must contains only alphanumeric chars, with no space.
  55. *
  56. * @since 15.0.0
  57. *
  58. * @return string
  59. */
  60. public function getId(): string;
  61. /**
  62. * Must returns a descriptive name of the Search Platform.
  63. * This is used mainly in the admin settings page to display the list of
  64. * available Search Platform
  65. *
  66. * @since 15.0.0
  67. *
  68. * @return string
  69. */
  70. public function getName(): string;
  71. /**
  72. * should returns the current configuration of the Search Platform.
  73. * This is used to display the configuration when using the
  74. * ./occ fulltextsearch:check command line.
  75. *
  76. * @since 15.0.0
  77. *
  78. * @return array
  79. */
  80. public function getConfiguration(): array;
  81. /**
  82. * Set the wrapper of the currently executed process.
  83. * Because the index process can be long and heavy, and because errors can
  84. * be encountered during the process, the IRunner is a wrapper that allow the
  85. * Search Platform to communicate with the process initiated by
  86. * FullTextSearch.
  87. *
  88. * The IRunner is coming with some methods so the Search Platform can
  89. * returns important information and errors to be displayed to the admin.
  90. *
  91. * @since 15.0.0
  92. *
  93. * @param IRunner $runner
  94. */
  95. public function setRunner(IRunner $runner);
  96. /**
  97. * Called when FullTextSearch is loading your Search Platform.
  98. *
  99. * @since 15.0.0
  100. */
  101. public function loadPlatform();
  102. /**
  103. * Called to check that your Search Platform is correctly configured and that
  104. * This is also the right place to check that the Search Service is available.
  105. *
  106. * @since 15.0.0
  107. *
  108. * @return bool
  109. */
  110. public function testPlatform(): bool;
  111. /**
  112. * Called before an index is initiated.
  113. * Best place to initiate some stuff on the Search Server (mapping, ...)
  114. *
  115. * @since 15.0.0
  116. */
  117. public function initializeIndex();
  118. /**
  119. * Reset the indexes for a specific providerId.
  120. * $providerId can be 'all' if it is a global reset.
  121. *
  122. * @since 15.0.0
  123. *
  124. * @param string $providerId
  125. */
  126. public function resetIndex(string $providerId);
  127. /**
  128. * Deleting some IIndex, sent in an array
  129. *
  130. * @see IIndex
  131. *
  132. * @since 15.0.0
  133. *
  134. * @param IIndex[] $indexes
  135. */
  136. public function deleteIndexes(array $indexes);
  137. /**
  138. * Indexing a document.
  139. *
  140. * @see IndexDocument
  141. *
  142. * @since 15.0.0
  143. *
  144. * @param IIndexDocument $document
  145. *
  146. * @return IIndex
  147. */
  148. public function indexDocument(IIndexDocument $document): IIndex;
  149. /**
  150. * Searching documents, ISearchResult should be updated with the result of
  151. * the search.
  152. *
  153. * @since 15.0.0
  154. *
  155. * @param ISearchResult $result
  156. * @param IDocumentAccess $access
  157. */
  158. public function searchRequest(ISearchResult $result, IDocumentAccess $access);
  159. /**
  160. * Return a document based on its Id and the Provider.
  161. * This is used when an admin execute ./occ fulltextsearch:document:platform
  162. *
  163. * @since 15.0.0
  164. *
  165. * @param string $providerId
  166. * @param string $documentId
  167. *
  168. * @return IIndexDocument
  169. */
  170. public function getDocument(string $providerId, string $documentId): IIndexDocument;
  171. }