1
0

IFullTextSearchProvider.php 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295
  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\IIndex;
  9. use OCP\FullTextSearch\Model\IIndexDocument;
  10. use OCP\FullTextSearch\Model\IIndexOptions;
  11. use OCP\FullTextSearch\Model\IRunner;
  12. use OCP\FullTextSearch\Model\ISearchRequest;
  13. use OCP\FullTextSearch\Model\ISearchResult;
  14. use OCP\FullTextSearch\Model\ISearchTemplate;
  15. /**
  16. * Interface IFullTextSearchProvider
  17. *
  18. * This interface must be use when creating a Content Provider for FullTextSearch.
  19. *
  20. * A Content Provider is an extension to the FullTextSearch that will extract and
  21. * provide content to the FullTextSearch.
  22. *
  23. * There is no limit to the number of Content Provider that can be integrated to
  24. * FullTextSearch. Each Content Provider corresponding to a type of content
  25. * available in Nextcloud (files, bookmarks, notes, deck cards, mails, ...)
  26. *
  27. * Content is split in document identified by an ID and the ID of the Content
  28. * Provider. The content is indexed by a Search Platform that will returns a
  29. * documentId as a result on a search request.
  30. *
  31. *
  32. * To oversimplify the mechanism:
  33. *
  34. * - When indexing, FullTextSearch will ask for documents to every Content Provider.
  35. * - On search, results from the Search Platform, identified by documentId, will
  36. * be improved by each relative Content Provider.
  37. *
  38. *
  39. * The Content Provider is 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. * <provider>OCA\YourApp\YourContentProvider</provider>
  44. * </fulltextsearch>
  45. *
  46. * Multiple Content Provider can be defined in a single app.
  47. *
  48. * @since 15.0.0
  49. *
  50. */
  51. interface IFullTextSearchProvider {
  52. /**
  53. * Must returns a unique Id used to identify the Content Provider.
  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 Content Provider.
  63. * This is used in multiple places, so better use a clear display name.
  64. *
  65. * @since 15.0.0
  66. *
  67. * @return string
  68. */
  69. public function getName(): string;
  70. /**
  71. * Should returns the current configuration of the Content Provider.
  72. * This is used to display the configuration when using the
  73. * ./occ fulltextsearch:check command line.
  74. *
  75. * @since 15.0.0
  76. *
  77. * @return array
  78. */
  79. public function getConfiguration(): array;
  80. /**
  81. * Must returns a ISearchTemplate that contains displayable items and
  82. * available options to users when searching.
  83. *
  84. * @see ISearchTemplate
  85. *
  86. * @since 15.0.0
  87. *
  88. * @return ISearchTemplate
  89. */
  90. public function getSearchTemplate(): ISearchTemplate;
  91. /**
  92. * Called when FullTextSearch is loading your Content Provider.
  93. *
  94. * @since 15.0.0
  95. */
  96. public function loadProvider();
  97. /**
  98. * Set the wrapper of the currently executed process.
  99. * Because the index process can be long and heavy, and because errors can
  100. * be encountered during the process, the IRunner is a wrapper that allow the
  101. * Content Provider to communicate with the process initiated by
  102. * FullTextSearch.
  103. *
  104. * The IRunner is coming with some methods so the Content Provider can
  105. * returns important information and errors to be displayed to the admin.
  106. *
  107. * @since 15.0.0
  108. *
  109. * @param IRunner $runner
  110. */
  111. public function setRunner(IRunner $runner);
  112. /**
  113. * This method is called when the administrator specify options when running
  114. * the ./occ fulltextsearch:index or ./occ fulltextsearch:live
  115. *
  116. * @since 15.0.0
  117. *
  118. * @param IIndexOptions $options
  119. */
  120. public function setIndexOptions(IIndexOptions $options);
  121. /**
  122. * Allow the provider to generate a list of chunk to split a huge list of
  123. * indexable documents
  124. *
  125. * During the indexing the generateIndexableDocuments method will be called
  126. * for each entry of the returned array.
  127. * If the returned array is empty, the generateIndexableDocuments() will be
  128. * called only once (per user).
  129. *
  130. * @since 16.0.0
  131. *
  132. * @param string $userId
  133. *
  134. * @return string[]
  135. */
  136. public function generateChunks(string $userId): array;
  137. /**
  138. * Returns all indexable document for a user as an array of IIndexDocument.
  139. *
  140. * There is no need to fill each IIndexDocument with content; at this point,
  141. * only fill the object with the minimum information to not waste memory while
  142. * still being able to identify the document it is referring to.
  143. *
  144. * FullTextSearch will call 2 other methods of this interface for each
  145. * IIndexDocument of the array, prior to their indexing:
  146. *
  147. * - first, to compare the date of the last index,
  148. * - then, to fill each IIndexDocument with complete data
  149. *
  150. * @see IIndexDocument
  151. *
  152. * @since 15.0.0
  153. * -> 16.0.0: the parameter "$chunk" was added
  154. *
  155. * @param string $userId
  156. * @param string $chunk
  157. *
  158. * @return IIndexDocument[]
  159. */
  160. public function generateIndexableDocuments(string $userId, string $chunk): array;
  161. /**
  162. * Called to verify that the document is not already indexed and that the
  163. * old index is not up-to-date, using the IIndex from
  164. * IIndexDocument->getIndex()
  165. *
  166. * Returning true will not queue the current IIndexDocument to any further
  167. * operation and will continue on the next element from the list returned by
  168. * generateIndexableDocuments().
  169. *
  170. * @since 15.0.0
  171. *
  172. * @param IIndexDocument $document
  173. *
  174. * @return bool
  175. */
  176. public function isDocumentUpToDate(IIndexDocument $document): bool;
  177. /**
  178. * Must fill IIndexDocument with all information relative to the document,
  179. * before its indexing by the Search Platform.
  180. *
  181. * Method is called for each element returned previously by
  182. * generateIndexableDocuments().
  183. *
  184. * @see IIndexDocument
  185. *
  186. * @since 15.0.0
  187. *
  188. * @param IIndexDocument $document
  189. */
  190. public function fillIndexDocument(IIndexDocument $document);
  191. /**
  192. * The Search Provider must create and return an IIndexDocument
  193. * based on the IIndex and its status. The IIndexDocument must contains all
  194. * information as it will be send for indexing.
  195. *
  196. * Method is called during a cron or a ./occ fulltextsearch:live after a
  197. * new document is created, or an old document is set as modified.
  198. *
  199. * @since 15.0.0
  200. *
  201. * @param IIndex $index
  202. *
  203. * @return IIndexDocument
  204. */
  205. public function updateDocument(IIndex $index): IIndexDocument;
  206. /**
  207. * Called when an index is initiated by the administrator.
  208. * This is should only be used in case of a specific mapping is needed.
  209. * (ie. _almost_ never)
  210. *
  211. * @since 15.0.0
  212. *
  213. * @param IFullTextSearchPlatform $platform
  214. */
  215. public function onInitializingIndex(IFullTextSearchPlatform $platform);
  216. /**
  217. * Called when administrator is resetting the index.
  218. * This is should only be used in case of a specific mapping has been
  219. * created.
  220. *
  221. * @since 15.0.0
  222. *
  223. * @param IFullTextSearchPlatform $platform
  224. */
  225. public function onResettingIndex(IFullTextSearchPlatform $platform);
  226. /**
  227. * Method is called when a search request is initiated by a user, prior to
  228. * be sent to the Search Platform.
  229. *
  230. * Your Content Provider can interact with the ISearchRequest to apply the
  231. * search options and make the search more precise.
  232. *
  233. * @see ISearchRequest
  234. *
  235. * @since 15.0.0
  236. *
  237. * @param ISearchRequest $searchRequest
  238. */
  239. public function improveSearchRequest(ISearchRequest $searchRequest);
  240. /**
  241. * Method is called after results of a search are returned by the
  242. * Search Platform.
  243. *
  244. * Your Content Provider can detail each entry with local data to improve
  245. * the display of the search result.
  246. *
  247. * @see ISearchResult
  248. *
  249. * @since 15.0.0
  250. *
  251. * @param ISearchResult $searchResult
  252. */
  253. public function improveSearchResult(ISearchResult $searchResult);
  254. /**
  255. * not used yet.
  256. *
  257. * @since 15.0.0
  258. */
  259. public function unloadProvider();
  260. }