eu.mais_h.mathsync.Summary Maven / Gradle / Ivy

Go to download
package eu.mais_h.mathsync;

import java.util.Iterator;

/**
 * Represents summarized data.
 *
 * Note that instances must be immutable.
 */
public interface Summary {

  /**
   * Adds an item to the summary.
   *
   * When both summaries can be {@link #toDifference() viewed as a difference}:
   * 

   *   if the item is in the removed set of that summary, it is in none of the resulting summary difference sets
   *   if the item is in none of the difference sets of that summary, it is in the added set of the resulting difference
   *   if the item is in the added set of that summary, the resulting summary may be impossible to decipher
   * 
   * 
   *
   * @param item the item to add.
   * @return a new summary with the item being included.
   */
  Summary plus(byte[] item);

  /**
   * Adds several items to the summary.
   *
   * Equivalent to repeatedly calling {@link #plus(byte[])} for each element, but this
   * method can do optimizations for batch updates.
   *
   * @param items the items to add.
   * @return a new summary with the items being included.
   */
  Summary plus(Iterator items);

  /**
   * Removes an item to the summary.
   *
   * When both summaries can be {@link #toDifference() viewed as a difference}:
   * 

   *   if the item is in the added set of that summary, it is in none of the resulting summary difference sets
   *   if the item is in none of the difference sets of that summary, it is in the removed set of the resulting difference
   *   if the item is in the removed set of that summary, the resulting summary may be impossible to decipher
   * 
   * 
   *
   * @param item the item to remove.
   * @return a new summary with the item being removed.
   */
  Summary minus(byte[] item);

  /**
   * Removes several items to the summary.
   *
   * Equivalent to repeatedly calling {@link #minus(byte[])} for each element, but this
   * method can do optimizations for batch updates.
   *
   * @param items the items to remove.
   * @return a new summary with the items being removed.
   */
  Summary minus(Iterator items);

  /**
   * Retrieves a JSON view of the summary.
   *
   * @return a JSON view of the summary.
   */
  String toJSON();

  /**
   * Retrieves a view of the summary as a difference.
   *
   * @return a difference view of the summary or null if it cannot be resolved with the information it contains.
   */
  Difference toDifference();
}