IIndexDocument.php 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * @copyright 2018
  5. *
  6. * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  7. * @author Maxence Lange <maxence@artificial-owl.com>
  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\Model;
  26. /**
  27. * Class IIndexDocument
  28. *
  29. * This is one of the main class of the FullTextSearch, used as a data transfer
  30. * object. An IIndexDocument is created to manage documents around FullTextSearch,
  31. * during an index and during a search.
  32. * The uniqueness of an IIndexDocument is made by the Id of the Content Provider
  33. * and the Id of the original document within the Content Provider.
  34. *
  35. * We will call original document the source from which the IIndexDocument is
  36. * generated. As an example, an original document can be a file, a mail, ...
  37. *
  38. * @since 15.0.0
  39. */
  40. interface IIndexDocument {
  41. public const NOT_ENCODED = 0;
  42. public const ENCODED_BASE64 = 1;
  43. /**
  44. * Returns the Id of the original document.
  45. *
  46. * @since 15.0.0
  47. *
  48. * @return string
  49. */
  50. public function getId(): string;
  51. /**
  52. * Returns the Id of the provider.
  53. *
  54. * @since 15.0.0
  55. *
  56. * @return string
  57. */
  58. public function getProviderId(): string;
  59. /**
  60. * Set the Index related to the IIndexDocument.
  61. *
  62. * @see IIndex
  63. *
  64. * @since 15.0.0
  65. *
  66. * @param IIndex $index
  67. *
  68. * @return IIndexDocument
  69. */
  70. public function setIndex(IIndex $index): IIndexDocument;
  71. /**
  72. * Get the Index.
  73. *
  74. * @since 15.0.0
  75. *
  76. * @return IIndex
  77. */
  78. public function getIndex(): IIndex;
  79. /**
  80. * return if Index is defined.
  81. *
  82. * @since 16.0.0
  83. *
  84. * @return bool
  85. */
  86. public function hasIndex(): bool;
  87. /**
  88. * Set the modified time of the original document.
  89. *
  90. * @since 15.0.0
  91. *
  92. * @param int $modifiedTime
  93. *
  94. * @return IIndexDocument
  95. */
  96. public function setModifiedTime(int $modifiedTime): IIndexDocument;
  97. /**
  98. * Get the modified time of the original document.
  99. *
  100. * @since 15.0.0
  101. *
  102. * @return int
  103. */
  104. public function getModifiedTime(): int;
  105. /**
  106. * Check if the original document of the IIndexDocument is older than $time.
  107. *
  108. * @since 15.0.0
  109. *
  110. * @param int $time
  111. *
  112. * @return bool
  113. */
  114. public function isOlderThan(int $time): bool;
  115. /**
  116. * Set the read rights of the original document using a IDocumentAccess.
  117. *
  118. * @see IDocumentAccess
  119. *
  120. * @since 15.0.0
  121. *
  122. * @param IDocumentAccess $access
  123. *
  124. * @return $this
  125. */
  126. public function setAccess(IDocumentAccess $access): IIndexDocument;
  127. /**
  128. * Get the IDocumentAccess related to the original document.
  129. *
  130. * @since 15.0.0
  131. *
  132. * @return IDocumentAccess
  133. */
  134. public function getAccess(): IDocumentAccess;
  135. /**
  136. * Add a tag to the list.
  137. *
  138. * @since 15.0.0
  139. *
  140. * @param string $tag
  141. *
  142. * @return IIndexDocument
  143. */
  144. public function addTag(string $tag): IIndexDocument;
  145. /**
  146. * Set the list of tags assigned to the original document.
  147. *
  148. * @since 15.0.0
  149. *
  150. * @param array $tags
  151. *
  152. * @return IIndexDocument
  153. */
  154. public function setTags(array $tags): IIndexDocument;
  155. /**
  156. * Get the list of tags assigned to the original document.
  157. *
  158. * @since 15.0.0
  159. *
  160. * @return array
  161. */
  162. public function getTags(): array;
  163. /**
  164. * Add a meta tag to the list.
  165. *
  166. * @since 15.0.0
  167. *
  168. * @param string $tag
  169. *
  170. * @return IIndexDocument
  171. */
  172. public function addMetaTag(string $tag): IIndexDocument;
  173. /**
  174. * Set the list of meta tags assigned to the original document.
  175. *
  176. * @since 15.0.0
  177. *
  178. * @param array $tags
  179. *
  180. * @return IIndexDocument
  181. */
  182. public function setMetaTags(array $tags): IIndexDocument;
  183. /**
  184. * Get the list of meta tags assigned to the original document.
  185. *
  186. * @since 15.0.0
  187. *
  188. * @return array
  189. */
  190. public function getMetaTags(): array;
  191. /**
  192. * Add a sub tag to the list.
  193. *
  194. * @since 15.0.0
  195. *
  196. * @param string $sub
  197. * @param string $tag
  198. *
  199. * @return IIndexDocument
  200. */
  201. public function addSubTag(string $sub, string $tag): IIndexDocument;
  202. /**
  203. * Set the list of sub tags assigned to the original document.
  204. *
  205. * @since 15.0.0
  206. *
  207. * @param array $tags
  208. *
  209. * @return IIndexDocument
  210. */
  211. public function setSubTags(array $tags): IIndexDocument;
  212. /**
  213. * Get the list of sub tags assigned to the original document.
  214. * If $formatted is true, the result will be formatted in a one
  215. * dimensional array.
  216. *
  217. * @since 15.0.0
  218. *
  219. * @param bool $formatted
  220. *
  221. * @return array
  222. */
  223. public function getSubTags(bool $formatted = false): array;
  224. /**
  225. * Set the source of the original document.
  226. *
  227. * @since 15.0.0
  228. *
  229. * @param string $source
  230. *
  231. * @return IIndexDocument
  232. */
  233. public function setSource(string $source): IIndexDocument;
  234. /**
  235. * Get the source of the original document.
  236. *
  237. * @since 15.0.0
  238. *
  239. * @return string
  240. */
  241. public function getSource(): string;
  242. /**
  243. * Set the title of the original document.
  244. *
  245. * @since 15.0.0
  246. *
  247. * @param string $title
  248. *
  249. * @return IIndexDocument
  250. */
  251. public function setTitle(string $title): IIndexDocument;
  252. /**
  253. * Get the title of the original document.
  254. *
  255. * @since 15.0.0
  256. *
  257. * @return string
  258. */
  259. public function getTitle(): string;
  260. /**
  261. * Set the content of the document.
  262. * $encoded can be NOT_ENCODED or ENCODED_BASE64 if the content is raw or
  263. * encoded in base64.
  264. *
  265. * @since 15.0.0
  266. *
  267. * @param string $content
  268. * @param int $encoded
  269. *
  270. * @return IIndexDocument
  271. */
  272. public function setContent(string $content, int $encoded = 0): IIndexDocument;
  273. /**
  274. * Get the content of the original document.
  275. *
  276. * @since 15.0.0
  277. *
  278. * @return string
  279. */
  280. public function getContent(): string;
  281. /**
  282. * Returns the type of the encoding on the content.
  283. *
  284. * @since 15.0.0
  285. *
  286. * @return int
  287. */
  288. public function isContentEncoded(): int;
  289. /**
  290. * Return the size of the content.
  291. *
  292. * @since 15.0.0
  293. *
  294. * @return int
  295. */
  296. public function getContentSize(): int;
  297. /**
  298. * Generate an hash, based on the content of the original document.
  299. *
  300. * @since 15.0.0
  301. *
  302. * @return IIndexDocument
  303. */
  304. public function initHash(): IIndexDocument;
  305. /**
  306. * Set the hash of the original document.
  307. *
  308. * @since 15.0.0
  309. *
  310. * @param string $hash
  311. *
  312. * @return IIndexDocument
  313. */
  314. public function setHash(string $hash): IIndexDocument;
  315. /**
  316. * Get the hash of the original document.
  317. *
  318. * @since 15.0.0
  319. *
  320. * @return string
  321. */
  322. public function getHash(): string;
  323. /**
  324. * Add a part, identified by a string, and its content.
  325. *
  326. * It is strongly advised to use alphanumerical chars with no space in the
  327. * $part string.
  328. *
  329. * @since 15.0.0
  330. *
  331. * @param string $part
  332. * @param string $content
  333. *
  334. * @return IIndexDocument
  335. */
  336. public function addPart(string $part, string $content): IIndexDocument;
  337. /**
  338. * Set all parts and their content.
  339. *
  340. * @since 15.0.0
  341. *
  342. * @param array $parts
  343. *
  344. * @return IIndexDocument
  345. */
  346. public function setParts(array $parts): IIndexDocument;
  347. /**
  348. * Get all parts of the IIndexDocument.
  349. *
  350. * @since 15.0.0
  351. *
  352. * @return array
  353. */
  354. public function getParts(): array;
  355. /**
  356. * Add a link, usable by the frontend.
  357. *
  358. * @since 15.0.0
  359. *
  360. * @param string $link
  361. *
  362. * @return IIndexDocument
  363. */
  364. public function setLink(string $link): IIndexDocument;
  365. /**
  366. * Get the link.
  367. *
  368. * @since 15.0.0
  369. *
  370. * @return string
  371. */
  372. public function getLink(): string;
  373. /**
  374. * Set more information that couldn't be set using other method.
  375. *
  376. * @since 15.0.0
  377. *
  378. * @param array $more
  379. *
  380. * @return IIndexDocument
  381. */
  382. public function setMore(array $more): IIndexDocument;
  383. /**
  384. * Get more information.
  385. *
  386. * @since 15.0.0
  387. *
  388. * @return array
  389. */
  390. public function getMore(): array;
  391. /**
  392. * Add some excerpt of the content of the original document, usually based
  393. * on the search request.
  394. *
  395. * @since 16.0.0
  396. *
  397. * @param string $source
  398. * @param string $excerpt
  399. *
  400. * @return IIndexDocument
  401. */
  402. public function addExcerpt(string $source, string $excerpt): IIndexDocument;
  403. /**
  404. * Set all excerpts of the content of the original document.
  405. *
  406. * @since 16.0.0
  407. *
  408. * @param array $excerpts
  409. *
  410. * @return IIndexDocument
  411. */
  412. public function setExcerpts(array $excerpts): IIndexDocument;
  413. /**
  414. * Get all excerpts of the content of the original document.
  415. *
  416. * @since 15.0.0
  417. *
  418. * @return array
  419. */
  420. public function getExcerpts(): array;
  421. /**
  422. * Set the score to the result assigned to this document during a search
  423. * request.
  424. *
  425. * @since 15.0.0
  426. *
  427. * @param string $score
  428. *
  429. * @return IIndexDocument
  430. */
  431. public function setScore(string $score): IIndexDocument;
  432. /**
  433. * Get the score.
  434. *
  435. * @since 15.0.0
  436. *
  437. * @return string
  438. */
  439. public function getScore(): string;
  440. /**
  441. * Set some information about the original document that will be available
  442. * to the front-end when displaying search result. (as string)
  443. * Because this information will not be indexed, this method can also be
  444. * used to manage some data while filling the IIndexDocument before its
  445. * indexing.
  446. *
  447. * @since 15.0.0
  448. *
  449. * @param string $info
  450. * @param string $value
  451. *
  452. * @return IIndexDocument
  453. */
  454. public function setInfo(string $info, string $value): IIndexDocument;
  455. /**
  456. * Get an information about a document. (string)
  457. *
  458. * @since 15.0.0
  459. *
  460. * @param string $info
  461. * @param string $default
  462. *
  463. * @return string
  464. */
  465. public function getInfo(string $info, string $default = ''): string;
  466. /**
  467. * Set some information about the original document that will be available
  468. * to the front-end when displaying search result. (as array)
  469. * Because this information will not be indexed, this method can also be
  470. * used to manage some data while filling the IIndexDocument before its
  471. * indexing.
  472. *
  473. * @since 15.0.0
  474. *
  475. * @param string $info
  476. * @param array $value
  477. *
  478. * @return IIndexDocument
  479. */
  480. public function setInfoArray(string $info, array $value): IIndexDocument;
  481. /**
  482. * Get an information about a document. (array)
  483. *
  484. * @since 15.0.0
  485. *
  486. * @param string $info
  487. * @param array $default
  488. *
  489. * @return array
  490. */
  491. public function getInfoArray(string $info, array $default = []): array;
  492. /**
  493. * Set some information about the original document that will be available
  494. * to the front-end when displaying search result. (as int)
  495. * Because this information will not be indexed, this method can also be
  496. * used to manage some data while filling the IIndexDocument before its
  497. * indexing.
  498. *
  499. * @since 15.0.0
  500. *
  501. * @param string $info
  502. * @param int $value
  503. *
  504. * @return IIndexDocument
  505. */
  506. public function setInfoInt(string $info, int $value): IIndexDocument;
  507. /**
  508. * Get an information about a document. (int)
  509. *
  510. * @since 15.0.0
  511. *
  512. * @param string $info
  513. * @param int $default
  514. *
  515. * @return int
  516. */
  517. public function getInfoInt(string $info, int $default = 0): int;
  518. /**
  519. * Set some information about the original document that will be available
  520. * to the front-end when displaying search result. (as bool)
  521. * Because this information will not be indexed, this method can also be
  522. * used to manage some data while filling the IIndexDocument before its
  523. * indexing.
  524. *
  525. * @since 15.0.0
  526. *
  527. * @param string $info
  528. * @param bool $value
  529. *
  530. * @return IIndexDocument
  531. */
  532. public function setInfoBool(string $info, bool $value): IIndexDocument;
  533. /**
  534. * Get an information about a document. (bool)
  535. *
  536. * @since 15.0.0
  537. *
  538. * @param string $info
  539. * @param bool $default
  540. *
  541. * @return bool
  542. */
  543. public function getInfoBool(string $info, bool $default = false): bool;
  544. /**
  545. * Get all info.
  546. *
  547. * @since 15.0.0
  548. *
  549. * @return array
  550. */
  551. public function getInfoAll(): array;
  552. }