package com.dbxml.db.common.btree;

/*
 * dbXML - Native XML Database
 * Copyright (C) 1999-2004  The dbXML Group, L.L.C.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 *
 * $Id: PagedLogPlayback.java,v 1.3 2004/07/20 20:19:33 bradford Exp $
 */

import com.dbxml.db.core.transaction.TransactionException;
import java.nio.ByteBuffer;

/**
 * PagedLogPlayback provides a callback interface so that a PagedLog can
 * play back log events to its parent Paged instance.  The Paged instance
 * will use these events to recreate its state in the case of a failure.
 */

interface PagedLogPlayback {
   /**
    * beginPlayback tells the callback handler that the log is about
    * to be played back, and that it should initialize any resources
    * that need to be initialized.
    */
   void beginPlayback();

   /**
    * start signals the beginning of a Transaction.
    *
    * @param transactionID The Transaction ID
    */
   void start(long transactionID) throws TransactionException;

   /**
    * commit signals the end of a Transaction by way of a commit event.
    *
    * @param transaction The Transaction ID
    */
   void commit(long transactionID) throws TransactionException;

   /**
    * cancel signals the end of a transaction by way of a cancel event.
    *
    * @param transaction The Transaction ID
    */
   void cancel(long transactionID) throws TransactionException;

   /**
    * write signals a write event including all of the necessary data to
    * recreate or cancel the write depending on the type of logging that
    * is being performed.  This event should not be acted upon until a
    * subsequent commit or cancel event is encountered.
    *
    * @param transactionID The Transaction ID
    * @param offset The offset into the file to perform the write
    * @param buffer The buffer value
    */
   void write(long transactionID, long offset, ByteBuffer buffer) throws TransactionException;

   /**
    * checkpoint signals that a checkpoint has been encountered in the log.
    * If a checkpoint is enountered, all previous events can safely be
    * ignored.  By default, the PagedLog will perform a truncation at a
    * checkpoint, so this event may never be encountered.
    */
   void checkpoint() throws TransactionException;

   /**
    * endPlayback tells the callback handler that the log has finished
    * being played back, and that it can clean up any resources that
    * have been allocated.
    */
   void endPlayback();
}
