IFullTextSearchPlatform.php 5.5 KB

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