1	<?php
2
3	namespace CirrusSearch\BuildDocument;
4
5	use Elastica\Document;
6	use MediaWiki\Revision\RevisionRecord;
7	use MediaWiki\Title\Title;
8	use WikiPage;
9
10	/**
11	* Interface for building subsets of the document stored in elasticsearch
12	* to represent individual wiki pages.
13	*/
14	interface PagePropertyBuilder {
15	/**
16	* Perform initial building of a page document.
17	*
18	* Called once per page when starting an update and is shared between all
19	* clusters written to. This doc may be written to the jobqueue multiple
20	* times and should not contain any large (in number of bytes) values.
21	*
22	* @param Document $doc The document to be populated
23	* @param WikiPage $page The page to scope operation to
24	* @param RevisionRecord $revision The page revision to use
25	*/
26	public function initialize( Document $doc, WikiPage $page, RevisionRecord $revision ): void;
27
28	/**
29	* Called after a batch of pages have been passed to self::initialize.
30	*
31	* Allows implementations to batch calls to external services necessary for
32	* collecting page properties. Implementations must update the Document
33	* instances previously provided.
34	*
35	* The builder will be disposed of after finishing a batch.
36	*/
37	public function finishInitializeBatch(): void;
38
39	/**
40	* Finalize document building before sending to cluster.
41	*
42	* Called on every write attempt for every cluster to perform any final
43	* document building.  Intended for bulk loading of content from wiki
44	* databases that would only serve to bloat the job queue.
45	*
46	* @param Document $doc
47	* @param Title $title
48	* @param RevisionRecord $revision
49	* @throws BuildDocumentException
50	*/
51	public function finalize( Document $doc, Title $title, RevisionRecord $revision ): void;
52	}