datavaluedescriptor.java

derby database source code.good for you.

/*

   Derby - Class org.apache.derby.iapi.types.DataValueDescriptor

   Copyright 1999, 2004 The Apache Software Foundation or its licensors, as applicable.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

 */

package org.apache.derby.iapi.types;

import org.apache.derby.iapi.services.io.ArrayInputStream;

import org.apache.derby.iapi.error.StandardException;
import org.apache.derby.iapi.types.Orderable;
import org.apache.derby.iapi.services.io.Storable;

import java.io.InputStream;
import java.io.IOException;
import java.sql.Date;
import java.sql.ResultSet;
import java.sql.PreparedStatement;
import java.sql.Time;
import java.sql.Timestamp;
import java.sql.SQLException;
import java.util.Calendar;

/**
 * The DataValueDescriptor interface provides methods to get the data from
 * a column returned by a statement.  This interface has the same methods
 * as NoCastDataValueDescriptor - the only reason it exists is for purposes
 * of internal documentation, to make it clear when the different getXXX
 * methods throw exceptions for illegal conversions.
 * <p>
 * This interface matches the getXXX methods on java.sql.ResultSet. This means
 * everyone satisfies getString and getObject; all of the numeric types, within
 * the limits of representation, satisfy all of the numeric getXXX methods;
 * all of the character types satisfy all of the getXXX methods except
 * getBytes and getBinaryStream; all of the binary types satisfy getBytes and
 * all of the getXXXStream methods; Date satisfies getDate and getTimestamp;
 * Time satisfies getTime; and Timestamp satisfies all of the date/time getXXX 
 * methods.
 * The "preferred" method (one that will always work, I presume) is the one that
 * matches the type most closely. See the comments below for
 * "preferences".  See the JDBC guide for details.
 * <p>
 * This interface does not include the getXXXStream methods.
 * <p>
 * The preferred methods for JDBC are:
 * <p>
 * CHAR and VARCHAR - getString()
 * <p>
 * BIT - getBoolean()
 * <p>
 * TINYINT - getByte()
 * <p>
 * SMALLINT - getShort()
 * <p>
 * INTEGER - getInt()
 * <p>
 * BIGINT - getLong()
 * <p>
 * REAL - getFloat()
 * <p>
 * FLOAT and DOUBLE - getDouble()
 * <p>
 * DECIMAL and NUMERIC - getBigDecimal()
 * <p>
 * BINARY and VARBINARY - getBytes()
 * <p>
 * DATE - getDate()
 * <p>
 * TIME - getTime()
 * <p>
 * TIMESTAMP - getTimestamp()
 * <p>
 * No JDBC type corresponds to getObject().  Use this for user-defined types
 * or to get the JDBC types as java Objects.  All primitive types will be
 * wrapped in their corresponding Object type, i.e. int will be
 * wrapped in an Integer.
 * <p>
 * getStream() 
 * 
 * @author Jeff Lichtman
 */

public interface DataValueDescriptor extends Storable, Orderable
{

	/**
	 * Gets the length of the data value.  The meaning of this is
	 * implementation-dependent.  For string types, it is the number of
	 * characters in the string.  For numeric types, it is the number of
	 * bytes used to store the number.  This is the actual length
	 * of this value, not the length of the type it was defined as.
	 * For example, a VARCHAR value may be shorter than the declared
	 * VARCHAR (maximum) length.
	 *
	 * @return	The length of the data value
	 *
	 * @exception StandardException   On error
	 */
	int	getLength() throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a String.
	 * Throws an exception if the data value is not a string.
	 *
	 * @return	The data value as a String.
	 *
	 * @exception StandardException   Thrown on error
	 */
	String	getString() throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a boolean.
	 * Throws an exception if the data value is not a boolean.
	 * For DataValueDescriptor, this is the preferred interface
	 * for BIT, but for this no-casting interface, it isn't, because
	 * BIT is stored internally as a Bit, not as a Boolean.
	 *
	 * @return	The data value as a boolean.
	 *
	 * @exception StandardException   Thrown on error
	 */
	boolean	getBoolean() throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a byte.
	 * Throws an exception if the data value is not a byte.
	 *
	 * @return	The data value as a byte.
	 *
	 * @exception StandardException   Thrown on error
	 */
	byte	getByte() throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a short.
	 * Throws an exception if the data value is not a short.
	 *
	 * @return	The data value as a short.
	 *
	 * @exception StandardException   Thrown on error
	 */
	short	getShort() throws StandardException;

	/**
	 * Gets the value in the data value descriptor as an int.
	 * Throws an exception if the data value is not an int.
	 *
	 * @return	The data value as a int.
	 *
	 * @exception StandardException   Thrown on error
	 */
	int	getInt() throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a long.
	 * Throws an exception if the data value is not a long.
	 *
	 * @return	The data value as a long.
	 *
	 * @exception StandardException   Thrown on error
	 */
	long	getLong() throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a float.
	 * Throws an exception if the data value is not a float.
	 *
	 * @return	The data value as a float.
	 *
	 * @exception StandardException   Thrown on error
	 */
	float	getFloat() throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a double.
	 * Throws an exception if the data value is not a double.
	 *
	 * @return	The data value as a double.
	 *
	 * @exception StandardException   Thrown on error
	 */
	double	getDouble() throws StandardException;
	
	/**
	 * How should this value be obtained so that it can
	 * be converted to a BigDecimal representation.
	 * @return Types.CHAR for String conversion through getString
	 * Types.DECIMAL for BigDecimal through getObject or Types.BIGINT
	 * for long conversion through getLong
	 * @exception StandardException Conversion is not possible
	 */
	int typeToBigDecimal() throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a byte array.
	 * Throws an exception if the data value is not a byte array.
	 *
	 * @return	The data value as a byte[].
	 *
	 * @exception StandardException  Thrown on error
	 */
	byte[]	getBytes() throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a java.sql.Date.
	 * Throws an exception if the data value is not a Date.
     *	@param cal calendar for object creation
	 * @return	The data value as a java.sql.Date.
	 *
	 * @exception StandardException   Thrown on error
	 */
	Date getDate(java.util.Calendar cal) throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a java.sql.Time.
	 * Throws an exception if the data value is not a Time.
     *	@param cal calendar for object creation
	 *
	 * @return	The data value as a java.sql.Time.
	 *
	 * @exception StandardException   Thrown on error
	 */
	Time	getTime(java.util.Calendar cal) throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a java.sql.Timestamp.
	 * Throws an exception if the data value is not a Timestamp.
     *	@param cal calendar for object creation
	 * @return	The data value as a java.sql.Timestamp.
	 *
	 * @exception StandardException   Thrown on error
	 */
	Timestamp	getTimestamp(java.util.Calendar cal) throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a Java Object.
	 * The type of the Object will be the Java object type corresponding
	 * to the data value's SQL type. JDBC defines a mapping between Java
	 * object types and SQL types - we will allow that to be extended
	 * through user type definitions. Throws an exception if the data
	 * value is not an object (yeah, right).
	 *
	 * @return	The data value as an Object.
	 *
	 * @exception StandardException   Thrown on error
	 */
	Object	getObject() throws StandardException;

	/**
	 * Gets the value in the data value descriptor as a Java InputStream.
	 * Only data types that implements StreamStorable will have stream states.
	 *
	 * @return	The stream state of the data value.
	 *
	 * @exception StandardException   Throws an exception if the data value
	 *								  cannot be received as a stream.
	 */
	InputStream	getStream() throws StandardException;

	/**
	 * Clone this DataValueDescriptor. Results in a new object
	 * that has the same value as this but can be modified independently.
	 *
	 * @return A clone of the DataValueDescriptor with the same initial value as this.
	 */
	public DataValueDescriptor getClone();

	/**
	 * Get a new null value of the same type as this data value.
	 *
	 */
	public DataValueDescriptor getNewNull();

	/**
	 * Set the value based on the value for the specified DataValueDescriptor
	 * from the specified ResultSet.
	 *
	 * @param resultSet		The specified ResultSet.
	 * @param colNumber		The 1-based column # into the resultSet.
	 * @param isNullable	Whether or not the column is nullable
	 *						(No need to call wasNull() if not)
	 * 
	 * @return Nothing.
	 *
	 * @exception StandardException		Thrown on error
	 * @exception SQLException		Error accessing the result set
	 */
	public void setValueFromResultSet(
    ResultSet   resultSet, 
    int         colNumber,
    boolean     isNullable)
		throws StandardException, SQLException;


	/**
		Set this value into a PreparedStatement. This method must
		handle setting NULL into the PreparedStatement.

		@exception SQLException thrown by the PreparedStatement object
		@exception StandardException thrown by me accessing my value.
	*/
	public void setInto(PreparedStatement ps, int position) throws SQLException, StandardException;

	/**
		Set this value into a ResultSet for a subsequent ResultSet.insertRow
		or ResultSet.updateRow. This method will only be called for non-null values.

		@exception SQLException thrown by the ResultSet object
		@exception StandardException thrown by me accessing my value.
	*/
	public void setInto(ResultSet rs, int position) throws SQLException, StandardException;

	/**
	 * Set the value of this DataValueDescriptor to the given value
	 *
	 * @param theValue	An Object containing the value to set this
	 *					DataValueDescriptor to.  Null means set the value
	 *					to SQL null.
	 *
	 * @return	This DataValueDescriptor
	 *
	 * @exception StandardException		Thrown on error
	 */ 
	public void setValue(Object theValue) throws StandardException;
	
	/**
	 * Set the value of this DataValueDescriptor to the given int value
	 *
	 * @param theValue	The value to set this DataValueDescriptor to
	 *
	 * @return	This DataValueDescriptor
	 *
	 * @exception StandardException		Thrown on error
	 */
	public void setValue(int theValue) throws StandardException;


	/**
	 * Set the value of this DataValueDescriptor to the given double value
	 *
	 * @param theValue	The value to set this DataValueDescriptor to
	 *
	 * @return	This DataValueDescriptor
	 *
	 * @exception StandardException		Thrown on error
	 */
	public void setValue(double theValue) throws StandardException;

	/**
	 * Set the value of this DataValueDescriptor to the given double value
	 *
	 * @param theValue	A Double containing the value to set this
	 *					DataValueDescriptor to.  Null means set the value
	 *					to SQL null.
	 *
	 * @return	This DataValueDescriptor
	 *
	 * @exception StandardException		Thrown on error
	 */

	public void setValue(float theValue) throws StandardException;

	/**
	 * Set the value of this DataValueDescriptor to the given short value
	 *
	 * @param theValue	The value to set this DataValueDescriptor to
	 *
	 * @return	This DataValueDescriptor
	 *
	 * @exception StandardException		Thrown on error
	 */
	public void setValue(short theValue) throws StandardException;

	/**
	 * Set the value of this DataValueDescriptor to the given long value
	 *
	 * @param theValue	The value to set this DataValueDescriptor to
	 *
	 * @return	This DataValueDescriptor
	 *
	 * @exception StandardException		Thrown on error
	 */
	public void setValue(long theValue) throws StandardException;

	/**
	 * Set the value of this DataValueDescriptor to the given byte value
	 *
	 * @param theValue	The value to set this DataValueDescriptor to
	 *
	 * @return	This DataValueDescriptor
	 *
	 */
	public void setValue(byte theValue) throws StandardException;

	
	/**
	 * Set the value.
	 *
	 * @param theValue	Contains the boolean value to set this to
	 *
	 * @return	This value
	 *