io.sirix.api.ResourceSession Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of sirix-core Show documentation
SirixDB is a hybrid on-disk and in-memory document oriented, versioned database system. It has a lightweight buffer manager, stores everything in a huge persistent and durable tree and allows efficient reconstruction of every revision. Furthermore, SirixDB implements change tracking, diffing and supports time travel queries.
There is a newer version: 0.11.0
Show newest version
/*
 * Copyright (c) 2011, University of Konstanz, Distributed Systems Group All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification, are permitted
 * provided that the following conditions are met: * Redistributions of source code must retain the
 * above copyright notice, this list of conditions and the following disclaimer. * Redistributions
 * in binary form must reproduce the above copyright notice, this list of conditions and the
 * following disclaimer in the documentation and/or other materials provided with the distribution.
 * * Neither the name of the University of Konstanz nor the names of its contributors may be used to
 * endorse or promote products derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL  BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package io.sirix.api;

import io.sirix.access.ResourceConfiguration;
import io.sirix.access.User;
import io.sirix.access.trx.node.IndexController;
import io.sirix.api.xml.XmlNodeReadOnlyTrx;
import io.sirix.api.xml.XmlNodeTrx;
import io.sirix.exception.SirixException;
import io.sirix.exception.SirixThreadedException;
import io.sirix.exception.SirixUsageException;
import io.sirix.node.interfaces.Node;
import org.checkerframework.checker.index.qual.NonNegative;
import org.checkerframework.checker.nullness.qual.NonNull;
import io.sirix.access.trx.node.AfterCommitState;
import io.sirix.access.trx.node.xml.XmlIndexController;
import io.sirix.cache.Cache;
import io.sirix.cache.RBIndexKey;
import io.sirix.index.path.summary.PathSummaryReader;

import java.nio.file.Path;
import java.time.Instant;
import java.util.List;
import java.util.Optional;
import java.util.concurrent.TimeUnit;

/**
 * 
 * Each resource is bound to a {@code ResourceManager}. Reader-only transactions and the single read/write transaction can then be started from
 * this instance. There can only be one write transaction at a time. However, multiple read-only
 * transactions can coexist concurrently.
 * 
 *
 * @author Sebastian Graf, University of Konstanz
 * @author Marc Kramis, Seabix GmbH
 * @author Johannes Lichtenberger
 */
public interface ResourceSession
    extends AutoCloseable {

  /**
   * Get the resource path.
   *
   * @return the resource path
   */
  Path getResourcePath();

  /**
   * Get the history, that is the metadata informations about the revisions.
   *
   * @return the history
   */
  List getHistory();

  /**
   * Get the history, that is the metadata informations about the revisions.
   *
   * @param revisions number of revision informations to retrieve starting with the most recent
   * @return the history
   */
  List getHistory(int revisions);

  /**
   * Get the history, that is the metadata informations about the revisions.
   *
   * @param fromRevision start revision (must be bigger than {@code toRevision})
   * @param toRevision   start revision (must be lower than {@code fromRevision})
   * @return the history
   */
  List getHistory(int fromRevision, int toRevision);

  /**
   * Get the single node writer if available, wrapped in an {@link Optional}.
   *
   * @return The single node writer if available.
   */
  Optional getNodeTrx();

  /**
   * Begin a new {@link PageReadOnlyTrx}.
   *
   * @return new {@link PageReadOnlyTrx} instance
   */
  default PageReadOnlyTrx beginPageReadOnlyTrx() {
    return beginPageReadOnlyTrx(getMostRecentRevisionNumber());
  }

  /**
   * Begin a new {@link PageReadOnlyTrx}.
   *
   * @param revision revision number
   * @return new {@link PageReadOnlyTrx} instance
   * @throws IllegalArgumentException if {@code revision < 0}
   */
  PageReadOnlyTrx beginPageReadOnlyTrx(@NonNegative int revision);

  /**
   * Begin a new {@link PageTrx}.
   *
   * @return new {@link PageTrx} instance
   * @throws SirixException if Sirix fails to create a new instance
   */
  default PageTrx beginPageTrx() {
    return beginPageTrx(getMostRecentRevisionNumber());
  }

  /**
   * Begin a new {@link PageTrx}.
   *
   * @param revision revision number
   * @return new {@link PageTrx} instance
   * @throws SirixException           if Sirix fails to create a new instance
   * @throws IllegalArgumentException if {@code revision < 0}
   */
  PageTrx beginPageTrx(@NonNegative int revision);

  /**
   * Begin a read-only transaction on the latest committed revision.
   *
   * @return instance of a class, which implements the {@link XmlNodeReadOnlyTrx} interface
   * @throws SirixException if can't begin Read Transaction
   */
  default R beginNodeReadOnlyTrx() {
    return beginNodeReadOnlyTrx(getMostRecentRevisionNumber());
  }

  /**
   * Begin a read-only transaction on the given revision number.
   *
   * @param revision revision to read from denoted by the revision number.
   * @return instance of a class, which implements the {@link XmlNodeReadOnlyTrx} interface
   * @throws IllegalArgumentException if {@code revision < 0}
   * @throws SirixThreadedException   if the thread is interrupted
   * @throws SirixUsageException      if the number of read-transactions is exceeded for a defined time
   */
  R beginNodeReadOnlyTrx(@NonNegative int revision);

  /**
   * Begin a read-only transaction with the revision, which is closest to the given point in time.
   *
   * @param pointInTime the point in time
   * @return instance of a class, which implements the {@link XmlNodeReadOnlyTrx} interface
   * @throws IllegalArgumentException if {@code revision < 0}
   * @throws SirixThreadedException   if the thread is interrupted
   * @throws SirixUsageException      if the number of read-transactions is exceeded for a defined time
   */
  R beginNodeReadOnlyTrx(@NonNull Instant pointInTime);

  /**
   * Begin exclusive read/write transaction without auto commit.
   *
   * @param afterCommitState determines if the transaction keeps running after committing or not
   * @return instance of a class, which implements the {@link XmlNodeTrx} interface
   * @throws SirixThreadedException if the thread is interrupted
   * @throws SirixUsageException    if the number of write-transactions is exceeded for a defined time
   */
  W beginNodeTrx(@NonNull AfterCommitState afterCommitState);

  /**
   * Begin exclusive read/write transaction with auto commit.
   *
   * @param maxNodes         count of node modifications after which a commit is issued
   * @param afterCommitState determines if the transaction keeps running after committing or not
   * @return instance of a class, which implements the {@link XmlNodeTrx} interface
   * @throws SirixThreadedException   if the thread is interrupted
   * @throws SirixUsageException      if the number of write-transactions is exceeded for a defined time
   * @throws IllegalArgumentException if {@code maxNodes < 0}
   */
  W beginNodeTrx(@NonNegative int maxNodes, @NonNull AfterCommitState afterCommitState);

  /**
   * Begin exclusive read/write transaction with auto commit.
   *
   * @param maxTime          time after which a commit is issued
   * @param timeUnit         unit used for time
   * @param afterCommitState determines if the transaction keeps running after committing or not
   * @return instance of a class, which implements the {@link XmlNodeTrx} interface
   * @throws SirixThreadedException   if the thread is interrupted
   * @throws SirixUsageException      if the number of write-transactions is exceeded for a defined time
   * @throws IllegalArgumentException if {@code maxTime < 0}
   * @throws NullPointerException     if {@code timeUnit} is {@code null}
   */
  W beginNodeTrx(@NonNegative int maxTime, @NonNull TimeUnit timeUnit, @NonNull AfterCommitState afterCommitState);

  /**
   * Begin exclusive read/write transaction with auto commit.
   *
   * @param maxNodes         count of node modifications after which a commit is issued
   * @param maxTime          time after which a commit is issued
   * @param timeUnit         unit used for time
   * @param afterCommitState determines if the transaction keeps running after committing or not
   * @return instance of a class, which implements the {@link XmlNodeTrx} interface
   * @throws SirixThreadedException   if the thread is interrupted
   * @throws SirixUsageException      if the number of write-transactions is exceeded for a defined time
   * @throws IllegalArgumentException if {@code maxNodes < 0}
   * @throws NullPointerException     if {@code timeUnit} is {@code null}
   */
  W beginNodeTrx(@NonNegative int maxNodes, @NonNegative int maxTime, @NonNull TimeUnit timeUnit, @NonNull AfterCommitState afterCommitState);

  /**
   * Begin exclusive read/write transaction without auto commit.
   *
   * @return instance of a class, which implements the {@link XmlNodeTrx} interface
   * @throws SirixThreadedException if the thread is interrupted
   * @throws SirixUsageException    if the number of write-transactions is exceeded for a defined time
   */
  W beginNodeTrx();

  /**
   * Begin exclusive read/write transaction with auto commit.
   *
   * @param maxNodes count of node modifications after which a commit is issued
   * @return instance of a class, which implements the {@link XmlNodeTrx} interface
   * @throws SirixThreadedException   if the thread is interrupted
   * @throws SirixUsageException      if the number of write-transactions is exceeded for a defined time
   * @throws IllegalArgumentException if {@code maxNodes < 0}
   */
  W beginNodeTrx(@NonNegative int maxNodes);

  /**
   * Begin exclusive read/write transaction with auto commit.
   *
   * @param maxTime  time after which a commit is issued
   * @param timeUnit unit used for time
   * @return instance of a class, which implements the {@link XmlNodeTrx} interface
   * @throws SirixThreadedException   if the thread is interrupted
   * @throws SirixUsageException      if the number of write-transactions is exceeded for a defined time
   * @throws IllegalArgumentException if {@code maxTime < 0}
   * @throws NullPointerException     if {@code timeUnit} is {@code null}
   */
  W beginNodeTrx(@NonNegative int maxTime, @NonNull TimeUnit timeUnit);

  /**
   * Begin exclusive read/write transaction with auto commit.
   *
   * @param maxNodeCount count of node modifications after which a commit is issued
   * @param timeUnit unit used for time
   * @param maxTime  time after which a commit is issued
   * @return instance of a class, which implements the {@link XmlNodeTrx} interface
   * @throws SirixThreadedException   if the thread is interrupted
   * @throws SirixUsageException      if the number of write-transactions is exceeded for a defined time
   * @throws IllegalArgumentException if {@code maxNodes < 0}
   * @throws NullPointerException     if {@code timeUnit} is {@code null}
   */
  W beginNodeTrx(@NonNegative int maxNodeCount, @NonNegative int maxTime, @NonNull TimeUnit timeUnit);

  /**
   * Open the path summary to allow iteration (basically implementation of {@link XmlNodeReadOnlyTrx}.
   *
   * @param revision revision key to read from
   * @return {@link PathSummaryReader} instance
   * @throws IllegalArgumentException if {@code revision < 0}
   */
  PathSummaryReader openPathSummary(@NonNegative int revision);

  /**
   * Open the path summary to allow iteration (basically implementation of {@link XmlNodeReadOnlyTrx}.
   *
   * @return {@link PathSummaryReader} instance
   * @throws SirixException if can't open path summary
   */
  default PathSummaryReader openPathSummary() {
    return openPathSummary(getMostRecentRevisionNumber());
  }

  /**
   * Get the revision number, which was committed at the closest time to the given point in time.
   *
   * @param pointInTime the point in time
   * @return the revision number, which was committed at the closest time to the given point in time.
   */
  int getRevisionNumber(@NonNull Instant pointInTime);

  /**
   * Safely close resource manager and immediately release all resources. If there are running
   * transactions, they will automatically be closed.
   * 
   * This is an idempotent operation and does nothing if the resource manager is already closed.
   *
   * @throws SirixException if can't close
   */
  @Override
  void close();

  /**
   * Test if session is closed. Needed for check against database for creation of a new one.
   *
   * @return if session was closed
   */
  boolean isClosed();

  /**
   * Get the most recently commited revision number.
   *
   * @return most recently commited revision number
   */
  int getMostRecentRevisionNumber();

  /**
   * Returns {@link ResourceConfiguration} that is bound to the session.
   *
   * @return {@link ResourceConfiguration} instance bound to session
   */
  ResourceConfiguration getResourceConfig();

  /**
   * Get the index controller.
   *
   * @param       Instance of IndexController
   * @param revision the revision number
   * @return the {@link XmlIndexController} instance
   */
  > C getRtxIndexController(int revision);

  /**
   * Get the index controller.
   *
   * @param       The index Controller
   * @param revision the revision
   * @return the {@link XmlIndexController} instance
   */
  > C getWtxIndexController(int revision);

  /**
   * Get the node reader with the given ID wrapped in an optional.
   *
   * @param ID The ID of the reader.
   * @return The node reader if available.
   */
  Optional getNodeReadTrxByTrxId(Long ID);

  /**
   * Determines if this resource manager has a running read-write transaction.
   *
   * @return {@code true}, if a running read-write transaction is found, {code false} otherwise
   */
  boolean hasRunningNodeWriteTrx();

//  /**
//   * Get a read-only transaction for a specific revision, if it exists.
//   *
//   * @param revision the revision number
//   * @return optional read-only transaction
//   */
//  Optional getNodeReadTrxByRevisionNumber(final int revision);

  /**
   * Get the user associated with the current ressource manager session.
   *
   * @return the user
   */
  Optional getUser();

  /**
   * Get cache for index-structures.
   *
   * @return the cache
   */
  Cache getIndexCache();
}