Package org.wikidata.wdtk.wikibaseapi

Class WikibaseDataEditor

java.lang.Object
org.wikidata.wdtk.wikibaseapi.WikibaseDataEditor
public class WikibaseDataEditor extends Object
Class that provides high-level editing functionality for Wikibase data.
Author:
Markus Kroetzsch

  • Constructor Details

    • WikibaseDataEditor

      public WikibaseDataEditor(ApiConnection connection, String siteUri)
      Creates an object to edit data via the Web API of the given ApiConnection object. The site URI is necessary to create data objects from API responses, since it is not contained in the data retrieved from the URI.
      Parameters:
      connection - ApiConnection
      siteUri - the URI identifying the site that is accessed (usually the prefix of entity URIs), e.g., "http://www.wikidata.org/entity/"

    • WikibaseDataEditor

      public WikibaseDataEditor(ApiConnection connection, String siteUri, GuidGenerator generator)
      Creates an object to edit data via the Web API of the given ApiConnection object. The site URI is necessary to create data objects from API responses, since it is not contained in the data retrieved from the URI.
      Parameters:
      connection - ApiConnection
      siteUri - the URI identifying the site that is accessed (usually the prefix of entity URIs), e.g., "http://www.wikidata.org/entity/"
      generator - the generator to use when creating fresh GUIDs for statements, snaks or references

  • Method Details

    • editAsBot

      public boolean editAsBot()
      Returns true if edits should be flagged as bot edits. See setEditAsBot(boolean) for details.
      Returns:
      whether to flag edits as bot

    • setEditAsBot

      public void setEditAsBot(boolean editAsBot)
      Switches the use of the bot parameter on or of. When set to true, the bot flag will be set for all edits. This will only have effect when logged in with a user account that is in the bot group. Bot users should set this to true in almost every case.
      Parameters:
      editAsBot -

    • getMaxLag

      public int getMaxLag()
      Returns the current value of the maxlag parameter. It specifies the number of seconds. To save actions causing any more site replication lag, this parameter can make the client wait until the replication lag is less than the specified value. In case of excessive lag, error code "maxlag" is returned upon API requests.
      Returns:
      current setting of the maxlag parameter

    • setMaxLag

      public void setMaxLag(int maxLag)
      Set the value of the maxlag parameter. If unsure, keep the default. See getMaxLag() for details.
      Parameters:
      maxLag - the new value in seconds

    • getMaxLagMaxRetries

      public int getMaxLagMaxRetries()
      Number of times we should retry if an editing action fails because the lag is too high.

    • setMaxLagMaxRetries

      public void setMaxLagMaxRetries(int retries)
      Number of times we should retry if an editing action fails because the lag is too high.

    • getMaxLagFirstWaitTime

      public int getMaxLagFirstWaitTime()
      Initial wait time in milliseconds, when an edit fails for the first time because of a high lag. This wait time is going to be multiplied by maxLagBackOffFactor for the subsequent waits.

    • setMaxLagFirstWaitTime

      public void setMaxLagFirstWaitTime(int time)
      Initial wait time in milliseconds, when an edit fails for the first time because of a high lag. This wait time is going to be multiplied by maxLagBackOffFactor for the subsequent waits.

    • getMaxLagBackOffFactor

      public double getMaxLagBackOffFactor()
      Factor by which the wait time between two maxlag retries should be multiplied at each attempt.

    • setMaxLagBackOffFactor

      public void setMaxLagBackOffFactor(double value)
      Factor by which the wait time between two maxlag retries should be multiplied at each attempt.

    • getAverageTimePerEdit

      public int getAverageTimePerEdit()
      Returns the average time that a single edit should take, measured in milliseconds. See WbEditingAction.getAverageTimePerEdit() for details.
      Returns:
      average time per edit in milliseconds

    • setAverageTimePerEdit

      public void setAverageTimePerEdit(int milliseconds)
      Sets the average time that a single edit should take, measured in milliseconds. See WbEditingAction.getAverageTimePerEdit() for details.
      Parameters:
      milliseconds - the new value in milliseconds

    • getRemainingEdits

      public int getRemainingEdits()
      Returns the number of edits that will be performed before entering simulation mode, or -1 if there is no limit on the number of edits (default). See WbEditingAction.getRemainingEdits() for details.
      Returns:
      number of remaining edits

    • setRemainingEdits

      public void setRemainingEdits(int remainingEdits)
      Sets the number of edits that this object can still perform. See WbEditingAction.setRemainingEdits(int) for details.
      Parameters:
      remainingEdits - number of edits that can still be performed, or -1 to disable this limit (default setting)

    • disableEditing

      public void disableEditing()
      Sets the remaining edits for this component to 0, so that all edits are simulated but not actually send to the API.

    • createEntityDocument

      public EntityDocument createEntityDocument(EntityDocument document, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Creates new entity document. Provided entity document must use a local item ID, such as ItemIdValue.NULL, and its revision ID must be 0.

      The newly created document is returned. It will contain the new item ID and revision ID. Note that the site IRI used in the item ID is not part of the API response. The site IRI given when constructing this object is used in its place.

      Statements in the provided document must not have IDs.

      Summary message will be prepended by an automatically generated comment. The length limit of the autocomment together with the summary is 260 characters. Everything above that limit will be cut off.

      Parameters:
      document - document that contains the data to be written
      summary - summary for the edit
      tags - string identifiers of the tags to apply to the edit, null or empty for no tags
      Returns:
      newly created item document or null for simulated edit (see disableEditing()
      Throws:
      IOException - if there was an IO problem, such as missing network connection
      MediaWikiApiErrorException - if MediaWiki API returned an error response

    • createItemDocument

      public ItemDocument createItemDocument(ItemDocument document, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Creates new item document. Provided item document must use a local item ID, such as ItemIdValue.NULL, and its revision ID must be 0.

      The newly created document is returned. It will contain the new item ID and revision ID. Note that the site IRI used in the item ID is not part of the API response. The site IRI given when constructing this object is used in its place.

      Statements in the provided document must not have IDs.

      Summary message will be prepended by an automatically generated comment. The length limit of the autocomment together with the summary is 260 characters. Everything above that limit will be cut off.

      Parameters:
      document - document that contains the data to be written
      summary - summary for the edit
      tags - string identifiers of the tags to apply to the edit, null or empty for no tags
      Returns:
      newly created item document or null for simulated edit (see disableEditing()
      Throws:
      IOException - if there was an IO problem, such as missing network connection
      MediaWikiApiErrorException - if MediaWiki API returned an error response

    • createPropertyDocument

      public PropertyDocument createPropertyDocument(PropertyDocument document, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Creates new property document. Provided property document must use a local property ID, such as PropertyIdValue.NULL, and its revision ID must be 0.

      The newly created document is returned. It will contain the new property ID and revision ID. Note that the site IRI used in the property ID is not part of the API response. The site IRI given when constructing this object is used in its place.

      Statements in the provided document must not have IDs.

      Summary message will be prepended by an automatically generated comment. The length limit of the autocomment together with the summary is 260 characters. Everything above that limit will be cut off.

      Parameters:
      document - document that contains the data to be written
      summary - summary for the edit
      tags - string identifiers of the tags to apply to the edit, null or empty for no tags
      Returns:
      newly created property document or null for simulated edit (see disableEditing()
      Throws:
      IOException - if there was an IO problem, such as missing network connection
      MediaWikiApiErrorException - if MediaWiki API returned an error response

    • createLexemeDocument

      public LexemeDocument createLexemeDocument(LexemeDocument document, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Creates new lexeme document. Provided lexeme document must use a local lexeme ID, such as LexemeIdValue.NULL, and its revision ID must be 0.

      The newly created document is returned. It will contain the new lexeme ID and revision ID. Note that the site IRI used in the lexeme ID is not part of the API response. The site IRI given when constructing this object is used in its place.

      Statements, senses, and forms in the provided document must not have IDs.

      Summary message will be prepended by an automatically generated comment. The length limit of the autocomment together with the summary is 260 characters. Everything above that limit will be cut off.

      Parameters:
      document - document that contains the data to be written
      summary - summary for the edit
      tags - string identifiers of the tags to apply to the edit, null or empty for no tags
      Returns:
      newly created lexeme document or null for simulated edit (see disableEditing()
      Throws:
      IOException - if there was an IO problem, such as missing network connection
      MediaWikiApiErrorException - if MediaWiki API returned an error response

    • editItemDocument

      @Deprecated public ItemDocument editItemDocument(ItemDocument itemDocument, boolean clear, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Deprecated.
      Use editEntityDocument(EntityUpdate, boolean, String, List) instead. Writes the data for the given item document with the summary message as given. Optionally, the existing data is cleared (deleted).

      The id of the given item document is used to specify which item document should be changed. The site IRI will be ignored for this.

      The revision id of the given item document is used to specify the base revision, enabling the API to detect edit conflicts. The value 0 can be used to omit this. It is strongly recommended to give a revision id when making edits where the outcome depends on the previous state of the data (i.e., any edit that does not use "clear").

      If the data is not cleared, then the existing data will largely be preserved. Statements with empty ids will be added without checking if they exist already; statements with (valid) ids will replace any existing statements with these ids or just be added if there are none. Labels, descriptions, and aliases will be preserved for all languages for which no data is given at all. For aliases this means that writing one alias in a language will overwrite all aliases in this language, so some care is needed.

      Parameters:
      itemDocument - the document that contains the data to be written
      clear - if true, the existing data will be replaced by the given data; if false, the given data will be added to the existing data, overwriting only parts that are set to new values
      summary - summary for the edit; will be prepended by an automatically generated comment; the length limit of the autocomment together with the summary is 260 characters: everything above that limit will be cut off
      tags - string identifiers of the tags to apply to the edit.
      Returns:
      the modified item document, or null if there was an error
      Throws:
      IOException - if there was an IO problem, such as missing network connection
      MediaWikiApiErrorException

    • editEntityDocument

      public EditingResult editEntityDocument(EntityUpdate update, boolean clear, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Updates EntityDocument entity. ID of the entity to update is taken from the update object. Its site IRI is ignored. No action is taken if the update is empty.

      If the update object references base revision of the document, its revision ID is used to specify the base revision in the API request, enabling the API to detect edit conflicts. It is strongly recommended to specify base revision document in the update object.

      Summary message will be prepended by an automatically generated comment. The length limit of the autocomment together with the summary is 260 characters. Everything above that limit will be cut off.

      Parameters:
      update - collection of changes to be written
      clear - if set to true, existing entity data will be removed and the update will be applied to empty entity
      summary - summary for the edit
      tags - string identifiers of the tags to apply to the edit, null or empty for no tags
      Throws:
      IOException - if there was an IO problem, such as missing network connection
      MediaWikiApiErrorException - if MediaWiki API returned an error response

    • editPropertyDocument

      @Deprecated public PropertyDocument editPropertyDocument(PropertyDocument propertyDocument, boolean clear, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Deprecated.
      Use editEntityDocument(EntityUpdate, boolean, String, List) instead. Writes the data for the given property document with the summary message as given. Optionally, the existing data is cleared (deleted).

      The id of the given property document is used to specify which property document should be changed. The site IRI will be ignored for this.

      The revision id of the given property document is used to specify the base revision, enabling the API to detect edit conflicts. The value 0 can be used to omit this. It is strongly recommended to give a revision id when making edits where the outcome depends on the previous state of the data (i.e., any edit that does not use "clear").

      If the data is not cleared, then the existing data will largely be preserved. Statements with empty ids will be added without checking if they exist already; statements with (valid) ids will replace any existing statements with these ids or just be added if there are none. Labels, descriptions, and aliases will be preserved for all languages for which no data is given at all. For aliases this means that writing one alias in a language will overwrite all aliases in this language, so some care is needed.

      Parameters:
      propertyDocument - the document that contains the data to be written
      clear - if true, the existing data will be replaced by the given data; if false, the given data will be added to the existing data, overwriting only parts that are set to new values
      summary - summary for the edit; will be prepended by an automatically generated comment; the length limit of the autocomment together with the summary is 260 characters: everything above that limit will be cut off
      tags - string identifiers of the tags to apply to the edit.
      Returns:
      the modified property document, or null if there was an error
      Throws:
      IOException - if there was an IO problem, such as missing network connection
      MediaWikiApiErrorException

    • editMediaInfoDocument

      @Deprecated public MediaInfoDocument editMediaInfoDocument(MediaInfoDocument mediaInfoDocument, boolean clear, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Deprecated.
      Use editEntityDocument(EntityUpdate, boolean, String, List) instead. Writes the data for the given media info document with the summary message as given. Optionally, the existing data is cleared (deleted). It creates the media info if needed.

      The id of the given media info document is used to specify which media info document should be changed or created. The site IRI will be ignored for this.

      The revision id of the given media info document is used to specify the base revision, enabling the API to detect edit conflicts. The value 0 can be used to omit this. It is strongly recommended to give a revision id when making edits where the outcome depends on the previous state of the data (i.e., any edit that does not use "clear").

      If the data is not cleared, then the existing data will largely be preserved. Statements with empty ids will be added without checking if they exist already; statements with (valid) ids will replace any existing statements with these ids or just be added if there are none. Labels will be preserved for all languages for which no data is given at all. For aliases this means that writing one alias in

      Parameters:
      mediaInfoDocument - the document that contains the data to be written
      clear - if true, the existing data will be replaced by the given data; if false, the given data will be added to the existing data, overwriting only parts that are set to new values
      summary - summary for the edit; will be prepended by an automatically generated comment; the length limit of the autocomment together with the summary is 260 characters: everything above that limit will be cut off
      tags - string identifiers of the tags to apply to the edit.
      Returns:
      the modified media info document, or null if there was an error
      Throws:
      IOException - if there was an IO problem, such as missing network connection
      MediaWikiApiErrorException

    • updateStatements

      @Deprecated public ItemDocument updateStatements(ItemIdValue itemIdValue, List<Statement> addStatements, List<Statement> deleteStatements, String summary, List<String> tags) throws MediaWikiApiErrorException, IOException
      Deprecated.
      Use editEntityDocument(EntityUpdate, boolean, String, List) instead. Updates the statements of the item document identified by the given item id. The updates are computed with respect to the current data found online, making sure that no redundant deletions or duplicate insertions happen. The references of duplicate statements will be merged.
      Parameters:
      itemIdValue - id of the document to be updated
      addStatements - the list of statements to be added or updated; statements with empty statement id will be added; statements with non-empty statement id will be updated (if such a statement exists)
      deleteStatements - the list of statements to be deleted; statements will only be deleted if they are present in the current document (in exactly the same form, with the same id)
      summary - summary for the edit; will be prepended by an automatically generated comment; the length limit of the autocomment together with the summary is 260 characters: everything above that limit will be cut off
      tags - string identifiers of the tags to apply to the edit.
      Returns:
      the updated document
      Throws:
      MediaWikiApiErrorException - if the API returns errors
      IOException - if there are IO problems, such as missing network connection

    • updateTermsStatements

      @Deprecated public ItemDocument updateTermsStatements(ItemIdValue itemIdValue, List<MonolingualTextValue> addLabels, List<MonolingualTextValue> addDescriptions, List<MonolingualTextValue> addAliases, List<MonolingualTextValue> deleteAliases, List<Statement> addStatements, List<Statement> deleteStatements, String summary, List<String> tags) throws MediaWikiApiErrorException, IOException
      Deprecated.
      Use editEntityDocument(EntityUpdate, boolean, String, List) instead. Updates the terms and statements of the item document identified by the given item id. The updates are computed with respect to the current data found online, making sure that no redundant deletions or duplicate insertions happen. The references of duplicate statements will be merged. The labels and aliases in a given language are kept distinct.
      Parameters:
      itemIdValue - id of the document to be updated
      addLabels - labels to be set on the item. They will overwrite existing values in the same language.
      addDescriptions - description to be set on the item. They will overwrite existing values in the same language.
      addAliases - aliases to be added. Existing aliases will be kept.
      deleteAliases - aliases to be deleted.
      addStatements - the list of statements to be added or updated; statements with empty statement id will be added; statements with non-empty statement id will be updated (if such a statement exists)
      deleteStatements - the list of statements to be deleted; statements will only be deleted if they are present in the current document (in exactly the same form, with the same id)
      summary - summary for the edit; will be prepended by an automatically generated comment; the length limit of the autocomment together with the summary is 260 characters: everything above that limit will be cut off
      tags - string identifiers of the tags to apply to the edit.
      Returns:
      the updated document
      Throws:
      MediaWikiApiErrorException - if the API returns errors
      IOException - if there are any IO errors, such as missing network connection

    • updateStatements

      @Deprecated public PropertyDocument updateStatements(PropertyIdValue propertyIdValue, List<Statement> addStatements, List<Statement> deleteStatements, String summary, List<String> tags) throws MediaWikiApiErrorException, IOException
      Deprecated.
      Use editEntityDocument(EntityUpdate, boolean, String, List) instead. Updates the statements of the property document identified by the given property id. The computation of updates is the same as for updateStatements(ItemIdValue, List, List, String, List).
      Parameters:
      propertyIdValue - id of the document to be updated
      addStatements - the list of statements to be added or updated; statements with empty statement id will be added; statements with non-empty statement id will be updated (if such a statement exists)
      deleteStatements - the list of statements to be deleted; statements will only be deleted if they are present in the current document (in exactly the same form, with the same id)
      summary - summary for the edit; will be prepended by an automatically generated comment; the length limit of the autocomment together with the summary is 260 characters: everything above that limit will be cut off
      tags - string identifiers of the tags to apply to the edit.
      Returns:
      the updated document
      Throws:
      MediaWikiApiErrorException - if the API returns errors
      IOException - if there are IO problems, such as missing network connection

    • updateStatements

      @Deprecated public <T extends StatementDocument> T updateStatements(T currentDocument, List<Statement> addStatements, List<Statement> deleteStatements, String summary, List<String> tags) throws MediaWikiApiErrorException, IOException
      Deprecated.
      Use editEntityDocument(EntityUpdate, boolean, String, List) instead. Updates statements of the given document. The document should be the current revision of the data that is to be updated. The updates are computed with respect to the data found in the document, making sure that no redundant deletions or duplicate insertions happen. The references of duplicate statements will be merged.

      The generic type T of this method must be a general interface such as ItemDocument, PropertyDocument, or StatementDocument. Specific implementations of these interfaces are not permitted.

      Parameters:
      currentDocument - the document that is to be updated; needs to have a correct revision id and entity id
      addStatements - the list of statements to be added or updated; statements with empty statement id will be added; statements with non-empty statement id will be updated (if such a statement exists)
      deleteStatements - the list of statements to be deleted; statements will only be deleted if they are present in the current document (in exactly the same form, with the same id)
      summary - summary for the edit; will be prepended by an automatically generated comment; the length limit of the autocomment together with the summary is 260 characters: everything above that limit will be cut off
      tags - string identifiers of the tags to apply to the edit. Ignored if null or empty.
      Returns:
      the updated document
      Throws:
      MediaWikiApiErrorException - if the API returns errors
      IOException - if there are IO problems, such as missing network connection

    • updateTermsStatements

      @Deprecated public <T extends TermedStatementDocument> T updateTermsStatements(T currentDocument, List<MonolingualTextValue> addLabels, List<MonolingualTextValue> addDescriptions, List<MonolingualTextValue> addAliases, List<MonolingualTextValue> deleteAliases, List<Statement> addStatements, List<Statement> deleteStatements, String summary, List<String> tags) throws MediaWikiApiErrorException, IOException
      Deprecated.
      Use editEntityDocument(EntityUpdate, boolean, String, List) instead. Updates the terms and statements of the current document. The updates are computed with respect to the current data in the document, making sure that no redundant deletions or duplicate insertions happen. The references of duplicate statements will be merged. The labels and aliases in a given language are kept distinct.
      Parameters:
      currentDocument - the document to be updated; needs to have a correct revision id and entity id
      addLabels - labels to be set on the item. They will overwrite existing values in the same language.
      addDescriptions - description to be set on the item. They will overwrite existing values in the same language.
      addAliases - aliases to be added. Existing aliases will be kept.
      deleteAliases - aliases to be deleted.
      addStatements - the list of statements to be added or updated; statements with empty statement id will be added; statements with non-empty statement id will be updated (if such a statement exists)
      deleteStatements - the list of statements to be deleted; statements will only be deleted if they are present in the current document (in exactly the same form, with the same id)
      summary - summary for the edit; will be prepended by an automatically generated comment; the length limit of the autocomment together with the summary is 260 characters: everything above that limit will be cut off
      tags - string identifiers of the tags to apply to the edit. Ignored if null or empty.
      Returns:
      the updated document
      Throws:
      MediaWikiApiErrorException - if the API returns errors
      IOException - if there are any IO errors, such as missing network connection

    • nullEdit

      public void nullEdit(EntityIdValue entityId) throws IOException, MediaWikiApiErrorException
      Performs a null edit on an entity. This has some effects on Wikibase, such as refreshing the labels of the referred items in the UI.
      Parameters:
      entityId - the document to perform a null edit on
      Throws:
      MediaWikiApiErrorException - if the API returns errors
      IOException - if there are any IO errors, such as missing network connection

    • nullEdit

      @Deprecated public <T extends StatementDocument> void nullEdit(ItemIdValue itemId) throws IOException, MediaWikiApiErrorException
      Deprecated.
      Use nullEdit(EntityIdValue) instead. Performs a null edit on an item. This has some effects on Wikibase, such as refreshing the labels of the referred items in the UI.
      Parameters:
      itemId - the document to perform a null edit on
      Throws:
      MediaWikiApiErrorException - if the API returns errors
      IOException - if there are any IO errors, such as missing network connection

    • nullEdit

      @Deprecated public <T extends StatementDocument> void nullEdit(PropertyIdValue propertyId) throws IOException, MediaWikiApiErrorException
      Deprecated.
      Use nullEdit(EntityIdValue) instead. Performs a null edit on a property. This has some effects on Wikibase, such as refreshing the labels of the referred items in the UI.
      Parameters:
      propertyId - the document to perform a null edit on
      Throws:
      MediaWikiApiErrorException - if the API returns errors
      IOException - if there are any IO errors, such as missing network connection

    • nullEdit

      public <T extends EntityDocument> T nullEdit(T currentDocument) throws IOException, MediaWikiApiErrorException
      Performs a null edit on an entity. This has some effects on Wikibase, such as refreshing the labels of the referred items in the UI.
      Parameters:
      currentDocument - the document to perform a null edit on
      Returns:
      new version of the document returned by Wikibase API
      Throws:
      MediaWikiApiErrorException - if the API returns errors
      IOException - if there are any IO errors, such as missing network connection

    • getRevisionIdFromResponse

      protected long getRevisionIdFromResponse(com.fasterxml.jackson.databind.JsonNode response) throws com.fasterxml.jackson.core.JsonProcessingException
      Extracts the last revision id from the JSON response returned by the API after an edit
      Parameters:
      response - the response as returned by Mediawiki
      Returns:
      the new revision id of the edited entity
      Throws:
      com.fasterxml.jackson.core.JsonProcessingException