IFullTextSearchProvider.php 8.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * @copyright 2018
  5. *
  6. * @author Maxence Lange <maxence@artificial-owl.com>
  7. * @author Roeland Jago Douma <roeland@famdouma.nl>
  8. *
  9. * @license GNU AGPL version 3 or any later version
  10. *
  11. * This program is free software: you can redistribute it and/or modify
  12. * it under the terms of the GNU Affero General Public License as
  13. * published by the Free Software Foundation, either version 3 of the
  14. * License, or (at your option) any later version.
  15. *
  16. * This program is distributed in the hope that it will be useful,
  17. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  19. * GNU Affero General Public License for more details.
  20. *
  21. * You should have received a copy of the GNU Affero General Public License
  22. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  23. *
  24. */
  25. namespace OCP\FullTextSearch;
  26. use OCP\FullTextSearch\Model\IIndex;
  27. use OCP\FullTextSearch\Model\IIndexDocument;
  28. use OCP\FullTextSearch\Model\IIndexOptions;
  29. use OCP\FullTextSearch\Model\IRunner;
  30. use OCP\FullTextSearch\Model\ISearchRequest;
  31. use OCP\FullTextSearch\Model\ISearchResult;
  32. use OCP\FullTextSearch\Model\ISearchTemplate;
  33. /**
  34. * Interface IFullTextSearchProvider
  35. *
  36. * This interface must be use when creating a Content Provider for FullTextSearch.
  37. *
  38. * A Content Provider is an extension to the FullTextSearch that will extract and
  39. * provide content to the FullTextSearch.
  40. *
  41. * There is no limit to the number of Content Provider that can be integrated to
  42. * FullTextSearch. Each Content Provider corresponding to a type of content
  43. * available in Nextcloud (files, bookmarks, notes, deck cards, mails, ...)
  44. *
  45. * Content is split in document identified by an ID and the ID of the Content
  46. * Provider. The content is indexed by a Search Platform that will returns a
  47. * documentId as a result on a search request.
  48. *
  49. *
  50. * To oversimplify the mechanism:
  51. *
  52. * - When indexing, FullTextSearch will ask for documents to every Content Provider.
  53. * - On search, results from the Search Platform, identified by documentId, will
  54. * be improved by each relative Content Provider.
  55. *
  56. *
  57. * The Content Provider is a PHP class that implement this interface and is defined
  58. * in appinfo/info.xml of the app that contains that class:
  59. *
  60. * <fulltextsearch>
  61. * <provider>OCA\YourApp\YourContentProvider</provider>
  62. * </fulltextsearch>
  63. *
  64. * Multiple Content Provider can be defined in a single app.
  65. *
  66. * @since 15.0.0
  67. *
  68. */
  69. interface IFullTextSearchProvider {
  70. /**
  71. * Must returns a unique Id used to identify the Content Provider.
  72. * Id must contains only alphanumeric chars, with no space.
  73. *
  74. * @since 15.0.0
  75. *
  76. * @return string
  77. */
  78. public function getId(): string;
  79. /**
  80. * Must returns a descriptive name of the Content Provider.
  81. * This is used in multiple places, so better use a clear display name.
  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 Content Provider.
  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. * Must returns a ISearchTemplate that contains displayable items and
  100. * available options to users when searching.
  101. *
  102. * @see ISearchTemplate
  103. *
  104. * @since 15.0.0
  105. *
  106. * @return ISearchTemplate
  107. */
  108. public function getSearchTemplate(): ISearchTemplate;
  109. /**
  110. * Called when FullTextSearch is loading your Content Provider.
  111. *
  112. * @since 15.0.0
  113. */
  114. public function loadProvider();
  115. /**
  116. * Set the wrapper of the currently executed process.
  117. * Because the index process can be long and heavy, and because errors can
  118. * be encountered during the process, the IRunner is a wrapper that allow the
  119. * Content Provider to communicate with the process initiated by
  120. * FullTextSearch.
  121. *
  122. * The IRunner is coming with some methods so the Content Provider can
  123. * returns important information and errors to be displayed to the admin.
  124. *
  125. * @since 15.0.0
  126. *
  127. * @param IRunner $runner
  128. */
  129. public function setRunner(IRunner $runner);
  130. /**
  131. * This method is called when the administrator specify options when running
  132. * the ./occ fulltextsearch:index or ./occ fulltextsearch:live
  133. *
  134. * @since 15.0.0
  135. *
  136. * @param IIndexOptions $options
  137. */
  138. public function setIndexOptions(IIndexOptions $options);
  139. /**
  140. * Allow the provider to generate a list of chunk to split a huge list of
  141. * indexable documents
  142. *
  143. * During the indexing the generateIndexableDocuments method will be called
  144. * for each entry of the returned array.
  145. * If the returned array is empty, the generateIndexableDocuments() will be
  146. * called only once (per user).
  147. *
  148. * @since 16.0.0
  149. *
  150. * @param string $userId
  151. *
  152. * @return string[]
  153. */
  154. public function generateChunks(string $userId): array;
  155. /**
  156. * Returns all indexable document for a user as an array of IIndexDocument.
  157. *
  158. * There is no need to fill each IIndexDocument with content; at this point,
  159. * only fill the object with the minimum information to not waste memory while
  160. * still being able to identify the document it is referring to.
  161. *
  162. * FullTextSearch will call 2 other methods of this interface for each
  163. * IIndexDocument of the array, prior to their indexing:
  164. *
  165. * - first, to compare the date of the last index,
  166. * - then, to fill each IIndexDocument with complete data
  167. *
  168. * @see IIndexDocument
  169. *
  170. * @since 15.0.0
  171. * -> 16.0.0: the parameter "$chunk" was added
  172. *
  173. * @param string $userId
  174. * @param string $chunk
  175. *
  176. * @return IIndexDocument[]
  177. */
  178. public function generateIndexableDocuments(string $userId, string $chunk): array;
  179. /**
  180. * Called to verify that the document is not already indexed and that the
  181. * old index is not up-to-date, using the IIndex from
  182. * IIndexDocument->getIndex()
  183. *
  184. * Returning true will not queue the current IIndexDocument to any further
  185. * operation and will continue on the next element from the list returned by
  186. * generateIndexableDocuments().
  187. *
  188. * @since 15.0.0
  189. *
  190. * @param IIndexDocument $document
  191. *
  192. * @return bool
  193. */
  194. public function isDocumentUpToDate(IIndexDocument $document): bool;
  195. /**
  196. * Must fill IIndexDocument with all information relative to the document,
  197. * before its indexing by the Search Platform.
  198. *
  199. * Method is called for each element returned previously by
  200. * generateIndexableDocuments().
  201. *
  202. * @see IIndexDocument
  203. *
  204. * @since 15.0.0
  205. *
  206. * @param IIndexDocument $document
  207. */
  208. public function fillIndexDocument(IIndexDocument $document);
  209. /**
  210. * The Search Provider must create and return an IIndexDocument
  211. * based on the IIndex and its status. The IIndexDocument must contains all
  212. * information as it will be send for indexing.
  213. *
  214. * Method is called during a cron or a ./occ fulltextsearch:live after a
  215. * new document is created, or an old document is set as modified.
  216. *
  217. * @since 15.0.0
  218. *
  219. * @param IIndex $index
  220. *
  221. * @return IIndexDocument
  222. */
  223. public function updateDocument(IIndex $index): IIndexDocument;
  224. /**
  225. * Called when an index is initiated by the administrator.
  226. * This is should only be used in case of a specific mapping is needed.
  227. * (ie. _almost_ never)
  228. *
  229. * @since 15.0.0
  230. *
  231. * @param IFullTextSearchPlatform $platform
  232. */
  233. public function onInitializingIndex(IFullTextSearchPlatform $platform);
  234. /**
  235. * Called when administrator is resetting the index.
  236. * This is should only be used in case of a specific mapping has been
  237. * created.
  238. *
  239. * @since 15.0.0
  240. *
  241. * @param IFullTextSearchPlatform $platform
  242. */
  243. public function onResettingIndex(IFullTextSearchPlatform $platform);
  244. /**
  245. * Method is called when a search request is initiated by a user, prior to
  246. * be sent to the Search Platform.
  247. *
  248. * Your Content Provider can interact with the ISearchRequest to apply the
  249. * search options and make the search more precise.
  250. *
  251. * @see ISearchRequest
  252. *
  253. * @since 15.0.0
  254. *
  255. * @param ISearchRequest $searchRequest
  256. */
  257. public function improveSearchRequest(ISearchRequest $searchRequest);
  258. /**
  259. * Method is called after results of a search are returned by the
  260. * Search Platform.
  261. *
  262. * Your Content Provider can detail each entry with local data to improve
  263. * the display of the search result.
  264. *
  265. * @see ISearchResult
  266. *
  267. * @since 15.0.0
  268. *
  269. * @param ISearchResult $searchResult
  270. */
  271. public function improveSearchResult(ISearchResult $searchResult);
  272. /**
  273. * not used yet.
  274. *
  275. * @since 15.0.0
  276. */
  277. public function unloadProvider();
  278. }