db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d..@apache.org
Subject svn commit: r393570 - in /db/derby/code/trunk/java/engine/org/apache/derby/iapi: services/io/StreamStorable.java types/DataType.java types/DataValueDescriptor.java types/SQLBinary.java types/SQLBlob.java types/SQLChar.java
Date Wed, 12 Apr 2006 18:32:59 GMT
Author: djd
Date: Wed Apr 12 11:32:59 2006
New Revision: 393570

URL: http://svn.apache.org/viewcvs?rev=393570&view=rev
Log:
DERBY-438 (partial) Clarify by adding comments or re-naming variables the expected format
of stream values passed to internal data types. The internal data types always work in streams
that represent the on-disk format of the data type and not the application visible stream.
Some code in SQLBinary and SQLBLob is incorrect and will be fixed in a subsequent commit.

Modified:
    db/derby/code/trunk/java/engine/org/apache/derby/iapi/services/io/StreamStorable.java
    db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataType.java
    db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataValueDescriptor.java
    db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBinary.java
    db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBlob.java
    db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLChar.java

Modified: db/derby/code/trunk/java/engine/org/apache/derby/iapi/services/io/StreamStorable.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/iapi/services/io/StreamStorable.java?rev=393570&r1=393569&r2=393570&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/iapi/services/io/StreamStorable.java
(original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/iapi/services/io/StreamStorable.java
Wed Apr 12 11:32:59 2006
@@ -23,27 +23,35 @@
 import java.io.InputStream;
 
 /**
-  Formatable for holding SQL data (which may be null).
-  It supports streaming columns.
+ * Streaming interface for a data value. The format of
+ * the stream is data type dependent and represents the
+ * on-disk format of the value. That is it is different
+ * to the value an application will see through JDBC
+ * with methods like getBinaryStream and getAsciiStream.
+ * 
+ * <BR>
+ * If the value is NULL (DataValueDescriptor.isNull returns
+ * true then these methods should not be used to get the value.
 
   @see Formatable
  */
 public interface StreamStorable
 {
 	/**
-	  Return the stream state of the object.
+	  Return the on-disk stream state of the object.
 	  
 	**/
 	public InputStream returnStream();
 
 	/**
-	  sets the stream state for the object.
+	  sets the on-disk stream state for the object.
 	**/
 	public void setStream(InputStream newStream);
 
 	/**
-	  sets the stream state for the object.
-	
+     * Set the value by reading the stream and
+     * converting it to an object form.
+     * 
 		@exception StandardException on error
 	**/
 	public void loadStream() throws StandardException;

Modified: db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataType.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataType.java?rev=393570&r1=393569&r2=393570&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataType.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataType.java Wed Apr 12 11:32:59
2006
@@ -993,7 +993,7 @@
 		}
 	}
 
-	public void setValue(InputStream theStream, int streamLength) throws StandardException
+	public void setValue(InputStream theStream, int valueLength) throws StandardException
 	{
 		throwLangSetMismatch("java.io.InputStream");
 	}
@@ -1010,7 +1010,7 @@
 
 
 	/**
-		Return an conversion exception for this type.
+		Return an conversion exception from this type to another.
 	*/
 	protected final StandardException dataTypeConversion(String targetType) {
 		return StandardException.newException(SQLState.LANG_DATA_TYPE_GET_MISMATCH, 

Modified: db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataValueDescriptor.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataValueDescriptor.java?rev=393570&r1=393569&r2=393570&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataValueDescriptor.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataValueDescriptor.java Wed
Apr 12 11:32:59 2006
@@ -759,9 +759,9 @@
 		The format of the stream is required to be the format of this type.
 
 		@param	theStream	stream of correctly formatted data
-		@param	streamLength	logical length of the stream's value in units of this type (e.g. chars
for string types).
+		@param	valueLength	logical length of the stream's value in units of this type (e.g. chars
for string types).
 	*/
-	public void setValue(InputStream theStream, int streamLength) throws StandardException;
+	public void setValue(InputStream theStream, int valueLength) throws StandardException;
 
 	/**
 		Check the value to seem if it conforms to the restrictions

Modified: db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBinary.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBinary.java?rev=393570&r1=393569&r2=393570&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBinary.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBinary.java Wed Apr 12
11:32:59 2006
@@ -111,16 +111,23 @@
 	 */
 	byte[] dataValue;
 
-	/*
-	 * stream state
+	/**
+	 * Value as a stream, this stream represents the on-disk
+     * format of the value. That is it has length information
+     * encoded in the first fe bytes.
 	 */
 	InputStream stream;
 
 	/**
-		Length of the stream in units relevant to the type,
-		in this case bytes.
+		Length of the value in bytes when this value
+        is set as a stream. Represents the length of the
+        value itself and not the length of the stream
+        which contains this length encoded as the first
+        few bytes. If the value of the stream is unknown
+        then this will be set to -1. If this value is
+        not set as a stream then this value should be ignored.
 	*/
-	int streamLength;
+	int streamValueLength;
 
 	/**
 		no-arg constructor, required by Formattable.
@@ -139,7 +146,7 @@
 	{
 		dataValue = theValue;
 		stream = null;
-		streamLength = -1;
+		streamValueLength = -1;
 	}
 
 	/**
@@ -203,7 +210,7 @@
 					readExternal(new FormatIdInputStream(stream));
 				}
 				stream = null;
-				streamLength = -1;
+				streamValueLength = -1;
 
 			}
 		}
@@ -223,8 +230,8 @@
 	{
 		if (stream != null) {
 
-			if (streamLength != -1)
-				return streamLength;
+			if (streamValueLength != -1)
+				return streamValueLength;
 		}
 
 		return (getBytes() == null) ? 0 : getBytes().length;
@@ -283,7 +290,7 @@
 		// need to clear stream first, in case this object is reused, and
 		// stream is set by previous use.  Track 3794.
 		stream = null;
-		streamLength = -1;
+		streamValueLength = -1;
 
 
 		int len = SQLBinary.readBinaryLength(in);
@@ -303,7 +310,7 @@
 		// need to clear stream first, in case this object is reused, and
 		// stream is set by previous use.  Track 3794.
 		stream = null;
-		streamLength = -1;
+		streamValueLength = -1;
 
 		int len = SQLBinary.readBinaryLength(in);
 
@@ -356,7 +363,12 @@
 		return len;
 	}
 
-	private void readFromStream(InputStream in) throws IOException {
+    /**
+     * Read the value from an input stream. The length
+     * encoded in the input stream has already been read
+     * and determined to be unknown.
+     */
+    private void readFromStream(InputStream in) throws IOException {
 
 		dataValue = null;	// allow gc of the old value before the new.
 		byte[] tmpData = new byte[32 * 1024];
@@ -395,7 +407,7 @@
 	{
 		dataValue = null;
 		stream = null;
-		streamLength = -1;
+		streamValueLength = -1;
 	}
 
 	/**
@@ -515,11 +527,18 @@
 		return stream;
 	}
 
+    /**
+     * Set me to the value represented by this stream.
+     * The format of the stream is the on-disk format
+     * described in this class's javadoc. That is the
+     * length is encoded in the first few bytes of the
+     * stream.
+     */
 	public final void setStream(InputStream newStream)
 	{
 		this.dataValue = null;
 		this.stream = newStream;
-		streamLength = -1;
+		streamValueLength = -1;
 	}
 
 	public final void loadStream() throws StandardException
@@ -542,14 +561,15 @@
 	}
 
 	/**
-	 * @see SQLBit#setValue
-	 *
+     * Set the value from the stream which is in the on-disk format.
+     * @param theStream On disk format of the stream
+     * @param valueLength length of the logical value in bytes.
 	 */
-	public final void setValue(InputStream theStream, int streamLength)
+	public final void setValue(InputStream theStream, int valueLength)
 	{
 		dataValue = null;
 		stream = theStream;
-		this.streamLength = streamLength;
+		this.streamValueLength = valueLength;
 	}
 
 	protected final void setFrom(DataValueDescriptor theValue) throws StandardException {
@@ -559,7 +579,7 @@
 			SQLBinary theValueBinary = (SQLBinary) theValue;
 			dataValue = theValueBinary.dataValue;
 			stream = theValueBinary.stream;
-			streamLength = theValueBinary.streamLength;
+			streamValueLength = theValueBinary.streamValueLength;
 		}
 		else
 		{
@@ -969,7 +989,7 @@
 		}
 		else
 		{
-			variableLength = streamLength;
+			variableLength = streamValueLength;
 		}
 
 		if (variableLength != -1 && variableLength > declaredLength)

Modified: db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBlob.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBlob.java?rev=393570&r1=393569&r2=393570&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBlob.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBlob.java Wed Apr 12 11:32:59
2006
@@ -170,7 +170,7 @@
 		throws SQLException
 	{
 			stream = resultSet.getBinaryStream(colNumber);
-			streamLength = -1; // unknown
+			streamValueLength = -1; // unknown
 			dataValue = null;
 	}
 
@@ -210,7 +210,7 @@
         } catch (SQLException e) {
             throw dataTypeConversion("DAN-438-tmp");
        }
-        streamLength = -1; // unknown
+        streamValueLength = -1; // unknown
         dataValue = null;
     }
 }

Modified: db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLChar.java
URL: http://svn.apache.org/viewcvs/db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLChar.java?rev=393570&r1=393569&r2=393570&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLChar.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLChar.java Wed Apr 12 11:32:59
2006
@@ -433,7 +433,10 @@
 		return stream;
 	}
 
-	public void setStream(InputStream newStream)
+    /**
+     * Set this value to the on-disk format stream.
+     */
+	public final void setStream(InputStream newStream)
 	{
 		this.value = null;
 		this.rawLength = -1;
@@ -1178,19 +1181,14 @@
         SQLTime.timeToString( cal.get( Calendar.HOUR), cal.get( Calendar.MINUTE), cal.get(
Calendar.SECOND), sb);
     }
 
-	/**
-	 * @see SQLChar#setValue
-	 *
-	 */
-	public void setValue(InputStream theStream, int streamLength)
+    /**
+     * Set the value from the stream which is in the on-disk format.
+     * @param theStream On disk format of the stream
+     * @param valueLength length of the logical value in characters.
+     */
+	public final void setValue(InputStream theStream, int valueLength)
 	{
-		value = null;
-		rawLength = -1;
-		stream = theStream;
-		// clear out the int array as well, so it will stay current
-		intArray = null;
-		intLength = 0;
-		cKey = null;
+        setStream(theStream);
 	}
 	
 	/**
@@ -2731,10 +2729,11 @@
 
 	// For null strings, cKey = null.
 	private CollationKey cKey; 
-	/*
-	 * stream state
+
+    /**
+	 * The value as a stream in the on-disk format.
 	 */
-	protected InputStream stream;
+	InputStream stream;
 	
 	/* Comparison info for National subclasses) */
 	private int[]	intArray;



Mime
View raw message