dataset.java

Town是一个100% 纯Java API

package com.workingdogs.town;

import java.io.*;
import java.sql.*;

/*
Town, a Java JDBC abstraction layer
Copyright (C) 1999  Serge Knystautas, Jon Stevens

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.
*/
import java.sql.*;
import java.util.*;

/**
The DataSet represents a table in the database. It is extended by
<a href="QueryDataSet.html">QueryDataSet</a> and
<a href="TableDataSet.html">TableDataSet</a> and should not be used directly.
A DataSet contains a <a href="Schema.html">Schema</a> and potentially a
collection of <a href="Record.html">Records</a>.

@author Jon S. Stevens <A HREF="mailto:[e-mail]">[e-mail]</A>
@author Serge Knystautas <a href="mailto:[e-mail]">[e-mail]</a>
@version 1.0
*/
public abstract class DataSet extends DBConnection
{
    /**
      * Keep column names exactly as presented by the database
      */
    public static final int PRESERVE_CASE = 0;

    /**
     * Force column names to be lowercase, regardless of what the database says
     */
    public static final int FORCE_LOWER_CASE = 1;

    /**
     * Force column names to be uppercase, regardless of what the database says
     */
    public static final int FORCE_UPPER_CASE = 2;

	/**
	 * Turn special characters into entities
	 */
	public static final int CHARACTER_ENTITIES = 0;

	/**
	 * Surround text with CDATA tags
	 */
	public static final int CHARACTER_CDATA = 1;

	/**
	 * Preserve special characters as is
	 */
	public static final int CHARACTER_PRESERVE = 2;

	/**
	 * The method used to encode special characters
	 */
	protected int character_mode = CHARACTER_ENTITIES;

	/**
	 * Omit null values completely
	 */
	public static final int OMIT_NULLS = 0;

	/**
	 * Turn nulls into empty strings
	 */
	public static final int EMPTY_NULLS = 1;

	/**
	 * How should we handle null values
	 */
	protected int null_mode = OMIT_NULLS;

    /** this DataSet's schema object */
    protected Schema schema;

    /** this DataSet's collection of Record objects */
    protected Vector records = null;

    /** have all records been retrieved with the fetchRecords? */
    protected boolean allRecordsRetrieved = false;

    /** number of records retrieved */
    protected int recordRetrievedCount = 0;

    /** number of records that were last fetched */
    protected int lastFetchSize = 0;

    /** number of records total that have been fetched */
    protected int totalFetchCount = 0;

    /** the result set for this DataSet */
    protected ResultSet resultSet;

    /**
     * This method was created in VisualAge.
     * @param connString java.lang.String
     */
    protected DataSet(String driver,
            String connString) throws DataSetException, ConnectionException
    {
        this (driver, connString, (String) null, (String) null);
    }
    /**
       * Create a new DataSet with a connection, tablename and KeyDef
       *
       * @param   conn
       * @param   tableName
       * @param   keydef
       * @exception   ConnectionException
       * @exception   DataSetException
       */
    protected DataSet (String driver, String connString,
            KeyDef keydef) throws ConnectionException, DataSetException
    {
        this (driver, connString, null, null, keydef);
    }
    /**
      * This method was created in VisualAge.
      * @param connString java.lang.String
      */
    protected DataSet(String driver, String connString,
            String username, String password) throws DataSetException,
    ConnectionException
    {
        super (driver, connString, username, password);
    }
    /**
       * Create a new DataSet with a connection, tablename and KeyDef
       *
       * @param   driver
       * @param   connString
       * @param   username
       * @param   password
       * @param   tableName
       * @param   keydef
       * @exception   ConnectionException
       * @exception   DataSetException
       */
    protected DataSet (String driver, String connString,
            String username, String password,
            KeyDef keydef) throws ConnectionException, DataSetException
    {
        super (driver, connString, username, password);

        if (dbconn == null)
            throw new ConnectionException ("Database connection could not be established!");
        else if (keydef == null)
            throw new DataSetException ("You need to specify a valid keydef!");
    }
    /**
       * Adds a record to this data set
       *
       * @return     the added record
       * @exception   DataSetException
       * @exception   ConnectionException
       */
    public abstract Record addRecord () throws DataSetException,
    ConnectionException;
    /**
      * Check if all the records have been retrieve
      *
      * @return true if all records have been retrieved
      */
    public boolean allRecordsRetrieved()
    {
        return this.allRecordsRetrieved;
    }
    /**
       *  Remove all records from the DataSet and nulls those records out
       *  and close() the DataSet.
       *
       * @return     an instance of myself
       */
    public DataSet clearRecords()
    {
        this.records.removeAllElements();
        this.records = null;
        return this;
    }

    /**
       * Releases the records, closes the ResultSet and the Statement and nulls the schema
       *
       * @exception   DataSetException
       * @exception   ConnectionException
       */
    public void close () throws DataSetException, ConnectionException
    {
        try
        {
            releaseRecords();
            schema = null;
            if (this.stmt != null)
                this.stmt.close();
            if (this.resultSet != null && ! (this instanceof QueryDataSet))
                resultSet().close();
            this.resultSet = null;

            super.close ();
        }
        catch (SQLException sqle)
        {
            throw new ConnectionException (sqle);
        }
    }

    /**
       * Check to see if the DataSet contains a Record at 0 based position
       *
       * @param   pos
       * @return     true if record exists
       */
    public boolean containsRecord(int pos) throws DataSetException,
    ConnectionException
    {
        if (this.records == null)
            fetchRecords ();

        try
        {
            if (this.records.elementAt(pos) != null)
                return true;
        }
        catch (Exception e)
        {
            return false;
        }
        return false;
    }
    /**
       * Causes the DataSet to hit the database and fetch all the records.
       *
       * @return     an instance of myself
       * @exception   ConnectionException
       * @exception   DataSetException
       */
    public DataSet fetchRecords() throws ConnectionException,
    DataSetException
    {
        return fetchRecords (0, -1);
    }
    /**
       * Causes the DataSet to hit the database and fetch max records.
       *
       * @param   max
       * @return     an instance of myself
       * @exception   ConnectionException
       * @exception   DataSetException
       */
    public DataSet fetchRecords(int max) throws ConnectionException,
    DataSetException
    {
        return fetchRecords (0, max);
    }
    /**
       * Causes the DataSet to hit the database and fetch start to max records. Start is at Record 0.
       *
       * @param   start
       * @param   max
       * @return     an instance of myself
       * @exception   ConnectionException
       * @exception   DataSetException
       */
    public DataSet fetchRecords(int start,
            int max) throws ConnectionException, DataSetException
    {
        if (max == 0)
            throw new DataSetException ("Max is 1 based and must be greater than 0!");
        if (max != -1 && start > max)
            throw new DataSetException ("Start cannot be larger than max!");
        else if (lastFetchSize() > 0 && this.records != null)
            throw new DataSetException ("You must call DataSet.clearRecords() before executing DataSet.fetchRecords() again!");

        String selectString = getSelectString ();
        /*
         if (selectString == null)
         {
         	selectString = new StringBuffer (256);
         	selectString.append ("SELECT ");
         	selectString.append (schema().attributes());
         	selectString.append (" FROM ");
         	selectString.append (schema().tableName());
         }
         */
        try
        {
            if (stmt == null)
            {
                stmt = connection().createStatement();
                this.resultSet =
                        stmt.executeQuery (selectString.toString());
            }

            if (this.resultSet != null)
            {
                if (this.records == null && max > 0)
                    this.records = new Vector (max);
                else
                    this.records = new Vector ();

                int startCounter = 0;
                int fetchCount = 0;
                while (! allRecordsRetrieved())
                {
                    if (fetchCount == max)
                        break;

                    if (startCounter >= start)
                    {
                        if (this.resultSet.next())
                        {
                            Record rec = new Record (this);
                            records.addElement (rec);
                            fetchCount++;
                        }
                        else
                        {
                            setAllRecordsRetrieved (true);
                            break;
                        }
                    }
                    else
                    {
                        startCounter++;
                    }
                }

                lastFetchSize = fetchCount;
            }
        }
        catch (SQLException e)
        {
            if (stmt != null)
            {
                try
                {
                    stmt.close();