package com.dbxml.db.core.query;

/*
 * 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: ResultSet.java,v 1.2 2004/02/12 00:17:57 bradford Exp $
 */

import com.dbxml.db.core.Collection;
import com.dbxml.db.core.data.Key;
import com.dbxml.xml.dtsm.Constants;
import com.dbxml.xml.dtsm.DocumentTable;

/**
 * The ResultSet interface is a set interface that allows the
 * developer to iterate over a set of DocumentTables. These
 * DocumentTables are the result of a query, and can either be
 * the entire original document, portions of an original document,
 * or synthesized nodes produced by the query resolver.
 */

public interface ResultSet {
   static final int RESULT_DOCUMENT = Constants.OBJ_BEGIN_DOCUMENT;
   static final int RESULT_ELEMENT = Constants.OBJ_BEGIN_ELEMENT;
   static final int RESULT_ATTRIBUTE = Constants.OBJ_BEGIN_ATTRIBUTE;
   static final int RESULT_PROCINST = Constants.OBJ_BEGIN_PROCINST;
   static final int RESULT_COMMENT = Constants.OBJ_COMMENT;
   static final int RESULT_TEXT = Constants.OBJ_TEXT;
   static final int RESULT_CDATA = Constants.OBJ_CDATA;

   static final int RESULT_STRING = Constants.VAL_STRING;
   static final int RESULT_BOOLEAN = Constants.VAL_BOOLEAN;
   static final int RESULT_DECIMAL = Constants.VAL_DECIMAL;
   static final int RESULT_FLOAT = Constants.VAL_FLOAT;
   static final int RESULT_DOUBLE = Constants.VAL_DOUBLE;
   static final int RESULT_DURATION = Constants.VAL_DURATION;
   static final int RESULT_DATETIME = Constants.VAL_DATETIME;
   static final int RESULT_TIME = Constants.VAL_TIME;
   static final int RESULT_DATE = Constants.VAL_DATE;
   static final int RESULT_GYEARMONTH = Constants.VAL_GYEARMONTH;
   static final int RESULT_GYEAR = Constants.VAL_GYEAR;
   static final int RESULT_GMONTHDAY = Constants.VAL_GMONTHDAY;
   static final int RESULT_GDAY = Constants.VAL_GDAY;
   static final int RESULT_GMONTH = Constants.VAL_GMONTH;
   static final int RESULT_HEXBINARY = Constants.VAL_HEXBINARY;
   static final int RESULT_BASE64BINARY = Constants.VAL_BASE64BINARY;
   static final int RESULT_ANYURI = Constants.VAL_ANYURI;
   static final int RESULT_QNAME = Constants.VAL_QNAME;

   /**
    * getCollection returns the top-level Collection context.  Note
    * that this may not be the collection that individual results
    * belong to as the query may execute recursively over a
    * Collection tree.
    *
    * @return The Collection context
    */
   Collection getCollection() throws QueryException;

   /**
    * getQuery returns the Query instance that produced this
    * result set.
    *
    * @return The Query
    */
   Query getQuery() throws QueryException;

   /**
    * next moves the cursor down one object from its current position.
    * A ResultSet cursor is initially positioned before the
    * first object; the first call to the method next makes the
    * first object the current object; the second call makes the
    * second object the current object, and so on.
    *
    * @return true if there is another object, false otherwise
    */
   boolean next() throws QueryException;

   /**
    * close releases this ResultSet object's database
    * resources immediately instead of waiting for this to happen
    * when it is automatically closed.
    */
   void close() throws QueryException;

   /**
    * getResultType returns the type of the object that the
    * ResultSet cursor currently points to.  Based on this
    * value, an appropriate result accessor method can be
    * chosen.
    *
    * @return the result type (ex: RESULT_DOCUMENT)
    */
   int getResultType() throws QueryException;

   /**
    * getCount returns the number of records returned or
    * modified by this query.  If this count is not available,
    * the query will return -1.
    *
    * @return The result/modified count
    */
   int getCount() throws QueryException;

   /**
    * getResult returns the result as a DocumentTable structure.
    *
    * @return The result DocumentTable
    */
   DocumentTable getResult() throws QueryException;

   /**
    * getResultCollection returns the Collection context for the
    * current result in the cursor.
    *
    * @return The Collection context
    */
   Collection getResultCollection() throws QueryException;

   /**
    * getResultKey return the Key for the current result in the
    * cursor.  Note that the key identifies the entire Document,
    * while the result may only be a fragment, in which case,
    * the key may be duplicated in the result set.
    */
   Key getResultKey() throws QueryException;
}
