resultset.java

SearchPathServer

/*
 * MM JDBC Drivers for MySQL
 *
 * $Id: ResultSet.java,v 1.7 2002/05/15 03:15:00 mark_matthews Exp $
 *
 * Copyright (C) 1998 Mark Matthews <[e-mail]>
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) 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
 * Library General Public License for more details.
 * 
 * You should have received a copy of the GNU Library 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.
 *
 * See the COPYING file located in the top-level-directory of
 * the archive of this library for complete text of license.
 *
 * Some portions:
 *
 * Copyright (c) 1996 Bradley McLean / Jeffrey Medeiros
 * Modifications Copyright (c) 1996/1997 Martin Rode
 * Copyright (c) 1997 Peter T Mount
 */

/**
 * A ResultSet provides access to a table of data generated by executing a
 * Statement.  The table rows are retrieved in sequence.  Within a row its
 * column values can be accessed in any order.
 *
 * <P>A ResultSet maintains a cursor pointing to its current row of data.
 * Initially the cursor is positioned before the first row.  The 'next'
 * method moves the cursor to the next row.
 *
 * <P>The getXXX methods retrieve column values for the current row.  You can
 * retrieve values either using the index number of the column, or by using
 * the name of the column.  In general using the column index will be more
 * efficient.  Columns are numbered from 1.
 *
 * <P>For maximum portability, ResultSet columns within each row should be read
 * in left-to-right order and each column should be read only once.
 *
 *<P> For the getXXX methods, the JDBC driver attempts to convert the
 * underlying data to the specified Java type and returns a suitable Java
 * value.  See the JDBC specification for allowable mappings from SQL types
 * to Java types with the ResultSet getXXX methods.
 *
 * <P>Column names used as input to getXXX methods are case insenstive.  When
 * performing a getXXX using a column name, if several columns have the same
 * name, then the value of the first matching column will be returned.  The
 * column name option is designed to be used when column names are used in the
 * SQL Query.  For columns that are NOT explicitly named in the query, it is
 * best to use column numbers.  If column names were used there is no way for
 * the programmer to guarentee that they actually refer to the intended
 * columns.
 *
 * <P>A ResultSet is automatically closed by the Statement that generated it
 * when that Statement is closed, re-executed, or is used to retrieve the
 * next result from a sequence of multiple results.
 *
 * <P>The number, types and properties of a ResultSet's columns are provided by
 * the ResultSetMetaData object returned by the getMetaData method.
 *
 * @see ResultSetMetaData
 * @see java.sql.ResultSet
 * @author Mark Matthews <[e-mail]>
 * @version $Id: ResultSet.java,v 1.7 2002/05/15 03:15:00 mark_matthews Exp $
 */

package com.mysql.jdbc;

import java.io.*;
import java.math.*;
import java.text.*;
import java.util.*;
import java.sql.*;

public abstract class ResultSet
{
	protected Vector _rows; // The results
	protected Field[] _fields; // The fields

	protected int _currentRow = -1; // Cursor to current row;
	protected byte[][] _thisRow; // Values for current row
	protected com.mysql.jdbc.Connection _connection; // The connection that created us
	protected java.sql.SQLWarning _warnings = null; // The warning chain
	protected boolean _wasNullFlag = false; // for wasNull()
	protected boolean _reallyResult = false; // for executeUpdate vs. execute

	protected Hashtable _columnNameToIndex = null;
	protected Hashtable _fullColumnNameToIndex = null;

	protected int _resultSetType = 0;
	protected int _resultSetConcurrency = 0;

	protected com.mysql.jdbc.Statement _owningStatement;

	protected boolean _closed = false;

	// These are longs for 
	// recent versions of the MySQL server.
	//
	// They get reduced to ints via the JDBC API,
	// but can be retrieved through a MySQLStatement
	// in their entirety.
	//

	protected long _updateID = -1; // for AUTO_INCREMENT
	protected long _updateCount; // How many rows did we update? 

	// For getTimestamp()

	private SimpleDateFormat _TSDF = null;

	/**
	 * A ResultSet is initially positioned before its first row,
	 * the first call to next makes the first row the current row;
	 * the second call makes the second row the current row, etc.
	 *
	 * <p>If an input stream from the previous row is open, it is
	 * implicitly closed.  The ResultSet's warning chain is cleared
	 * when a new row is read
	 *
	 * @return true if the new current is valid; false if there are no
	 *    more rows
	 * @exception java.sql.SQLException if a database access error occurs
	 */

	public boolean next() throws java.sql.SQLException
	{

		if (Driver.trace)
		{
			Object[] args = {
			};
			Debug.methodCall(this, "next", args);
		}

		boolean b;

		if (!reallyResult())
			throw new java.sql.SQLException("ResultSet is from UPDATE. No Data", "S1000");

		if (_rows.size() == 0)
		{
			b = false;
		}
		else
		{
			if (_currentRow + 1 >= _rows.size())
			{

				// force scroll past end

				_currentRow = _rows.size();

				b = false;

			}
			else
			{
				clearWarnings();
				_currentRow = _currentRow + 1;
				_thisRow = (byte[][]) _rows.elementAt(_currentRow);
				b = true;
			}
		}

		if (Driver.trace)
		{

			Debug.returnValue(this, "next", new Boolean(b));

		}

		return b;
	}

	/**
	 * The prev method is not part of JDBC, but because of the
	 * architecture of this driver it is possible to move both
	 * forward and backward within the result set.
	 *
	 * <p>If an input stream from the previous row is open, it is
	 * implicitly closed.  The ResultSet's warning chain is cleared
	 * when a new row is read
	 *
	 * @return true if the new current is valid; false if there are no
	 *    more rows
	 * @exception java.sql.SQLException if a database access error occurs
	 */

	public boolean prev() throws java.sql.SQLException
	{
		if (_currentRow - 1 >= 0)
		{
			_currentRow--;
			_thisRow = (byte[][]) _rows.elementAt(_currentRow);
			return true;
		}
		else
		{
			return false;
		}
	}

	/**
	 * In some cases, it is desirable to immediately release a ResultSet
	 * database and JDBC resources instead of waiting for this to happen
	 * when it is automatically closed.  The close method provides this
	 * immediate release.
	 *
	 * <p><B>Note:</B> A ResultSet is automatically closed by the Statement
	 * the Statement that generated it when that Statement is closed,
	 * re-executed, or is used to retrieve the next result from a sequence
	 * of multiple results.  A ResultSet is also automatically closed
	 * when it is garbage collected.
	 *
	 * @exception java.sql.SQLException if a database access error occurs
	 */

	public void close() throws java.sql.SQLException
	{
		if (_rows != null)
		{
			_rows.removeAllElements();
		}

		_closed = true;
	}

	/**
	 * A column may have the value of SQL NULL; wasNull() reports whether
	 * the last column read had this special value.  Note that you must
	 * first call getXXX on a column to try to read its value and then
	 * call wasNull() to find if the value was SQL NULL
	 *
	 * @return true if the last column read was SQL NULL
	 * @exception java.sql.SQLException if a database access error occurred
	 */

	public boolean wasNull() throws java.sql.SQLException
	{
		return _wasNullFlag;
	}

	/**
	 * Get the value of a column in the current row as a Java String
	 *
	 * @param columnIndex the first column is 1, the second is 2...
	 * @return the column value, null for SQL NULL
	 * @exception java.sql.SQLException if a database access error occurs
	 */

	public String getString(int columnIndex) throws java.sql.SQLException
	{
		checkRowPos();

		if (_fields == null)
		{
			throw new java.sql.SQLException(
				"Query generated no fields for ResultSet",
				"S1002");
		}

		if (columnIndex < 1 || columnIndex > _fields.length)
			throw new java.sql.SQLException(
				"Column Index out of range ( " + columnIndex + " > " + _fields.length + ").",
				"S1002");

		try
		{
			if (_thisRow[columnIndex - 1] == null)
			{
				_wasNullFlag = true;
			}
			else
			{
				_wasNullFlag = false;
			}
		}
		catch (NullPointerException E)
		{
			_wasNullFlag = true;
		}

		if (_wasNullFlag)
			return null;

		if (_connection != null && _connection.useUnicode())
		{
			try
			{
				String Encoding = _connection.getEncoding();

				if (Encoding == null)
				{
					return new String(_thisRow[columnIndex - 1]);
				}
				else
				{
					return new String(_thisRow[columnIndex - 1], _connection.getEncoding());
				}
			}
			catch (java.io.UnsupportedEncodingException E)
			{
				throw new SQLException(
					"Unsupported character encoding '" + _connection.getEncoding() + "'.",
					"0S100");
			}
		}
		else 
		{
			return new String(_thisRow[columnIndex - 1]);
		}

	}

	/**
	 * Get the value of a column in the current row as a Java boolean
	 *
	 * @param columnIndex the first column is 1, the second is 2...
	 * @return the column value, false for SQL NULL
	 * @exception java.sql.SQLException if a database access error occurs
	 */

	public boolean getBoolean(int columnIndex) throws java.sql.SQLException
	{
		String S = getString(columnIndex);

		if (S != null && S.length() > 0)
		{
			int c = S.toLowerCase().charAt(0);
			return ((c == 't') || (c == 'y') || (c == '1') || S.equals("-1"));
		}
		return false; // SQL NULL
	}

	/**
	 * Get the value of a column in the current row as a Java byte.
	 *
	 * @param columnIndex the first column is 1, the second is 2,...
	 * @return the column value; 0 if SQL NULL
	 * @exception java.sql.SQLException if a database access error occurs
	 */

	public byte getByte(int columnIndex) throws java.sql.SQLException
	{
		checkRowPos();

		if (columnIndex < 1 || columnIndex > _fields.length)
			throw new java.sql.SQLException(
				"Column Index out of range ( " + columnIndex + " > " + _fields.length + ").",
				"S1002");

		try
		{
			if (_thisRow[columnIndex - 1] == null)
			{
				_wasNullFlag = true;
			}
			else
			{
				_wasNullFlag = false;
			}
		}
		catch (NullPointerException E)
		{
			_wasNullFlag = true;
		}

		if (_wasNullFlag)
		{
			return 0;
		}

		Field F = _fields[columnIndex - 1];

		switch (F.getMysqlType())
		{
			case MysqlDefs.FIELD_TYPE_DECIMAL :
			case MysqlDefs.FIELD_TYPE_TINY :
			case MysqlDefs.FIELD_TYPE_SHORT :
			case MysqlDefs.FIELD_TYPE_LONG :
			case MysqlDefs.FIELD_TYPE_FLOAT :
			case MysqlDefs.FIELD_TYPE_DOUBLE :
			case MysqlDefs.FIELD_TYPE_LONGLONG :
			case MysqlDefs.FIELD_TYPE_INT24 :
				try
				{
					String S = getString(columnIndex);

					// Strip off the decimals
					if (S.indexOf(".") != -1)
					{
						S = S.substring(0, S.indexOf("."));
					}
					return Byte.parseByte(S);
				}
				catch (NumberFormatException NFE)
				{
					throw new SQLException(
						"Value '" + getString(columnIndex) + "' is out of range [-127,127]",
						"S1009");
				}
			default :
				return _thisRow[columnIndex - 1][0];
		}
	}

	/**
	 * Get the value of a column in the current row as a Java short.
	 *
	 * @param columnIndex the first column is 1, the second is 2,...
	 * @return the column value; 0 if SQL NULL
	 * @exception java.sql.SQLException if a database access error occurs
	 */

	public short getShort(int columnIndex) throws java.sql.SQLException
	{
		return (short) getLong(columnIndex);
	}

	/**
	 * Get the value of a column in the current row as a Java int.
	 *
	 * @param columnIndex the first column is 1, the second is 2,...
	 * @return the column value; 0 if SQL NULL
	 * @exception java.sql.SQLException if a database access error occurs
	 */

	public int getInt(int columnIndex) throws java.sql.SQLException
	{
		return (int) getLong(columnIndex);
	}

	/**
	 * Get the value of a column in the current row as a Java long.
	 *
	 * @param columnIndex the first column is 1, the second is 2,...
	 * @return the column value; 0 if SQL NULL
	 * @exception java.sql.SQLException if a database access error occurs
	 */

	public long getLong(int columnIndex) throws java.sql.SQLException
	{
		checkRowPos();

		if (_fields == null)
		{
			throw new java.sql.SQLException(
				"Query generated no fields for ResultSet",
				"S1002");
		}

		if (columnIndex < 1 || columnIndex > _fields.length)
			throw new java.sql.SQLException(
				"Column Index out of range ( " + columnIndex + " > " + _fields.length + ").",
				"S1002");

		try
		{
			if (_thisRow[columnIndex - 1] == null)
			{
				_wasNullFlag = true;
			}
			else
			{
				_wasNullFlag = false;
			}
		}
		catch (NullPointerException E)
		{
			_wasNullFlag = true;
		}

		if (_wasNullFlag)
		{
			return 0;
		}

		try
		{
			return getLong(_thisRow[columnIndex - 1]);
		}
		catch (NumberFormatException E)
		{
			throw new java.sql.SQLException(
				"Bad format for number '"
					+ new String(_thisRow[columnIndex - 1])
					+ "' in column "
					+ columnIndex
					+ "("
					+ _fields[columnIndex
					- 1]
					+ ").",
				"S1009");
		}
	}

	/**
	 * Get the value of a column in the current row as a Java float.
	 *
	 * @param columnIndex the first column is 1, the second is 2,...
	 * @return the column value; 0 if SQL NULL
	 * @exception java.sql.SQLException if a database access error occurs
	 */

	public float getFloat(int columnIndex) throws java.sql.SQLException
	{
		return (float) getDouble(columnIndex);
	}

	/**
	 * Get the value of a column in the current row as a Java double.
	 *
	 * @param columnIndex the first column is 1, the second is 2,...
	 * @return the column value; 0 if SQL NULL
	 * @exception java.sql.SQLException if a database access error occurs
	 */

	public double getDouble(int columnIndex) throws java.sql.SQLException
	{
		checkRowPos();

		if (_fields == null)
		{
			throw new java.sql.SQLException(
				"Query generated no fields for ResultSet",
				"S1002");
		}

		if (columnIndex < 1 || columnIndex > _fields.length)
			throw new java.sql.SQLException(
				"Column Index out of range ( " + columnIndex + " > " + _fields.length + ").",
				"S1002");