/*
 * Copyright (c) 2007, Marc Kramis
 * 
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 * 
 * $Id$
 */

package org.treetank.api;

/**
 * <h1>ISession</h1>
 * 
 * <p>
 * Each TreeTank file is bound to one instance implementing ISession.
 * Transactions can then be started from this instance. There can only be one
 * IWriteTransaction at the time. It can be committed or aborted through the
 * ISession.
 * </p>
 * 
 * <p>
 * Auto commit mode is the default mode and works as follows:
 * <ul>
 *  <li>Commit when the number of modifications exceeds
 *      <code>IConstants.COMMIT_THRESHOLD</code>.</li>
 * </ul>
 * </p>
 * 
 * <h2>Description</h2>
 * 
 * <h2>Convention</h2>
 * 
 * <h2>User Example</h2>
 * 
 * <h2>Developer Example</h2>
 */
public interface ISession {

  /**
   * Get file name of TreeTank file.
   * 
   * @return File name of TreeTank file.
   */
  public String getFileName();

  /**
   * Get absolute path to TreeTank file.
   * 
   * @return Absolute path to TreeTank file.
   */
  public String getAbsolutePath();

  /**
   * Tells whether the session is bound to an encrypted TreeTank file.
   * 
   * @return True if the TreeTank file is encrypted. False else.
   */
  public boolean isEncrypted();

  /**
   * Tells whether the session is bound to a checksummed TreeTank file.
   * 
   * @return True if the TreeTank file is checksummed. False else.
   */
  public boolean isChecksummed();

  /**
   * Get the major revision of the TreeTank version.
   * 
   * @return Major revision of TreeTank version.
   */
  public int getVersionMajor();

  /**
   * Get the minor revision of the TreeTank version.
   * 
   * @return Minor revision of TreeTank version.
   */
  public int getVersionMinor();

  /**
   * Begin a read-only transaction on the latest committed revision key.
   * 
   * @return IReadTransaction instance.
   */
  public IReadTransaction beginReadTransaction();

  /**
   * Begin a read-only transaction on the given revision key.
   * 
   * @param revisionKey Revision key to read from.
   * @return IReadTransaction instance.
   */
  public IReadTransaction beginReadTransaction(final long revisionKey);

  /**
   * Begin exclusive read/write transaction. Uses auto commit as default.
   * 
   * @return IWriteTransaction instance.
   */
  public IWriteTransaction beginWriteTransaction();

  /**
   * Begin exclusive read/write transaction.
   * 
   * @param autoCommit True activates auto commit.
   * @return IWriteTransaction instance.
   */
  public IWriteTransaction beginWriteTransaction(final boolean autoCommit);

  /**
   * Safely close session and immediately release all resources. A session
   * can not be closed as long as there are running reading or writing
   * transactions.
   * 
   * This is an idempotent operation and does nothing if the session is
   * already closed.
   */
  public void close();

}

@@ -834,24 +834,52 @@
 on%3C/h1%3E%0A * %0A
+ * %3Ch2%3EDescription%3C/h2%3E%0A * %0A
  * %3Cp%3E%0A * Ea
@@ -932,25 +932,34 @@
 ementing
- 
+%0A * %3Ccode%3E
 ISession
 .%0A * Tra
@@ -946,24 +946,31 @@
 ode%3EISession
+%3C/code%3E
 .%0A * Transac
@@ -1040,16 +1040,22 @@
  one%0A * 
+%3Ccode%3E
 IWriteTr
@@ -1063,16 +1063,23 @@
 nsaction
+%3C/code%3E
  at the 
@@ -1088,208 +1088,435 @@
 me. 
-It can be committed or aborted through the%0A * ISession.%0A * %3C/p%3E%0A * %0A * %3Cp%3E%0A * Auto commit mode is the default mode and works as follows:%0A * %3Cul%3E%0A *  %3Cli%3ECommit when the number of modifications exceeds
+However, multiple%0A * %3Ccode%3EIReadTransactions%3C/code%3E can coexist concurrently.%0A * %3C/p%3E%0A * %0A * %3Ch2%3EConvention%3C/h2%3E%0A * %0A * %3Ch2%3EUser Example%3C/h2%3E%0A * %0A * %3Cp%3E%0A *  %3Cpre%3E%0A *   // Simple session without encryption or end-to-end integrity.%0A *   final ISession session = Session.beginSession(%22example.tnk%22);%0A *   %0A *   // Session with encryption and end-to-end integrity.%0A *   final SessionConfiguration config = new SessionConfiguration(
 %0A * 
@@ -1524,154 +1524,157 @@
     
+ 
-%3Ccode%3EIConstants.COMMIT_THRESHOLD%3C/code%3E.%3C/li%3E%0A * %3C/ul%3E%0A * %3C/p%3E%0A * %0A * %3Ch2%3EDescription%3C/h2%3E%0A * %0A * %3Ch2%3EConvention%3C/h2%3E%0A * %0A * %3Ch2%3EUser Example%3C/h2
+%22example.tnk%22,%0A *       %22exampleKey......%22.getBytes(),%0A *       true);%0A *   final ISession session = Session.beginSession(config);%0A *  %3C/pre%3E%0A * %3C/p
 %3E%0A *

ISession JavaDoc.