Package org.wikidata.wdtk.datamodel.helpers

Class StatementUpdateBuilder

java.lang.Object
org.wikidata.wdtk.datamodel.helpers.StatementUpdateBuilder
public class StatementUpdateBuilder extends Object
Builder for incremental construction of StatementUpdate objects.
See Also:

  • Method Details

    • create

      public static StatementUpdateBuilder create()
      Creates new builder object for constructing statement update.
      Returns:
      update builder object

    • create

      public static StatementUpdateBuilder create(EntityIdValue subject)
      Creates new builder object for constructing statement update of given subject. All added or replaced statements must have the same subject ID.
      Parameters:
      subject - statement subject or null for unspecified ID
      Returns:
      update builder object
      Throws:
      IllegalArgumentException - if subject is a placeholder ID

    • forStatements

      public static StatementUpdateBuilder forStatements(Collection<Statement> statements)
      Creates new builder object for constructing update of given base revision statements. Provided statements will be used to check correctness of changes.

      Since all changes will be checked after the StatementUpdate is passed to EntityDocumentBuilder anyway, it is usually unnecessary to use this method. It is simpler to initialize the builder with create().

      Parameters:
      statements - statements from base revision of the document
      Returns:
      update builder object
      Throws:
      NullPointerException - if statements or any of its items is null
      IllegalArgumentException - if any statement is missing statement ID or statement subjects are inconsistent or placeholders

    • forStatements

      public static StatementUpdateBuilder forStatements(EntityIdValue subject, Collection<Statement> statements)
      Creates new builder object for constructing update of given base revision statements with given subject. Provided statements will be used to check correctness of changes. All provided statements as well as added or replaced statements must have the provided subject ID.

      Since all changes will be checked after the StatementUpdate is passed to EntityDocumentBuilder anyway, it is usually unnecessary to use this method. It is simpler to initialize the builder with create().

      Parameters:
      subject - statement subject or null for unspecified ID
      statements - statements from base revision of the document
      Returns:
      update builder object
      Throws:
      NullPointerException - if statements or any of its items is null
      IllegalArgumentException - if any statement is missing statement ID or statement subjects are inconsistent or placeholders

    • forStatementGroups

      public static StatementUpdateBuilder forStatementGroups(Collection<StatementGroup> groups)
      Creates new builder object for constructing update of given base revision statement groups. Provided statements will be used to check correctness of changes.

      Since all changes will be checked after the StatementUpdate is passed to EntityDocumentBuilder anyway, it is usually unnecessary to use this method. It is simpler to initialize the builder with create().

      Parameters:
      groups - statement groups from base revision of the document
      Returns:
      update builder object
      Throws:
      NullPointerException - if groups is null
      IllegalArgumentException - if any group is null or any statement is missing statement ID or statement subjects are inconsistent or placeholders

    • forStatementGroups

      public static StatementUpdateBuilder forStatementGroups(EntityIdValue subject, Collection<StatementGroup> groups)
      Creates new builder object for constructing update of given base revision statement groups with given subject. Provided statements will be used to check correctness of changes. All provided statements as well as added or replaced statements must have the provided subject ID.

      Since all changes will be checked after the StatementUpdate is passed to EntityDocumentBuilder anyway, it is usually unnecessary to use this method. It is simpler to initialize the builder with create().

      Parameters:
      subject - statement subject or null for unspecified ID
      groups - statement groups from base revision of the document
      Returns:
      update builder object
      Throws:
      NullPointerException - if groups is null
      IllegalArgumentException - if any group is null or any statement is missing statement ID or statement subjects are inconsistent or placeholders

    • add

      public StatementUpdateBuilder add(Statement statement)
      Adds statement to the entity. If statement has an ID (perhaps because it is a modified copy of another statement), its ID is stripped to ensure the statement is added and no other statement is modified.
      Parameters:
      statement - new statement to add
      Returns:
      this (fluent method)
      Throws:
      NullPointerException - if statement is null
      IllegalArgumentException - if statement's subject is inconsistent with other statements or it is a placeholder ID

    • replace

      public StatementUpdateBuilder replace(Statement statement)
      Replaces existing statement in the entity. Provided statement must have statement ID identifying statement to replace. Calling this method overrides any previous changes made to the same statement ID by this method or remove(String).

      If base revision statements were provided, existence of the statement is checked. Any attempt to replace some statement with identical statement is silently ignored, resulting in empty update.

      Parameters:
      statement - replacement for existing statement
      Returns:
      this (fluent method)
      Throws:
      NullPointerException - if statement is null
      IllegalArgumentException - if statement does not have statement ID or it is not among base revision statements (if available) or its subject is inconsistent with other statements or a placeholder ID

    • remove

      public StatementUpdateBuilder remove(String statementId)
      Removes existing statement from the entity. Calling this method overrides any previous changes made to the same statement ID by replace(Statement). Removing the same statement ID twice is silently tolerated.

      If base revision statements were provided, this method checks that statement with this ID exists in the base revision.

      Parameters:
      statementId - ID of the removed statement
      Returns:
      this (fluent method)
      Throws:
      NullPointerException - if statementId is null
      IllegalArgumentException - if statementId is empty or it is not among base revision statements (if available)

    • append

      public StatementUpdateBuilder append(StatementUpdate update)
      Replays all changes in provided update into this builder object. Changes are performed as if by calling add(Statement), replace(Statement), and remove(String) methods.
      Parameters:
      update - statement update to replay
      Returns:
      this (fluent method)
      Throws:
      NullPointerException - if update is null
      IllegalArgumentException - if updated or removed statement is not among base revision statements (if available)

    • build

      public StatementUpdate build()
      Creates new StatementUpdate object with contents of this builder object.
      Returns:
      constructed object