AbstractRequest.java

/**
 * C-JDBC: Clustered JDBC.
 * Copyright (C) 2002-2004 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, Mathieu Peltier.
 */

package org.objectweb.cjdbc.common.sql;

import java.io.Serializable;
import java.sql.SQLException;

import org.objectweb.cjdbc.common.sql.schema.DatabaseSchema;

/**
 * An <code>AbstractRequest</code> defines the skeleton of an SQL request.
 * 
 * @author <a href="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a>
 * @author <a href="mailto:Julie.Marguerite@inria.fr">Julie Marguerite </a>
 * @author <a href="mailto:Mathieu.Peltier@inrialpes.fr">Mathieu Peltier </a>
 * @version 1.0
 */
public abstract class AbstractRequest implements Serializable
{
  /** Request unique id (set by the controller). */
  protected transient long id;

  /** SQL query (should be set in constructor). */
  protected String         sqlQuery;

  /** SQL query skeleton as it appears in PreparedStatements. */
  protected String         sqlSkeleton      = null;

  /**
   * Login used to issue this request (must be set by the
   * VirtualDatabaseWorkerThread).
   */
  protected String         login;

  /** Whether this request is cacheable or not. */
  protected int            cacheable;

  /** Whether the SQL content has been parsed or not. */
  protected boolean        isParsed;

  /**
   * Maximum number of rows in the ResultSet.
   * 
   * @see java.sql.Statement#setMaxRows(int)
   */
  protected int            maxRows;

  private int              fetchSize        = 0;

  //
  // Connection related parameters
  //

  /** True if the connection has been set to read-only */
  protected boolean        isReadOnly       = false;

  /**
   * Whether this request has been sent in <code>autocommit</code> mode or
   * not.
   */
  protected boolean        isAutoCommit;

  /**
   * Transaction identifier if this request belongs to a transaction. The value
   * is set by the VirtualDatabaseWorkerThread.
   */
  protected long           transactionId;

  /**
   * Timeout for this request in seconds, value 0 means no timeout (should be
   * set in constructor).
   */
  protected int            timeout;

  /**
   * Should the driver do escape processing before sending to the database? No
   * setter for this member, should be set in constructor.
   */
  protected boolean        escapeProcessing = true;

  /**
   * Should match System.getProperty("line.separator") on the driver side.
   * Required for parsing.
   */
  private String           lineSeparator    = null;

  /**
   * If set to true, the query is interpreted on the driver side, if false the
   * various parameters are encoded and passed as is to the database native
   * driver by the controller.
   */
  private boolean          driverProcessed  = true;

  /**
   * Default constructor Creates a new <code>AbstractRequest</code> object
   * 
   * @param sqlQuery the SQL query
   * @param escapeProcessing should the driver to escape processing before
   *          sending to the database ?
   * @param timeout an <code>int</code> value
   * @param lineSeparator the line separator used in the query
   */
  public AbstractRequest(String sqlQuery, boolean escapeProcessing,
      int timeout, String lineSeparator)
  {
    this.sqlQuery = sqlQuery;
    this.escapeProcessing = escapeProcessing;
    this.timeout = timeout;
    this.lineSeparator = lineSeparator;
  }

  /**
   * Returns <code>true</code> if this request is a read request (
   * <code>SELECT</code> requests for example perform a read).
   * 
   * @return <code>true</code> if this request is a read request
   */
  public abstract boolean isReadRequest();

  /**
   * Returns <code>true</code> if this request is a write request (
   * <code>INSERT</code> or <code>UPDATE</code> for example perform writes).
   * 
   * @return <code>true</code> if this requests is a write request
   */
  public abstract boolean isWriteRequest();

  /**
   * Returns <code>true</code> if the resulting operation on this request is
   * unknown (some non-standard command or stored procedure for example).
   * 
   * @return a <code>boolean</code> value
   */
  public abstract boolean isUnknownRequest();

  /**
   * Returns <code>true</code> if the request SQL content has been already
   * parsed.
   * 
   * @return a <code>boolean</code> value
   */
  public boolean isParsed()
  {
    return isParsed;
  }

  /**
   * Returns <code>true</code> if the connection is set to read-only
   * 
   * @return a <code>boolean</code> value
   */
  public boolean isReadOnly()
  {
    return isReadOnly;
  }

  /**
   * Sets the read-only mode for this request.
   * 
   * @param isReadOnly <code>true</code> if connection is read-only
   */
  public void setIsReadOnly(boolean isReadOnly)
  {
    this.isReadOnly = isReadOnly;
  }

  /**
   * Returns the cacheable status of this request. It can be:
   * {@link org.objectweb.cjdbc.common.sql.RequestType#CACHEABLE},
   * {@link org.objectweb.cjdbc.common.sql.RequestType#UNCACHEABLE}or
   * {@link org.objectweb.cjdbc.common.sql.RequestType#UNIQUE_CACHEABLE}
   * 
   * @return a <code>int</code> value
   */
  public int getCacheAbility()
  {
    return cacheable;
  }

  /**
   * Set the cacheable status of this request. It can be:
   * {@link org.objectweb.cjdbc.common.sql.RequestType#CACHEABLE},
   * {@link org.objectweb.cjdbc.common.sql.RequestType#UNCACHEABLE}or
   * {@link org.objectweb.cjdbc.common.sql.RequestType#UNIQUE_CACHEABLE}
   * 
   * @param cacheAbility a <code>int</code> value
   */
  public void setCacheAbility(int cacheAbility)
  {
    this.cacheable = cacheAbility;
  }

  /**
   * Returns <code>true</code> if the driver should escape processing before
   * sending to the database?
   * 
   * @return a <code>boolean</code> value
   */
  public boolean getEscapeProcessing()
  {
    return escapeProcessing;
  }

  /**
   * Returns the unique id of this request.
   * 
   * @return the request id
   */
  public long getId()
  {
    return id;
  }

  /**
   * Sets the unique id of this request.
   * 
   * @param id the id to set
   */
  public void setId(long id)
  {
    this.id = id;
  }

  /**
   * Returns <code>true</code> if the request should be executed in
   * <code>autocommit</code> mode.
   * 
   * @return a <code>boolean</code> value
   */
  public boolean isAutoCommit()
  {
    return isAutoCommit;
  }

  /**
   * Sets the autocommit mode for this request.
   * 
   * @param isAutoCommit <code>true</code> if <code>autocommit</code> should
   *          be used
   */
  public void setIsAutoCommit(boolean isAutoCommit)
  {
    this.isAutoCommit = isAutoCommit;
  }

  /**
   * Returns the login used to issue this request.
   * 
   * @return a <code>String</code> value
   */
  public String getLogin()
  {
    return login;
  }

  /**
   * Returns the lineSeparator value.
   * 
   * @return Returns the lineSeparator.
   */
  public String getLineSeparator()
  {
    return lineSeparator;
  }

  /**
   * Sets the lineSeparator value.
   * 
   * @param lineSeparator The lineSeparator to set.
   */
  public void setLineSeparator(String lineSeparator)
  {
    this.lineSeparator = lineSeparator;
  }

  /**
   * Sets the login to use to issue this request.
   * 
   * @param login a <code>String</code> value
   */
  public void setLogin(String login)
  {
    this.login = login;
  }

  /**
   * Gets the SQL code of this request.
   * 
   * @return the SQL query
   */
  public String getSQL()
  {
    return sqlQuery;
  }

  /**
   * Get a short form of this request if the SQL statement exceeds
   * nbOfCharacters.
   * 
   * @param nbOfCharacters number of characters to include in the short form.
   * @return the nbOfCharacters first characters of the SQL statement
   */
  public String getSQLShortForm(int nbOfCharacters)
  {
    if ((nbOfCharacters == 0) || (sqlQuery.length() < nbOfCharacters))
      return sqlQuery;
    else
      return sqlQuery.substring(0, nbOfCharacters) + "...";
  }

  /**
   * Get the maximum number of rows the ResultSet can contain.
   * 
   * @return maximum number of rows
   * @see java.sql.Statement#getMaxRows()
   */
  public int getMaxRows()
  {
    return maxRows;
  }

  /**
   * Set the maximum number of rows in the ResultSet.
   * 
   * @param rows maximum number of rows
   * @see java.sql.Statement#setMaxRows(int)
   */
  public void setMaxRows(int rows)
  {
    maxRows = rows;
  }

  /**
   * Set the SQL code of this request. Warning! The request parsing validity is
   * not checked. The caller has to recall
   * {@link #parse(DatabaseSchema, int, boolean)}if needed.
   * 
   * @param sql SQL statement
   */
  public void setSQL(String sql)
  {
    this.sqlQuery = sql;
  }

  /**
   * Gets the timeout for this request in seconds.
   * 
   * @return timeout in seconds (0 means no timeout)
   */
  public int getTimeout()
  {
    return timeout;
  }

  /**
   * Sets the new timeout in seconds for this request.
   * 
   * @param timeout an <code>int</code> value
   */
  public void setTimeout(int timeout)
  {
    this.timeout = timeout;
  }

  /**
   * Gets the identifier of the transaction if this request belongs to a
   * transaction, or -1 if this request does not belong to a transaction.
   * 
   * @return transaction identifier or -1
   */
  public long getTransactionId()
  {
    return transactionId;
  }

  /**
   * Sets the transaction identifier this request belongs to.
   * 
   * @param id transaction id
   */
  public void setTransactionId(long id)
  {
    transactionId = id;
  }

  /**
   * Two requests are equal if they have the same SQL code.
   * 
   * @param other an object
   * @return a <code>boolean</code> value
   */
  public boolean equals(Object other)
  {
    if (!(other instanceof AbstractRequest))
      return false;

    AbstractRequest r = (AbstractRequest) other;
    return sqlQuery.equals(r.getSQL())
        && (transactionId == r.getTransactionId());
  }

  /**
   * Parses the SQL request and extract the selected columns and tables given
   * the <code>DatabaseSchema</code> of the database targeted by this request.
   * <p>
   * An exception is thrown when the parsing fails. Warning, this method does
   * not check the validity of the request. In particular, invalid request could
   * be parsed without throwing an exception. However, valid SQL request should
   * never throw an exception.
   * 
   * @param schema a <code>DatabaseSchema</code> value
   * @param granularity parsing granularity as defined in
   *          <code>ParsingGranularities</code>
   * @param isCaseSensitive true if parsing must be case sensitive
   * @exception SQLException if the parsing fails
   */
  public abstract void parse(DatabaseSchema schema, int granularity,
      boolean isCaseSensitive) throws SQLException;

  /**
   * Clones the parsing of a request.
   * 
   * @param request the parsed request to clone
   */
  public abstract void cloneParsing(AbstractRequest request);

  /**
   * If the query has a skeleton defined, return the skeleton wth all carriage
   * returns replaces with spaces. If no SQL skeleton is defined, we perform the
   * same processing on the instanciated SQL statement.
   * 
   * @return statement with CR replaces by spaces
   */
  public String trimCarriageReturn()
  {
    if (sqlSkeleton != null)
      return trimCarriageReturn(sqlSkeleton);
    else
      return trimCarriageReturn(sqlQuery);
  }

  /**
   * Replaces any carriage returns by a space in a given <code>String</code>.
   * 
   * @param s the <code>String</code> to transform
   * @return the transformed <code>String</code>
   */
  private String trimCarriageReturn(String s)
  {
    int lineSeparatorLength = lineSeparator.length();
    int idx = s.indexOf(lineSeparator);
    if (idx == -1)
      return s;
    else
    {
      if (idx == 0) // carriage is the first character
        return trimCarriageReturn(s.substring(lineSeparatorLength));
      else if (idx == (s.length() - lineSeparatorLength)) // is the last
        // character
        return s.substring(0, s.length() - lineSeparatorLength);
      else
        // is somewhere in the string
        return s.substring(0, idx) + " "
            + trimCarriageReturn(s.substring(idx + lineSeparatorLength));
    }
  }

  /**
   * @return the SQL query skeleton given in a <code>PreparedStatement</code>.
   */
  public String getSqlSkeleton()
  {
    return sqlSkeleton;
  }

  /**
   * @param skel set the SQL query skeleton given in a
   *          <code>PreparedStatement</code>.
   */
  public void setSqlSkeleton(String skel)
  {
    sqlSkeleton = skel;
  }

  /**
   * Returns the driverProcessed value.
   * 
   * @return Returns the driverProcessed.
   */
  public boolean isDriverProcessed()
  {
    return driverProcessed;
  }

  /**
   * Sets the driverProcessed value.
   * 
   * @param driverProcessed The driverProcessed to set.
   */
  public void setDriverProcessed(boolean driverProcessed)
  {
    this.driverProcessed = driverProcessed;
  }

  /**
   * Sets the fetchSize value.
   * 
   * @param fetchSize The fetchSize to set.
   */
  public void setFetchSize(int fetchSize)
  {
    this.fetchSize = fetchSize;
  }

  /**
   * Returns the fetchSize value.
   * 
   * @return Returns the fetchSize.
   */
  public int getFetchSize()
  {
    return fetchSize;
  }

  /**
   * Displays some debugging information about this request.
   */
  public void debug()
  {
    System.out.println("Request: " + sqlQuery);
    System.out.print("Cacheable status: ");
    System.out.println(RequestType.getInformation(cacheable));
  }

}

---