docs/pageupdater.txt

   1 This document provides an overview of the usage of PageUpdater and DerivedPageDataUpdater.
   2
   3 == PageUpdater ==
   4 PageUpdater is the canonical way to create page revisions, that is, to perform edits.
   5
   6 PageUpdater is a stateful, handle-like object that allows new revisions to be created
   7 on a given wiki page using the saveRevision() method. PageUpdater provides setters for
   8 defining the new revision's content as well as meta-data such as change tags. saveRevision()
   9 stores the new revision's primary content and metadata, and triggers the necessary
  10 updates to derived secondary data and cached artifacts e.g. in the ParserCache and the
  11 CDN layer, using a DerivedPageDataUpdater.
  12
  13 PageUpdater instances follow the below life cycle, defined by a number of
  14 methods:
  15
  16                           +----------------------------+
  17                           |                            |
  18                           |             new            |
  19                           |                            |
  20                           +------|--------------|------+
  21                                  |              |
  22             grabParentRevision()-|              |
  23             or hasEditConflict()-|              |
  24                                  |              |
  25                         +--------v-------+      |
  26                         |                |      |
  27                         |  parent known  |      |
  28                         |                |      |
  29   Enables---------------+--------|-------+      |
  30     safe operations based on     |              |-saveRevision()
  31     the parent revision, e.g.    |              |
  32     section replacement or       |              |
  33     edit conflict resolution.    |              |
  34                                  |              |
  35                   saveRevision()-|              |
  36                                  |              |
  37                           +------v--------------v------+
  38                           |                            |
  39                           |      creation committed    |
  40                           |                            |
  41   Enables-----------------+----------------------------+
  42     wasSuccess()
  43     isUnchanged()
  44     isNew()
  45     getState()
  46     getNewRevision()
  47     etc.
  48
  49 The stateful nature of PageUpdater allows it to be used to safely perform
  50 transformations that depend on the new revision's parent revision, such as replacing
  51 sections or applying 3-way conflict resolution, while protecting against race
  52 conditions using a compare-and-swap (CAS) mechanism: after calling code used the
  53 grabParentRevision() method to access the edit's logical parent, PageUpdater
  54 remembers that revision, and ensure that that revision is still the page's current
  55 revision when performing the atomic database update for the revision's primary
  56 meta-data when saveRevision() is called. If another revision was created concurrently,
  57 saveRevision() will fail, indicating the problem with the "edit-conflict" code in the status
  58 object.
  59
  60 Typical usage for programmatic revision creation (with $page being a WikiPage as of 1.32, to be
  61 replaced by a repository service later):
  62
  63   $updater = $page->newPageUpdater( $user );
  64   $updater->setContent( SlotRecord::MAIN, $content );
  65   $updater->setRcPatrolStatus( RecentChange::PRC_PATROLLED );
  66   $newRev = $updater->saveRevision( $comment );
  67
  68 Usage with content depending on the parent revision
  69
  70   $updater = $page->newPageUpdater( $user );
  71   $parent = $updater->grabParentRevision();
  72   $content = $parent->getContent( SlotRecord::MAIN )->replaceSection( $section, $sectionContent );
  73   $updater->setContent( SlotRecord::MAIN, $content );
  74   $newRev = $updater->saveRevision( $comment, EDIT_UPDATE );
  75
  76 In both cases, all secondary updates will be triggered automatically.
  77
  78 == DerivedPageDataUpdater ==
  79 DerivedPageDataUpdater is a stateful, handle-like object that caches derived data representing
  80 a revision, and can trigger updates of cached copies of that data, e.g. in the links tables,
  81 page_props, the ParserCache, and the CDN layer.
  82
  83 DerivedPageDataUpdater is used by PageUpdater when creating new revisions, but can also
  84 be used independently when performing meta data updates during undeletion, import, or
  85 when puring a page. It's a stepping stone on the way to a more complete refactoring of WikiPage.
  86
  87 NOTE: Avoid direct usage of DerivedPageDataUpdater. In the future, we want to define interfaces
  88 for the different use cases of DerivedPageDataUpdater, particularly providing access to post-PST
  89 content and ParserOutput to callbacks during revision creation, which currently use
  90 WikiPage::prepareContentForEdit, and allowing updates to be triggered on purge, import, and
  91 undeletion, which currently use WikiPage::doEditUpdates() and Content::getSecondaryDataUpdates().
  92
  93 The primary reason for DerivedPageDataUpdater to be stateful is internal caching of state
  94 that avoids the re-generation of ParserOutput and re-application of pre-save-
  95 transformations (PST).
  96
  97 DerivedPageDataUpdater instances follow the below life cycle, defined by a number of
  98 methods:
  99
 100                        +---------------------------------------------------------------------+
 101                        |                                                                     |
 102                        |                                 new                                 |
 103                        |                                                                     |
 104                        +---------------|------------------|------------------|---------------+
 105                                        |                  |                  |
 106                  grabCurrentRevision()-|                  |                  |
 107                                        |                  |                  |
 108                            +-----------v----------+       |                  |
 109                            |                      |       |-prepareContent() |
 110                            |    knows current     |       |                  |
 111                            |                      |       |                  |
 112   Enables------------------+-----|-----|----------+       |                  |
 113     pageExisted()                |     |                  |                  |
 114     wasRedirect()                |     |-prepareContent() |                  |-prepareUpdate()
 115                                  |     |                  |                  |
 116                                  |     |    +-------------v------------+     |
 117                                  |     |    |                          |     |
 118                                  |     +---->        has content       |     |
 119                                  |          |                          |     |
 120   Enables------------------------|----------+--------------------------+     |
 121     isChange()                   |                              |            |
 122     isCreation()                 |-prepareUpdate()              |            |
 123     getSlots()                   |              prepareUpdate()-|            |
 124     getTouchedSlotRoles()        |                              |            |
 125     getCanonicalParserOutput()   |                  +-----------v------------v-----------------+
 126                                  |                  |                                          |
 127                                  +------------------>                 has revision             |
 128                                                     |                                          |
 129   Enables-------------------------------------------+------------------------|-----------------+
 130     updateParserCache()                                                      |
 131     runSecondaryDataUpdates()                                                |-doUpdates()
 132                                                                              |
 133                                                                  +-----------v---------+
 134                                                                  |                     |
 135                                                                  |     updates done    |
 136                                                                  |                     |
 137                                                                  +---------------------+
 138
 139
 140 - grabCurrentRevision() returns the logical parent revision of the target revision. It is
 141 guaranteed to always return the same revision for a given DerivedPageDataUpdater instance.
 142 If called before prepareUpdate(), this fixates the logical parent to be the page's current
 143 revision. If called for the first time after prepareUpdate(), it returns the revision
 144 passed as the 'oldrevision' option to prepareUpdate(), or, if that wasn't given, the
 145 parent of $revision parameter passed to prepareUpdate().
 146
 147 - prepareContent() is called before the new revision is created, to apply pre-save-
 148 transformation (PST) and allow subsequent access to the canonical ParserOutput of the
 149 revision. getSlots() and getCanonicalParserOutput() as well as getSecondaryDataUpdates()
 150 may be used after prepareContent() was called. Calling prepareContent() with the same
 151 parameters again has no effect. Calling it again with mismatching parameters, or calling
 152 it after prepareUpdate() was called, triggers a LogicException.
 153
 154 - prepareUpdate() is called after the new revision has been created. This may happen
 155 right after the revision was created, on the same instance on which prepareContent() was
 156 called, or later (possibly much later), on a fresh instance in a different process,
 157 due to deferred or asynchronous updates, or during import, undeletion, purging, etc.
 158 prepareUpdate() is required before a call to doUpdates(), and it also enables calls to
 159 getSlots() and getCanonicalParserOutput() as well as getSecondaryDataUpdates().
 160 Calling prepareUpdate() with the same parameters again has no effect.
 161 Calling it again with mismatching parameters, or calling it with parameters mismatching
 162 the ones prepareContent() was called with, triggers a LogicException.
 163
 164 - getSecondaryDataUpdates() returns DataUpdates that represent derived data for the revision.
 165 These may be used to update such data, e.g. in ApiPurge, RefreshLinksJob, and the refreshLinks
 166 script.
 167
 168 - doUpdates() triggers the updates defined by getSecondaryDataUpdates(), and also causes
 169 updates to cached artifacts in the ParserCache, the CDN layer, etc. This is primarily
 170 used by PageUpdater, but also by PageArchive during undeletion, and when importing
 171 revisions from XML. doUpdates() can only be called after prepareUpdate() was used to
 172 initialize the DerivedPageDataUpdater instance for a specific revision. Calling it before
 173 prepareUpdate() is called raises a LogicException.
 174
 175 A DerivedPageDataUpdater instance is intended to be re-used during different stages
 176 of complex update operations that often involve callbacks to extension code via
 177 MediaWiki's hook mechanism, or deferred or even asynchronous execution of Jobs and
 178 DeferredUpdates. Since these mechanisms typically do not provide a way to pass a
 179 DerivedPageDataUpdater directly, WikiPage::getDerivedPageDataUpdater() has to be used to
 180 obtain a DerivedPageDataUpdater for the update currently in progress - re-using the
 181 same DerivedPageDataUpdater if possible avoids re-generation of ParserOutput objects
 182 and other expensively derived artifacts.
 183
 184 This mechanism for re-using a DerivedPageDataUpdater instance without passing it directly
 185 requires a way to ensure that a given DerivedPageDataUpdater instance can actually be used
 186 in the calling code's context. For this purpose, WikiPage::getDerivedPageDataUpdater()
 187 calls the isReusableFor() method on DerivedPageDataUpdater, which ensures that the given
 188 instance is applicable to the given parameters. In other words, isReusableFor() predicts
 189 whether calling prepareContent() or prepareUpdate() with a given set of parameters will
 190 trigger a LogicException. In that case, WikiPage::getDerivedPageDataUpdater() creates a
 191 fresh DerivedPageDataUpdater instance.