AbstractRecoveryLog.java

/**
 * C-JDBC: Clustered JDBC.
 * Copyright (C) 2002-2005 French National Institute For Research In Computer
 * Science And Control (INRIA).
 * Contact: c-jdbc@objectweb.org
 * 
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by the
 * Free Software Foundation; either version 2.1 of the License, or any later
 * version.
 * 
 * This library 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 Lesser General Public License
 * for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
 *
 * Initial developer(s): Emmanuel Cecchet.
 * Contributor(s): Julie Marguerite.
 */

package org.objectweb.cjdbc.controller.recoverylog;

import java.sql.SQLException;
import java.util.ArrayList;

import javax.management.NotCompliantMBeanException;

import org.objectweb.cjdbc.common.i18n.Translate;
import org.objectweb.cjdbc.common.jmx.mbeans.AbstractRecoveryLogMBean;
import org.objectweb.cjdbc.common.log.Trace;
import org.objectweb.cjdbc.common.sql.AbstractWriteRequest;
import org.objectweb.cjdbc.common.sql.StoredProcedure;
import org.objectweb.cjdbc.common.xml.DatabasesXmlTags;
import org.objectweb.cjdbc.common.xml.XmlComponent;
import org.objectweb.cjdbc.controller.jmx.AbstractStandardMBean;
import org.objectweb.cjdbc.controller.requestmanager.TransactionMarkerMetaData;

/**
 * Log Recovery is responsible for logging performed queries, managing
 * checkpoints and retrieving write requests executed from a given checkpoint.
 * 
 * @author <a href="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a>
 * @author <a href="mailto:Julie.Marguerite@inria.fr">Julie Marguerite </a>
 * @version 1.0
 */
public abstract class AbstractRecoveryLog extends AbstractStandardMBean
    implements
      XmlComponent,
      AbstractRecoveryLogMBean
{

  static Trace logger       = Trace
                                .getLogger("org.objectweb.cjdbc.controller.recoverylog");

  private long recoveringNb = 0;

  /**
   * Generic constructor.
   * 
   * @param mBeanInterface the MBean interface
   * @throws NotCompliantMBeanException if the MBean is not JMX compliant
   */
  protected AbstractRecoveryLog(Class mBeanInterface)
      throws NotCompliantMBeanException
  {
    super(mBeanInterface);
  }

  /**
   * Returns the recoveringNb value.
   * 
   * @return Returns the recoveringNb.
   */
  public long getRecoveringNb()
  {
    return recoveringNb;
  }

  /**
   * Log a write request.
   * 
   * @param request The write request to log
   * @exception SQLException if an error occurs
   */
  public abstract void logRequest(AbstractWriteRequest request)
      throws SQLException;

  /**
   * Log a call to a stored procedure.
   * 
   * @param proc The stored procedure call to log
   * @param isRead True if the stored procedure call returns a ResultSet
   * @exception SQLException if an error occurs
   */
  public abstract void logRequest(StoredProcedure proc, boolean isRead)
      throws SQLException;

  //
  // Transaction management
  //

  /**
   * Get the id of the last transaction logged in the recovery log.
   * 
   * @return the last transaction id.
   * @throws SQLException if an error occured while retrieving the id.
   */
  public abstract long getLastTransactionId() throws SQLException;

  /**
   * Log the beginning of a new transaction.
   * 
   * @param tm The transaction marker metadata
   * @exception SQLException if an error occurs
   */
  public abstract void begin(TransactionMarkerMetaData tm) throws SQLException;

  /**
   * Log a transaction abort. This is used only for transaction that were
   * started but where no request was executed, which is in fact an empty
   * transaction. The underlying implementation might safely discard the
   * corresponding begin from the log as an optimization.
   * 
   * @param tm The transaction marker metadata
   * @exception SQLException if an error occurs
   */
  public abstract void abort(TransactionMarkerMetaData tm) throws SQLException;

  /**
   * Log a transaction commit.
   * 
   * @param tm The transaction marker metadata
   * @exception SQLException if an error occurs
   */
  public abstract void commit(TransactionMarkerMetaData tm) throws SQLException;

  /**
   * Log a transaction rollback.
   * 
   * @param tm The transaction marker metadata
   * @exception SQLException if an error occurs
   */
  public abstract void rollback(TransactionMarkerMetaData tm)
      throws SQLException;

  //
  // Recovery process
  //

  /**
   * Notify the recovery log that a recovery process has started.
   */
  public synchronized void beginRecovery()

  {
    recoveringNb++;
  }

  /**
   * Possibly clean the recovery log after all recovery process are done.
   * 
   * @exception SQLException if an error occurs
   */
  public abstract void cleanRecoveryLog() throws SQLException;

  /**
   * Notify the recovery log that a recovery process has finished. If this is
   * the last recovery process to finish, the cleanRecoveryLog method is called
   * 
   * @see #cleanRecoveryLog()
   */
  public synchronized void endRecovery()
  {
    recoveringNb--;
    if (recoveringNb == 0)
    {
      try
      {
        cleanRecoveryLog();
      }
      catch (SQLException e)
      {
        logger.error(Translate.get("recovery.cleaning.failed", e));
      }
    }
  }

  /**
   * Returns <code>true</code> if at least one backend has started a recover
   * process.
   * 
   * @return <code>boolean</code>
   */
  public synchronized boolean isRecovering()
  {
    return recoveringNb > 0;
  }

  /**
   * Get the next request (begin/commit/rollback or WriteRequest) from the
   * recovery log given the id of the previously recovered request.
   * <p>
   * The id of the request before the first one to recover is given by
   * getCheckpointRequestId.
   * 
   * @param previousRequestId id of the previously recovered request
   * @return AbstractTask task corresponding to the next request to recover
   * @exception SQLException if an error occurs
   * @see #getCheckpointRequestId(String)
   */
  public abstract RecoveryTask recoverNextRequest(long previousRequestId)
      throws SQLException;

  //
  // Checkpoint Management
  //

  /**
   * Retrieve recovery information on a backend. This includes, the last known
   * state of the backend, and the last known checkpoint
   * 
   * @param databaseName the virtual database name
   * @param backendName the backend name
   * @return <code>BackendRecoveryInfo<code> instance or <code>null</code> if the backend does not exist
   * @throws SQLException if cannot proceed
   */
  public abstract BackendRecoveryInfo getBackendRecoveryInfo(
      String databaseName, String backendName) throws SQLException;

  /**
   * Returns an array of names of all the checkpoint available in the recovery
   * log
   * 
   * @return <code>ArrayList</code> of <code>String</code> checkpoint names
   * @throws SQLException if fails
   */
  public abstract ArrayList getCheckpointNames() throws SQLException;

  /**
   * Get the request id corresponding to a given checkpoint. This is the first
   * step in a recovery process. Following steps consist in calling
   * recoverNextRequest.
   * 
   * @param checkpointName Name of the checkpoint
   * @return int the request identifier corresponding to this checkpoint.
   * @exception SQLException if an error occurs
   * @see #recoverNextRequest(long)
   */
  public abstract long getCheckpointRequestId(String checkpointName)
      throws SQLException;

  /**
   * Remove a checkpoint from the recovery. This is useful for recovery
   * maintenant
   * 
   * @param checkpointName to remove
   * @throws SQLException if an error occurs
   */
  public abstract void removeCheckpoint(String checkpointName)
      throws SQLException;

  /**
   * Store the state of the backend in the recovery log
   * 
   * @param databaseName the virtual database name
   * @param backendRecoveryInfo the backend recovery information to store
   * @throws SQLException if cannot proceed
   */
  public abstract void storeBackendRecoveryInfo(String databaseName,
      BackendRecoveryInfo backendRecoveryInfo) throws SQLException;

  /**
   * Store a Checkpoint using the current log state.
   * 
   * @param checkpointName Name of the checkpoint
   * @exception SQLException if an error occurs
   */
  public abstract void storeCheckpoint(String checkpointName)
      throws SQLException;

  /**
   * Store a Checkpoint using the given request id.
   * 
   * @param checkpointName Name of the checkpoint
   * @param requestId request identifier
   * @exception SQLException if an error occurs
   */
  public abstract void storeCheckpoint(String checkpointName, long requestId)
      throws SQLException;

  /**
   * Get xml information of the current recovery load in the system.
   * 
   * @return xml formatted string
   */
  public String getXml()

  {
    StringBuffer info = new StringBuffer();
    info.append("<" + DatabasesXmlTags.ELT_RecoveryLog + ">");
    info.append(getXmlImpl());
    info.append("</" + DatabasesXmlTags.ELT_RecoveryLog + ">");
    return info.toString();
  }

  /**
   * @see org.objectweb.cjdbc.common.xml.XmlComponent#getXml()
   */
  public abstract String getXmlImpl();

  /**
   * Allow to get the content of the recovery log for viewing
   * 
   * @return <code>String[][]</code>
   * @see org.objectweb.cjdbc.console.views.RecoveryLogViewer
   */
  public abstract String[][] getData();

}

---