Package org.wikidata.wdtk.wikibaseapi

Class WbEditingAction

java.lang.Object
org.wikidata.wdtk.wikibaseapi.WbEditingAction
public class WbEditingAction extends Object
Java implementation for the wbeditentity API action.
Author:
Michael Guenther, Markus Kroetzsch, Antonin Delpeuch

  • Constructor Details

    • WbEditingAction

      public WbEditingAction(ApiConnection connection, String siteIri)
      Creates an object to modify data on a Wikibase site. The API is used to request the changes. The site URI is necessary since it is not contained in the data retrieved from the API.
      Parameters:
      connection - ApiConnection Object to send the requests
      siteIri - the URI identifying the site that is accessed (usually the prefix of entity URIs), e.g., "http://www.wikidata.org/entity/"

  • Method Details

    • 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

    • 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).
      Returns:
      number of remaining edits

    • setRemainingEdits

      public void setRemainingEdits(int remainingEdits)
      Sets the number of edits that this object can still perform. Thereafter, edits will only be prepared but not actually performed in the Web API. This function is useful to do a defined number of test edits. If this number is set to 0, then no edits will be performed. If it is set to -1 (or any other negative number), then there is no limit on the edits performed.
      Parameters:
      remainingEdits - number of edits that can still be performed, or -1 to disable this limit (default setting)

    • getAverageTimePerEdit

      public int getAverageTimePerEdit()
      Returns the average time in milliseconds that one edit will take. This time is enforced to avoid overloading the site with too many edits, and also to throttle the rate of editing (which is useful to stop a bot in case of errors). Individual edits can be faster than this, but if several consecutive edits are above this rate, the program will pause until the expected speed is reached again. The delay is based on real system time. This means that it will only wait as long as necessary. If your program takes time between edits for other reasons, there will be no additional delay caused by this feature.
      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 getAverageTimePerEdit() for details.
      Parameters:
      milliseconds - the new value in milliseconds

    • wbEditEntity

      public EntityDocument wbEditEntity(String id, String site, String title, String newEntity, String data, boolean clear, boolean bot, long baserevid, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Executes the API action "wbeditentity" for the given parameters. Created or modified items are returned as a result. In particular, this is relevant to find out about the id assigned to a newly created entity.

      Unless the parameter clear is true, data of existing entities will be modified or added, but not deleted. For labels, descriptions, and aliases, this happens by language. In particular, if an item has English and German aliases, and an edit action writes a new English alias, then this new alias will replace all previously existing English aliases, while the German aliases will remain untouched. In contrast, adding statements for a certain property will not delete existing statements of this property. In fact, it is even possible to create many copies of the exact same statement. A special JSON syntax exists for deleting specific statements.

      See the online API documentation for further information.

      TODO: There is currently no way to delete the label, description, or aliases for a particular language without clearing all data. Empty strings are not accepted. One might achieve this by adapting the JSON serialization to produce null values for such strings, and for alias lists that contain only such strings.

      Parameters:
      id - the id of the entity to be edited; if used, the site and title parameters must be null
      site - when selecting an entity by title, the site key for the title, e.g., "enwiki"; if used, title must also be given but id must be null
      title - string used to select an entity by title; if used, site must also be given but id must be null
      newEntity - used for creating a new entity of a given type; the value indicates the intended entity type; possible values include "item" and "property"; if used, the parameters id, site, and title must be null
      data - JSON representation of the data that is to be written; this is a mandatory parameter
      clear - if true, existing data will be cleared (deleted) before writing the new data
      bot - if true, edits will be flagged as "bot edits" provided that the logged in user is in the bot group; for regular users, the flag will just be ignored
      baserevid - the revision of the data that the edit refers to or 0 if this should not be submitted; when used, the site will ensure that no edit has happened since this revision to detect edit conflicts; it is recommended to use this whenever in all operations where the outcome depends on the state of the online data
      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.
      Returns:
      the JSON response as returned by the API
      Throws:
      IOException - if there was an IO problem. such as missing network connection
      MediaWikiApiErrorException - if the API returns an error

    • wbSetLabel

      public com.fasterxml.jackson.databind.JsonNode wbSetLabel(String id, String site, String title, String newEntity, String language, String value, boolean bot, long baserevid, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Executes the API action "wbsetlabel" for the given parameters.
      Parameters:
      id - the id of the entity to be edited; if used, the site and title parameters must be null
      site - when selecting an entity by title, the site key for the title, e.g., "enwiki"; if used, title must also be given but id must be null
      title - string used to select an entity by title; if used, site must also be given but id must be null
      newEntity - used for creating a new entity of a given type; the value indicates the intended entity type; possible values include "item" and "property"; if used, the parameters id, site, and title must be null
      language - the language code for the label
      value - the value of the label to set. Set it to null to remove the label.
      bot - if true, edits will be flagged as "bot edits" provided that the logged in user is in the bot group; for regular users, the flag will just be ignored
      baserevid - the revision of the data that the edit refers to or 0 if this should not be submitted; when used, the site will ensure that no edit has happened since this revision to detect edit conflicts; it is recommended to use this whenever in all operations where the outcome depends on the state of the online data
      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.
      Returns:
      the label as returned by the API
      Throws:
      IOException - if there was an IO problem. such as missing network connection
      MediaWikiApiErrorException - if the API returns an error
      IOException
      MediaWikiApiErrorException

    • wbSetDescription

      public com.fasterxml.jackson.databind.JsonNode wbSetDescription(String id, String site, String title, String newEntity, String language, String value, boolean bot, long baserevid, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Executes the API action "wbsetlabel" for the given parameters.
      Parameters:
      id - the id of the entity to be edited; if used, the site and title parameters must be null
      site - when selecting an entity by title, the site key for the title, e.g., "enwiki"; if used, title must also be given but id must be null
      title - string used to select an entity by title; if used, site must also be given but id must be null
      newEntity - used for creating a new entity of a given type; the value indicates the intended entity type; possible values include "item" and "property"; if used, the parameters id, site, and title must be null
      language - the language code for the label
      value - the value of the label to set. Set it to null to remove the label.
      bot - if true, edits will be flagged as "bot edits" provided that the logged in user is in the bot group; for regular users, the flag will just be ignored
      baserevid - the revision of the data that the edit refers to or 0 if this should not be submitted; when used, the site will ensure that no edit has happened since this revision to detect edit conflicts; it is recommended to use this whenever in all operations where the outcome depends on the state of the online data
      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.
      Returns:
      the JSON response from the API
      Throws:
      IOException - if there was an IO problem. such as missing network connection
      MediaWikiApiErrorException - if the API returns an error
      IOException
      MediaWikiApiErrorException

    • wbSetAliases

      public com.fasterxml.jackson.databind.JsonNode wbSetAliases(String id, String site, String title, String newEntity, String language, List<String> add, List<String> remove, List<String> set, boolean bot, long baserevid, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Executes the API action "wbsetaliases" for the given parameters.
      Parameters:
      id - the id of the entity to be edited; if used, the site and title parameters must be null
      site - when selecting an entity by title, the site key for the title, e.g., "enwiki"; if used, title must also be given but id must be null
      title - string used to select an entity by title; if used, site must also be given but id must be null
      newEntity - used for creating a new entity of a given type; the value indicates the intended entity type; possible values include "item" and "property"; if used, the parameters id, site, and title must be null
      language - the language code for the label
      add - the values of the aliases to add. They will be merged with the existing aliases. This parameter cannot be used in conjunction with "set".
      remove - the values of the aliases to remove. Other aliases will be retained. This parameter cannot be used in conjunction with "set".
      set - the values of the aliases to set. This will erase any existing aliases in this language and replace them by the given list.
      bot - if true, edits will be flagged as "bot edits" provided that the logged in user is in the bot group; for regular users, the flag will just be ignored
      baserevid - the revision of the data that the edit refers to or 0 if this should not be submitted; when used, the site will ensure that no edit has happened since this revision to detect edit conflicts; it is recommended to use this whenever in all operations where the outcome depends on the state of the online data
      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.
      Returns:
      the JSON response from the API
      Throws:
      IOException - if there was an IO problem. such as missing network connection
      MediaWikiApiErrorException - if the API returns an error
      IOException
      MediaWikiApiErrorException

    • wbSetClaim

      public com.fasterxml.jackson.databind.JsonNode wbSetClaim(String statement, boolean bot, long baserevid, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Executes the API action "wbsetclaim" for the given parameters.
      Parameters:
      statement - the JSON serialization of claim to add or delete.
      bot - if true, edits will be flagged as "bot edits" provided that the logged in user is in the bot group; for regular users, the flag will just be ignored
      baserevid - the revision of the data that the edit refers to or 0 if this should not be submitted; when used, the site will ensure that no edit has happened since this revision to detect edit conflicts; it is recommended to use this whenever in all operations where the outcome depends on the state of the online data
      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.
      Returns:
      the JSON response from the API
      Throws:
      IOException - if there was an IO problem. such as missing network connection
      MediaWikiApiErrorException - if the API returns an error
      IOException
      MediaWikiApiErrorException

    • wbRemoveClaims

      public com.fasterxml.jackson.databind.JsonNode wbRemoveClaims(List<String> statementIds, boolean bot, long baserevid, String summary, List<String> tags) throws IOException, MediaWikiApiErrorException
      Executes the API action "wbremoveclaims" for the given parameters.
      Parameters:
      statementIds - the statement ids to delete
      bot - if true, edits will be flagged as "bot edits" provided that the logged in user is in the bot group; for regular users, the flag will just be ignored
      baserevid - the revision of the data that the edit refers to or 0 if this should not be submitted; when used, the site will ensure that no edit has happened since this revision to detect edit conflicts; it is recommended to use this whenever in all operations where the outcome depends on the state of the online data
      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.
      Returns:
      the JSON response from the API
      Throws:
      IOException - if there was an IO problem. such as missing network connection
      MediaWikiApiErrorException - if the API returns an error
      IOException
      MediaWikiApiErrorException

    • getEntityDocumentFromResponse

      protected EntityDocument getEntityDocumentFromResponse(com.fasterxml.jackson.databind.JsonNode root) throws IOException
      TODO: TO BE REFACTORED
      Parameters:
      root -
      Returns:
      Throws:
      IOException

    • 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.

    • getCurrentLag

      public double getCurrentLag() throws IOException, MediaWikiApiErrorException
      Retrieves the current lag from the target site, by making an API call.
      Throws:
      MediaWikiApiErrorException - when an unexpected MediaWiki API error happened (not the spurious one normally returned by MediaWiki when retrieving lag).
      IOException - when communication with the server failed.