org.chronos.chronodb.internal.api.TemporalDataMatrix Maven / Gradle / Ivy
Show all versions of org.chronos.chronodb.api Show documentation
package org.chronos.chronodb.internal.api;
import org.chronos.chronodb.api.Order;
import org.chronos.chronodb.api.key.TemporalKey;
import org.chronos.chronodb.internal.api.stream.CloseableIterator;
import org.chronos.chronodb.internal.impl.temporal.UnqualifiedTemporalEntry;
import org.chronos.chronodb.internal.impl.temporal.UnqualifiedTemporalKey;
import org.chronos.chronodb.internal.util.KeySetModifications;
import java.util.*;
/**
* A {@link TemporalDataMatrix} is a structured container for temporal key-value pairs.
*
*
* Such a matrix is defined over a set of timestamps T, in combination with a set of keys K. A temporal
* data matrix D is then defined as D = T x K. The matrix can be visualized as follows:
*
*
* K
*
* ^
* |
* |
* +----+----+----+----+----+
* c | | V2 | | | |
* +----+----+----+----+----+
* b | | | V4 | | X |
* +----+----+----+----+----+
* a | V1 | | V3 | | |
* +----+----+----+----+----+---> T
* 1 2 3 4 5
*
*
* In the example above, the following inserts have been applied:
*
* - a->V1 at T = 1
*
- c->v2 at T = 2
*
- a->v3, b-> v4 at T = 3
*
- b->deleted at T = 5
*
*
* Each entry in such a matrix D has a certain validity range on the T axis. For example, the entry "a->V1" is valid in
* range [1;3[, while "b->V4" is valid in [3;5[. In general, each entry is valid from (including) the timestamp at which
* it was inserted, up to the timestamp where the next insert occurs (exclusive).
*
* @author [email protected] -- Initial Contribution and API
*/
public interface TemporalDataMatrix {
// =================================================================================================================
// METADATA
// =================================================================================================================
/**
* Returns the name of the keyspace that is represented by this matrix.
*
* @return The keyspace. Never null.
*/
public String getKeyspace();
/**
* Returns the timestamp at which this matrix was created.
*
* @return The creation timestamp. Never negative.
*/
public long getCreationTimestamp();
// =================================================================================================================
// QUERIES
// =================================================================================================================
/**
* Returns the value for the given key at the given timestamp together with the time range in which it is valid.
*
* @param timestamp The timestamp at which to get the value for the given key. Must not be negative.
* @param key The key to get the value for. Must not be null.
* @return A ranged result. The result object itself is guaranteed to be non-null. Contains the
* {@linkplain GetResult#getValue() value} for the given key at the given timestamp, or contains a
* null-{@linkplain GetResult#getValue() value} if the key does not exist in this matrix at the
* given timestamp. The {@linkplain GetResult#getPeriod() range} of the returned object represents the
* period in which the given key is bound to the returned value.
*/
public GetResult get(final long timestamp, final String key);
/**
* Returns the history of the given key, i.e. all timestamps at which the given key changed its value due to a
* commit.
*
* @param key The key to get the commit timestamps for. Must not be null.
* @param lowerBound The (inclusive) lower bound of the timestamp range to search in. Must not be negative. Must be less than or equal to upperBound.
* @param upperBound The (inclusive) upper bound of the timestamp range to search in. Must not be negative. Must be greater than or equal to the lowerBound.
* @param order The desired ordering of the result iterator. Must not be null.
* @return An iterator over all commit timestamps on the given key, up to the given maximum timestamp. May be empty,
* but never null.
*/
public Iterator history(final String key, long lowerBound, long upperBound, Order order);
/**
* Returns an iterator over all entries in this matrix.
*
* @param minTimestamp The minimum timestamp to include. Only entries with timestamps greater than or equal to this timestamp
* will be considered. Must not be negative. Must be less than or equal to maxTimestamp.
* @param maxTimestamp The maximum timestamp to include. Only entries with timestamps less than or equal to this timestamp
* will be considered. Must not be negative. Must be greater than or equal to minTimestamp.
* @return An iterator over all entries up to the given timestamp. May be empty, but never null.
*/
public CloseableIterator allEntriesIterator(long minTimestamp, long maxTimestamp);
/**
* Returns the timestamp at which the last (latest) commit has happened on the given key.
*
* @param key The key in question. Must not be null.
* @return The latest commit timestamp, or a negative value if there has never been a commit to this key in this
* matrix.
*/
public default long lastCommitTimestamp(String key){
return this.lastCommitTimestamp(key, System.currentTimeMillis());
}
/**
* Returns the last (highest) modification timestamp of the given key which is less than or equal to the given upperBound.
*
* @param key The key to get the last modification timestamp for. Must not be null.
* @param upperBound The maximum change timestamp to consider (inclusive).
* @return The highest modification timestamp on the given key which is less than or equal to the given upper bound, or -1 to indicate that the key has not existed up to this point.
*/
public long lastCommitTimestamp(String key, long upperBound);
/**
* Returns the {@link TemporalKey temporal keys} that were modified in the given time range.
*
* @param timestampLowerBound The lower bound on the timestamp to search for (inclusive). Must not be negative. Must be less than or
* equal to the upper bound.
* @param timestampUpperBound The upper bound on the timestamp to search for (inclusive). Must not be negative. Must be larger than
* or equal to the lower bound.
* @return An iterator over the temporal keys that were modified in the given time range. May be empty, but never
* null.
* @see #getCommitTimestampsBetween(long, long)
*/
public Iterator getModificationsBetween(long timestampLowerBound, long timestampUpperBound);
/**
* Returns the timestamps at which actual commits have taken place in the given time range.
*
* @param timestampLowerBound The lower bound on the timestamp to search for (inclusive). Must not be negative. Must be less than or
* equal to the upper bound.
* @param timestampUpperBound The upper bound on the timestamp to search for (inclusive). Must not be negative. Must be larger than
* or equal to the lower bound.
* @return An iterator over the commit timestamps in the given time range. May be empty, but never null
* .
* @see #getModificationsBetween(long, long)
*/
public Iterator getCommitTimestampsBetween(long timestampLowerBound, long timestampUpperBound);
/**
* Returns an iterator over the keys which changed their value at the given commit timestamp.
*
* @param commitTimestamp The commit timestamp to analyze. Must exactly match a commit timestamp in the history, otherwise the
* resulting iterator will be empty. Must not be negative.
* @return An iterator over the keys which changed in this matrix at the commit with the given timestamp. Never
* null. Will be empty if there have been no changes in the given keyspace at the given commit,
* if no commit has taken place at the specified timestamp, or a keyspace with the given name did not exist
* at that timestamp.
*/
public Iterator getChangedKeysAtCommit(long commitTimestamp);
/**
* Returns the modifications to the keyset performed in this matrix, up to the given timestamp.
*
* @param timestamp The timestamp for which to retrieve the modifications. Must not be negative. Must be smaller than the
* timestamp of the latest change.
* @return the keyset modifications. May be empty, but never null.
*/
public KeySetModifications keySetModifications(long timestamp);
/**
* Returns the total number of entries in this matrix.
*
*
* For chunked backends, this will return the size of the head chunk.
*
*
* @return The total number of entries. Never negative.
*/
public long size();
// =================================================================================================================
// CONTENT MODIFICATION
// =================================================================================================================
/**
* Adds the given contents to this matrix, at the given timestamp.
*
* @param timestamp The timestamp at which to add the given contents to this matrix. Must not be negative.
* @param contents The key-value pairs to add, as a map. Must not be null. If the map is empty, this method
* is a no-op and returns immediately.
*/
public void put(final long timestamp, final Map contents);
/**
* Inserts the given set of entries into this matrix.
*
* @param entries The entries to insert. Must not be null. If the set is empty, this method is a no-op and
* returns immediately.
* @param force Force the insertion of the entries, bypassing safety checks. Use true to force the
* insertion.
*/
public void insertEntries(Set entries, boolean force);
/**
* Performs a rollback of the contents of this matrix to the given timestamp.
*
*
* Any entries which have been inserted after the given timestamp will be removed during the process.
*
* @param timestamp The timestamp to roll back to. Must not be negative.
*/
public void rollback(long timestamp);
// =================================================================================================================
// DATEBACK OPERATIONS
// =================================================================================================================
/**
* Purges the entry at the given key and timestamp from this matrix.
*
* @param key The key of the entry to purge. Must not be null.
* @param timestamp The timestamp of the entry to purge (exact match). Must not be negative.
* @return true if the entry was purged successfully, or false if there was no entry to
* purge at the given coordinates.
*/
public default boolean purgeEntry(String key, long timestamp) {
return this.purgeEntries(Collections.singleton(UnqualifiedTemporalKey.create(key, timestamp))) > 0;
}
/**
* Purges the entries at the given coordinates from this matrix.
*
* @param keys The keys to purge. Must not be null, may be empty.
* @return The number of successfully purged entries. Keys which did not exist do not count towards this result.
*/
public int purgeEntries(Set keys);
/**
* Purges the given key from the matrix on all timestamps.
*
* @param key The key to purge. Must not be null.
* @return The timestamps at which the key was removed. May be empty, but never null.
*/
public Collection purgeKey(String key);
/**
* Purges all entries in the matrix that reside in the given time range, eliminating them completely from the history.
*
* @param purgeRangeStart The lower bound of the range to purge entries from (inclusive). Must not be negative, must not be
* larger than purgeRangeEnd.
* @param purgeRangeEnd The upper bound of the range to purge entries from (inclusive). Must not be negative, must be greater
* than or equal to purgeRangeStart.
* @return The set of coordinates which have been affected by the operation. Never null, may be empty.
*/
public Set purgeAllEntriesInTimeRange(long purgeRangeStart, long purgeRangeEnd);
/**
* Ensures that the creation timestamp of this matrix is greater than or equal to the given value.
*
*
* If the creation timestamp of this matrix happens to be greater than the given timestamp, it will be adjusted to match it.
*
*
* @param creationTimestamp The creation timestamp to match. Must not be negative.
*/
public void ensureCreationTimestampIsGreaterThanOrEqualTo(long creationTimestamp);
}