1	<?php
2
3	namespace CirrusSearch\BuildDocument;
4
5	use Elastica\Document;
6	use MediaWiki\Page\WikiPage;
7	use MediaWiki\Revision\RevisionRecord;
8	use MediaWiki\Title\Title;
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	* @param bool $isRedirect Whether $page is a redirect, as already resolved by the
26	*  orchestrator from the same source as the rest of the build (avoids re-deriving it,
27	*  so page_type and redirect_target cannot disagree on the revision path)
28	*/
29	public function initialize( Document $doc, WikiPage $page, RevisionRecord $revision, bool $isRedirect ): void;
30
31	/**
32	* Called after a batch of pages have been passed to self::initialize.
33	*
34	* Allows implementations to batch calls to external services necessary for
35	* collecting page properties. Implementations must update the Document
36	* instances previously provided.
37	*
38	* The builder will be disposed of after finishing a batch.
39	*/
40	public function finishInitializeBatch(): void;
41
42	/**
43	* Finalize document building before sending to cluster.
44	*
45	* Called on every write attempt for every cluster to perform any final
46	* document building.  Intended for bulk loading of content from wiki
47	* databases that would only serve to bloat the job queue.
48	*
49	* @param Document $doc
50	* @param Title $title
51	* @param RevisionRecord $revision
52	* @throws BuildDocumentException
53	*/
54	public function finalize( Document $doc, Title $title, RevisionRecord $revision ): void;
55	}