Author: kristwaa
Date: Thu Jan 21 10:52:25 2010
New Revision: 901648
URL: http://svn.apache.org/viewvc?rev=901648&view=rev
Log:
DERBY-4515: Document and clarify the use of DataValueDescriptor.setValue(InputStream,int)
Clarified and improved documentation for the setValue method.
Added a constant to represent unknown length.
Rewrote code in EmbedPreparedStatement to remove an unnecessary variable.
Patch file: derby-4515-1a-setValue_stream_clarification.diff
Modified:
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/SQLChar.java
db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedPreparedStatement.java
db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedResultSet.java
Modified: db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataValueDescriptor.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/DataValueDescriptor.java?rev=901648&r1=901647&r2=901648&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 Thu
Jan 21 10:52:25 2010
@@ -95,6 +95,12 @@
public interface DataValueDescriptor extends Storable, Orderable
{
+ /**
+ * Constant indicating that the logical length of a value (i.e. chars for
+ * string types or bytes for binary types) is unknown.
+ */
+ int UNKNOWN_LOGICAL_LENGTH = -1;
+
/**
* Gets the length of the data value. The meaning of this is
* implementation-dependent. For string types, it is the number of
@@ -826,14 +832,24 @@
boolean unknownRV)
throws StandardException;
- /**
- Set the value to be the contents of the stream.
- The reading of the stream may be delayed until execution time.
- The format of the stream is required to be the format of this type.
-
- @param theStream stream of correctly formatted data
- @param valueLength logical length of the stream's value in units of this type (e.g. chars
for string types).
- */
+ /**
+ * Set the value to be the contents of the stream.
+ * <p>
+ * The reading of the stream may be delayed until execution time, and the
+ * format of the stream is required to be the format of this type.
+ * <p>
+ * Note that the logical length excludes any header bytes and marker bytes
+ * (for instance the Derby specific EOF stream marker). Specifying the
+ * logical length may improve performance in some cases, but specifying
+ * that the length is unknown (<code>UNKNOWN_LOGICAL_LENGTH</code> should
+ * always leave the system in a functional state. Specifying an incorrect
+ * length will cause errors.
+ *
+ * @param theStream stream of correctly formatted data
+ * @param valueLength logical length of the stream's value in units of this
+ * type (e.g. chars for string types), or
+ * <code>UNKNOWN_LOGICAL_LENGTH</code> if the logical length is unknown
+ */
public void setValue(InputStream theStream, int valueLength) throws StandardException;
/**
Modified: db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBinary.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLBinary.java?rev=901648&r1=901647&r2=901648&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 Thu Jan 21
10:52:25 2010
@@ -702,8 +702,9 @@
/**
* 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.
- */
+ * @param valueLength length of the logical value in bytes, or
+ * <code>DataValueDescriptor.UNKNOWN_LOGICAL_LENGTH</code>
+ */
public final void setValue(InputStream theStream, int valueLength)
{
dataValue = null;
Modified: db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLChar.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/SQLChar.java?rev=901648&r1=901647&r2=901648&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 Thu Jan 21 10:52:25
2010
@@ -1613,7 +1613,8 @@
/**
* 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.
+ * @param valueLength length of the logical value in characters, or
+ * <code>DataValueDescriptor.UNKNOWN_LOGICAL_LENGTH</code>
*/
public final void setValue(InputStream theStream, int valueLength)
{
Modified: db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedPreparedStatement.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedPreparedStatement.java?rev=901648&r1=901647&r2=901648&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedPreparedStatement.java
(original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedPreparedStatement.java
Thu Jan 21 10:52:25 2010
@@ -748,19 +748,16 @@
DataTypeDescriptor dtd[] = preparedStatement
.getParameterTypes();
int colWidth = dtd[parameterIndex - 1].getMaximumWidth();
- // Default to max column width. This will be used to limit the
- // amount of data read when operating on "lengthless" streams.
- int usableLength = colWidth;
+ // Holds either UNKNOWN_LOGICAL_LENGTH or the exact logical length.
+ int usableLength = DataValueDescriptor.UNKNOWN_LOGICAL_LENGTH;
if (!lengthLess) {
// We cast the length from long to int. This wouldn't be
// appropriate if the limit of 2G-1 is decided to be increased
// at a later stage.
- int intLength = (int)length;
+ usableLength = (int)length;
int truncationLength = 0;
- usableLength = intLength;
-
// Currently long varchar does not allow for truncation of
// trailing blanks.
// For char and varchar types, current mechanism of
@@ -781,11 +778,9 @@
// usableLength is the length of the data from stream that
// can be inserted which is min(colWidth,length) provided
// length - colWidth has trailing blanks only
- // we have used intLength into which the length variable had
- // been cast to an int and stored
- if (intLength > colWidth) {
+ if (usableLength > colWidth) {
+ truncationLength = usableLength - colWidth;
usableLength = colWidth;
- truncationLength = intLength - usableLength;
}
}
// Create a stream with truncation.
@@ -925,8 +920,8 @@
try {
RawToBinaryFormatStream rawStream;
if (lengthLess) {
- // Force length to -1 for good measure.
- length = -1;
+ // Indicate that we don't know the logical length of the stream.
+ length = DataValueDescriptor.UNKNOWN_LOGICAL_LENGTH;
DataTypeDescriptor dtd[] =
preparedStatement.getParameterTypes();
rawStream = new RawToBinaryFormatStream(x,
Modified: db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedResultSet.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedResultSet.java?rev=901648&r1=901647&r2=901648&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedResultSet.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedResultSet.java Thu Jan
21 10:52:25 2010
@@ -2828,8 +2828,8 @@
}
rawStream = new RawToBinaryFormatStream(x, (int)length);
} else {
- // Force length to -1 if stream is length less.
- length = -1;
+ // Force length to UNKNOWN_LOGICAL_LENGTH if stream is length less.
+ length = DataValueDescriptor.UNKNOWN_LOGICAL_LENGTH;
rawStream = new RawToBinaryFormatStream(x,
getMaxColumnWidth(columnIndex),
getColumnSQLType(columnIndex));
@@ -2936,7 +2936,7 @@
!getEmbedConnection().getDatabase().getDataDictionary().
checkVersion(DataDictionary.DD_VERSION_CURRENT, null)));
ReaderToUTF8Stream utfIn;
- int usableLength = -1;
+ int usableLength = DataValueDescriptor.UNKNOWN_LOGICAL_LENGTH;
if (!lengthLess) {
// check for -ve length here
if (length < 0)
@@ -2993,8 +2993,6 @@
dvd.getStreamHeaderGenerator());
}
- // NOTE: The length argument to setValue is not used. If that
- // changes, the value might also have to change.
dvd.setValue(utfIn, usableLength);
} catch (StandardException t) {
throw noStateChangeException(t);
|