Class SQLChar
- All Implemented Interfaces:
Externalizable
,Serializable
,Comparable
,Formatable
,Storable
,StreamStorable
,TypedFormat
,ConcatableDataValue
,DataValueDescriptor
,Orderable
,StringDataValue
,VariableSizeDataValue
- Direct Known Subclasses:
CollatorSQLChar
,SQLVarchar
The state may be in char[], a String, a Clob, or an unread stream, depending on how the datatype was created.
Stream notes:
When the datatype comes from the database layer and the length of the bytes necessary to store the datatype on disk exceeds the size of a page of the container holding the data then the store returns a stream rather than reading all the bytes into a char[] or String. The hope is that the usual usage case is that data never need be expanded in the derby layer, and that client can just be given a stream that can be read a char at a time through the jdbc layer. Even though SQLchar's can't ever be this big, this code is shared by all the various character datatypes including SQLClob which is expected to usually larger than a page.
The state can also be a stream in the case of insert/update where the client has used a jdbc interface to set the value as a stream rather than char[]. In this case the hope is that the usual usage case is that stream never need be read until it is passed to store, read once, and inserted into the database.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected Clob
The value as a user-created Clob(package private) char[][]
private static final int
private static final char[]
Static array that can be used for blank padding.protected static final StreamHeaderGenerator
Stream header generator for CHAR, VARCHAR and LONG VARCHAR.private CollationKey
private static final int
when we know that the array needs to grow by at least one byte, it is not performant to grow by just one byte instead this amount is used to provide a reasonable growby size.private LocaleFinder
private static final char
The pad character (space).private char[]
private int
protected static final int
threshold, that decides when we return space back to the VM see getString() where it is used(package private) InputStream
The value as a stream in the on-disk format.private String
Fields of the classFields inherited from interface org.apache.derby.iapi.types.DataValueDescriptor
UNKNOWN_LOGICAL_LENGTH
Fields inherited from interface org.apache.derby.iapi.types.Orderable
ORDER_OP_EQUALS, ORDER_OP_GREATEROREQUALS, ORDER_OP_GREATERTHAN, ORDER_OP_LESSOREQUALS, ORDER_OP_LESSTHAN
Fields inherited from interface org.apache.derby.iapi.types.StringDataValue
BOTH, COLLATION_DERIVATION_EXPLICIT, COLLATION_DERIVATION_IMPLICIT, COLLATION_DERIVATION_NONE, COLLATION_TYPE_TERRITORY_BASED, COLLATION_TYPE_TERRITORY_BASED_IDENTICAL, COLLATION_TYPE_TERRITORY_BASED_PRIMARY, COLLATION_TYPE_TERRITORY_BASED_SECONDARY, COLLATION_TYPE_TERRITORY_BASED_TERTIARY, COLLATION_TYPE_UCS_BASIC, LEADING, TRAILING
Fields inherited from interface org.apache.derby.iapi.types.VariableSizeDataValue
IGNORE_PRECISION
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionansiTrim
(int trimType, StringDataValue trimChar, StringDataValue result) The SQL Ansi trim function.private static void
appendBlanks
(char[] ca, int offset, int howMany) Private/Protected methods of This class:charLength
(NumberDataValue result) This method implements the char_length function for char.Shallow clone a StreamStorable without objectifying.cloneValue
(boolean forceMaterialization) Clone this DataValueDescriptor.boolean
compare
(int op, DataValueDescriptor other, boolean orderedNulls, boolean unknownRV) Compare this Orderable with a given Orderable for the purpose of qualification and sorting.int
compare
(DataValueDescriptor other) Compare this Orderable with a given Orderable for the purpose of index positioning.concatenate
(StringDataValue leftOperand, StringDataValue rightOperand, StringDataValue result) The SQL concatenation '||' operator.private void
copyState
(String otherValue, char[] otherRawData, int otherRawLength, CollationKey otherCKey, InputStream otherStream, Clob otherClobValue, LocaleFinder otherLocaleFinder) protected void
equals
(DataValueDescriptor left, DataValueDescriptor right) The = operator as called from the language module, as opposed to the storage module.int
Estimate the memory usage in bytes of the data value and the overhead of the class.private void
formatJDBCDate
(Calendar cal, StringBuffer sb) private void
formatJDBCTime
(Calendar cal, StringBuffer sb) boolean
Get Boolean from a SQLChar.byte
getByte()
Get Byte from a SQLChar.char[]
Get a char array.private int
protected CollationKey
This method gets called for the collation sensitive char classes ie CollatorSQLChar, CollatorSQLVarchar, CollatorSQLLongvarchar, CollatorSQLClob.protected RuleBasedCollator
Get date from a SQLChar.static Date
getDate
(Calendar cal, String str, LocaleFinder localeFinder) Static function to Get date from a string.double
Get double from a SQLChar.float
getFloat()
Get float from a SQLChar.int
getInt()
Get int from a SQLChar.int
Gets the length of the data value.private Locale
protected LocaleFinder
long
getLong()
Get long from a SQLChar.Get a new null value of the same type as this data value.protected StringDataValue
Get a SQLVarchar for a built-in string function.Gets the value in the data value descriptor as a int.char[]
This is a special accessor used when we wrap passwords in VARCHARs.short
getShort()
Get Short from a SQLChar.Gets the value in the data stream descriptor as an InputStream.Returns the default stream header generator for the string data types.Returns a descriptor for the input stream for this character data value.If possible, use getCharArray() if you don't really need a string.Get time from a SQLChar.static Time
getTime
(Calendar cal, String str, LocaleFinder localeFinder) Static function to Get Time from a string.getTimestamp
(Calendar cal) Get Timestamp from a SQLChar.static Timestamp
getTimestamp
(Calendar cal, String str, LocaleFinder localeFinder) Static function to Get Timestamp from a string.Gets a trace representation for debugging.int
Return my format identifier.Get the SQL name of the datatypeprivate int
getUTF8Length
(String string, int start, int end) Get the number of bytes needed to represent a string in modified UTF-8, which is the encoding used bywriteExternal()
andwriteUTF()
.getValue
(RuleBasedCollator collatorForComparison) Gets either SQLChar/SQLVarchar/SQLLongvarchar/SQLClob(base classes) or CollatorSQLChar/CollatorSQLVarchar/CollatorSQLLongvarch/CollatorSQLClob (subclasses).greaterOrEquals
(DataValueDescriptor left, DataValueDescriptor right) The >= operator as called from the language module, as opposed to the storage module.greaterThan
(DataValueDescriptor left, DataValueDescriptor right) The > operator as called from the language module, as opposed to the storage module.protected int
growBy()
returns the reasonable minimum amount by which the array can grow .int
hashCode()
(package private) int
Hash code implementation for collator sensitive subclasses.protected final void
hasNonBlankChars
(String source, int start, int end) boolean
isNull()
see if the String value is null.lessOrEquals
(DataValueDescriptor left, DataValueDescriptor right) The <= operator as called from the language module, as opposed to the storage module.lessThan
(DataValueDescriptor left, DataValueDescriptor right) The < operator as called from the language module, as opposed to the storage module.like
(DataValueDescriptor pattern) This method implements the like function for char (with no escape value).like
(DataValueDescriptor pattern, DataValueDescriptor escape) This method implements the like function for char with an escape value.void
Set the value by reading the stream and converting it to an object form.locate
(StringDataValue searchFrom, NumberDataValue start, NumberDataValue result) This method implements the locate function for char.lower
(StringDataValue result) Convert the string to lower case.protected void
normalize
(DataTypeDescriptor desiredType, String sourceValue) void
normalize
(DataTypeDescriptor desiredType, DataValueDescriptor source) Normalization method - this method may be called when putting a value into a SQLChar, for example, when inserting into a SQLChar column.notEquals
(DataValueDescriptor left, DataValueDescriptor right) The <> operator as called from the language module, as opposed to the storage module.private int
void
protected void
readExternal
(ObjectInput in, int utflen, int knownStrLen) Restores the data value from the source stream, materializing the value in memory.protected void
readExternalClobFromArray
(ArrayInputStream in, int charLen) Reads a CLOB from the source stream and materializes the value in a character array.void
Reads in a string from the specified data input stream.private void
Resets state after materializing value from an array.void
Restore this object to its (SQL)null value.Public Methods of StreamStorable interface:void
setBigDecimal
(BigDecimal bigDecimal) Only to be called when an application through JDBC is setting a SQLChar to a java.math.BigDecimal.protected void
setFrom
(DataValueDescriptor theValue) Set the value of this DataValueDescriptor based on the value of the specified DataValueDescriptor.final void
setInto
(PreparedStatement ps, int position) Set the value into a PreparedStatement.protected void
setLocaleFinder
(LocaleFinder localeFinder) void
setObjectForCast
(Object theValue, boolean instanceOfResultType, String resultTypeClassName) Allow any Java type to be cast to a character type using Object.toString.void
setStream
(InputStream newStream) Set this value to the on-disk format stream.void
setStreamHeaderFormat
(Boolean inSoftUpgradeMode) Sets the mode for the database being accessed.void
setValue
(boolean theValue) Set the value.void
setValue
(byte theValue) Set the value of this DataValueDescriptor to the given byte value At DataType level just throws an error lower classes will overridevoid
setValue
(byte[] theValue) Set the value of this DataValueDescriptor.void
setValue
(double theValue) Set the value of this DataValueDescriptor to the given double value At DataType level just throws an error lower classes will overridevoid
setValue
(float theValue) Set the value of this DataValueDescriptor to the given float value At DataType level just throws an error lower classes will overridevoid
setValue
(int theValue) Set the value of this DataValueDescriptor to the given int value At DataType level just throws an error lower classes will overridevoid
setValue
(long theValue) Set the value of this DataValueDescriptor to the given long value At DataType level just throws an error lower classes will overridevoid
setValue
(short theValue) Set the value of this DataValueDescriptor to the given short value At DataType level just throws an error lower classes will overridefinal void
setValue
(InputStream theStream, int valueLength) Set the value from the stream which is in the on-disk format.void
Set the value of this DataValueDescriptor.void
Set the value of this DataValueDescriptor.void
Set the value of this DataValueDescriptor.void
Set the value of this DataValueDescriptor.void
Set the value of this DataValueDescriptor.final void
setValueFromResultSet
(ResultSet resultSet, int colNumber, boolean isNullable) Set the value based on the value for the specified DataValueDescriptor from the specified ResultSet.void
setWidth
(int desiredWidth, int desiredScale, boolean errorOnTrunc) Set the width of the to the desired value.protected static int
stringCompare
(char[] op1, int leftlen, char[] op2, int rightlen) Compare two Strings using standard SQL semantics.protected static int
stringCompare
(String op1, String op2) Compare two Strings using standard SQL semantics.protected int
stringCompare
(SQLChar char1, SQLChar char2) Compare two SQLChars.substring
(NumberDataValue start, NumberDataValue length, ConcatableDataValue result, int maxLen) The SQL substr() function.protected void
Wraps anIOException
in aStandardException
then throws the wrapping exception.toString()
private String
trimInternal
(int trimType, char trimChar, String source) This function public for testing purposes.int
Each built-in type in JSQL has a precedence.int
CHAR/VARCHAR/LONG VARCHAR implementation.upper
(StringDataValue result) Convert the string to upper case.protected final void
writeClobUTF
(ObjectOutput out) Writes the header and the user data for a CLOB to the destination stream.void
Writes a non-Clob data value to the modified UTF-8 format used by Derby.private static void
writeUTF
(ObjectOutput out, int c) Write a single character to a stream in the modified UTF-8 format.private final void
writeUTF
(ObjectOutput out, int strLen, boolean isRaw, Reader characterReader) Writes the user data value to a stream in the modified UTF-8 format.void
Zero out the wrapped char[] so that it can't be memory-sniffed.Methods inherited from class org.apache.derby.iapi.types.DataType
checkHostVariable, coalesce, compare, compare, compareTo, dataTypeConversion, equals, flip, genericSetObject, getBytes, getTypeName, hasStream, in, invalidFormat, isNotNull, isNullOp, outOfRange, recycle, setInto, setObject, setToNull, setValue, setValue, setValue, setValue, setValue, setValue, throwLangSetMismatch, throwLangSetMismatch
-
Field Details
-
PAD
private static final char PADThe pad character (space).- See Also:
-
RETURN_SPACE_THRESHOLD
protected static final int RETURN_SPACE_THRESHOLDthreshold, that decides when we return space back to the VM see getString() where it is used- See Also:
-
GROWBY_FOR_CHAR
private static final int GROWBY_FOR_CHARwhen we know that the array needs to grow by at least one byte, it is not performant to grow by just one byte instead this amount is used to provide a reasonable growby size.- See Also:
-
BASE_MEMORY_USAGE
private static final int BASE_MEMORY_USAGE -
BLANKS
private static final char[] BLANKSStatic array that can be used for blank padding. -
CHAR_HEADER_GENERATOR
Stream header generator for CHAR, VARCHAR and LONG VARCHAR. Currently, only one header format is used for these data types. -
value
Fields of the class -
rawData
private char[] rawData -
rawLength
private int rawLength -
cKey
-
_clobValue
The value as a user-created Clob -
stream
InputStream streamThe value as a stream in the on-disk format. -
localeFinder
-
arg_passer
char[][] arg_passer
-
-
Constructor Details
-
SQLChar
public SQLChar()no-arg constructor, required by Formattable. -
SQLChar
-
SQLChar
-
SQLChar
public SQLChar(char[] val) This is a special constructor used when we need to represent a password as a VARCHAR (see DERBY-866). If you need a general-purpose constructor for char[] values and you want to re-use this constructor, make sure to keep track of the following:
- A password should never be turned into a String. This is because Java garbage collection makes it easy to sniff memory for String passwords. For more information, see this blog.
- It must be possible to 0 out the char[] array wrapped inside this SQLChar. This reduces the vulnerability that someone could sniff the char[] password after Derby has processed it.
-
-
Method Details
-
appendBlanks
private static void appendBlanks(char[] ca, int offset, int howMany) Private/Protected methods of This class: -
getRawDataAndZeroIt
public char[] getRawDataAndZeroIt()This is a special accessor used when we wrap passwords in VARCHARs. This accessor copies the wrapped char[] and then fills it with 0s so that the password can't be memory-sniffed. For more information, see the comment on the SQLChar( char[] ) constructor.
-
zeroRawData
public void zeroRawData()Zero out the wrapped char[] so that it can't be memory-sniffed. This helps us protect passwords. See the comment on the SQLChar( char[] ) constructor.
-
getBoolean
Get Boolean from a SQLChar.Return false for only "0" or "false" for false. No case insensitivity. Everything else is true.
The above matches JCC and the client driver.
- Specified by:
getBoolean
in interfaceDataValueDescriptor
- Overrides:
getBoolean
in classDataType
- Returns:
- The data value as a boolean.
- Throws:
StandardException
- Thrown on error- See Also:
-
getByte
Get Byte from a SQLChar.Uses java standard Byte.parseByte() to perform coercion.
- Specified by:
getByte
in interfaceDataValueDescriptor
- Overrides:
getByte
in classDataType
- Returns:
- The data value as a byte.
- Throws:
StandardException
- thrown on failure to convert- See Also:
-
getShort
Get Short from a SQLChar.Uses java standard Short.parseShort() to perform coercion.
- Specified by:
getShort
in interfaceDataValueDescriptor
- Overrides:
getShort
in classDataType
- Returns:
- The data value as a short.
- Throws:
StandardException
- thrown on failure to convert- See Also:
-
getInt
Get int from a SQLChar.Uses java standard Short.parseInt() to perform coercion.
- Specified by:
getInt
in interfaceDataValueDescriptor
- Overrides:
getInt
in classDataType
- Returns:
- The data value as a int.
- Throws:
StandardException
- thrown on failure to convert- See Also:
-
getLong
Get long from a SQLChar.Uses java standard Short.parseLong() to perform coercion.
- Specified by:
getLong
in interfaceDataValueDescriptor
- Overrides:
getLong
in classDataType
- Returns:
- The data value as a long.
- Throws:
StandardException
- thrown on failure to convert- See Also:
-
getFloat
Get float from a SQLChar.Uses java standard Float.floatValue() to perform coercion.
- Specified by:
getFloat
in interfaceDataValueDescriptor
- Overrides:
getFloat
in classDataType
- Returns:
- The data value as a float.
- Throws:
StandardException
- thrown on failure to convert- See Also:
-
getDouble
Get double from a SQLChar.Uses java standard Double.doubleValue() to perform coercion.
- Specified by:
getDouble
in interfaceDataValueDescriptor
- Overrides:
getDouble
in classDataType
- Returns:
- The data value as a double.
- Throws:
StandardException
- thrown on failure to convert- See Also:
-
getDate
Get date from a SQLChar.- Specified by:
getDate
in interfaceDataValueDescriptor
- Overrides:
getDate
in classDataType
- Parameters:
cal
- calendar for object creation- Returns:
- The data value as a java.sql.Date.
- Throws:
StandardException
- thrown on failure to convert- See Also:
-
getDate
public static Date getDate(Calendar cal, String str, LocaleFinder localeFinder) throws StandardException Static function to Get date from a string.- Throws:
StandardException
- thrown on failure to convert- See Also:
-
getTime
Get time from a SQLChar.- Specified by:
getTime
in interfaceDataValueDescriptor
- Overrides:
getTime
in classDataType
- Parameters:
cal
- calendar for object creation- Returns:
- The data value as a java.sql.Time.
- Throws:
StandardException
- thrown on failure to convert- See Also:
-
getTime
public static Time getTime(Calendar cal, String str, LocaleFinder localeFinder) throws StandardException Static function to Get Time from a string.- Throws:
StandardException
- thrown on failure to convert- See Also:
-
getTimestamp
Get Timestamp from a SQLChar.- Specified by:
getTimestamp
in interfaceDataValueDescriptor
- Overrides:
getTimestamp
in classDataType
- Parameters:
cal
- calendar for object creation- Returns:
- The data value as a java.sql.Timestamp.
- Throws:
StandardException
- thrown on failure to convert- See Also:
-
getTimestamp
public static Timestamp getTimestamp(Calendar cal, String str, LocaleFinder localeFinder) throws StandardException Static function to Get Timestamp from a string.- Throws:
StandardException
- thrown on failure to convert- See Also:
-
returnStream
Public Methods of StreamStorable interface:- Specified by:
returnStream
in interfaceStreamStorable
-
setStream
Set this value to the on-disk format stream.- Specified by:
setStream
in interfaceStreamStorable
-
loadStream
Description copied from interface:StreamStorable
Set the value by reading the stream and converting it to an object form.- Specified by:
loadStream
in interfaceStreamStorable
- Throws:
StandardException
- on error
-
getObject
Description copied from class:DataType
Gets the value in the data value descriptor as a int. Throws an exception if the data value is not receivable as a int.- Specified by:
getObject
in interfaceDataValueDescriptor
- Overrides:
getObject
in classDataType
- Returns:
- The data value as a int.
- Throws:
StandardException
- Thrown on error
-
getStream
Description copied from class:DataType
Gets the value in the data stream descriptor as an InputStream. Throws an exception if the data value is not receivable as a stream.- Specified by:
getStream
in interfaceDataValueDescriptor
- Overrides:
getStream
in classDataType
- Returns:
- The data value as an InputStream.
- Throws:
StandardException
- Thrown on error- See Also:
-
getStreamWithDescriptor
Returns a descriptor for the input stream for this character data value.- Specified by:
getStreamWithDescriptor
in interfaceStringDataValue
- Returns:
- Nothing, throws exception.
- Throws:
StandardException
- if the value isn't represented by a stream- See Also:
-
typeToBigDecimal
CHAR/VARCHAR/LONG VARCHAR implementation. Convert to a BigDecimal using getString.- Specified by:
typeToBigDecimal
in interfaceDataValueDescriptor
- Overrides:
typeToBigDecimal
in classDataType
- Returns:
- Types.CHAR for String conversion through getString Types.DECIMAL for BigDecimal through getObject or Types.BIGINT for long conversion through getLong
- Throws:
StandardException
- Conversion is not possible
-
getLength
Description copied from interface:DataValueDescriptor
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.- Specified by:
getLength
in interfaceDataValueDescriptor
- Returns:
- The length of the data value
- Throws:
StandardException
- Thrown on error
-
throwStreamingIOException
Wraps anIOException
in aStandardException
then throws the wrapping exception.- Parameters:
ioe
- theIOException
to wrap- Throws:
StandardException
- the wrapping exception
-
getTypeName
Description copied from interface:DataValueDescriptor
Get the SQL name of the datatype- Specified by:
getTypeName
in interfaceDataValueDescriptor
- Returns:
- The SQL name of the datatype
-
getString
If possible, use getCharArray() if you don't really need a string. getString() will cause an extra char array to be allocated when it calls the the String() constructor (the first time through), so may be cheaper to use getCharArray().- Specified by:
getString
in interfaceDataValueDescriptor
- Returns:
- The data value as a String.
- Throws:
StandardException
- Thrown on error
-
getCharArray
Get a char array. Typically, this is a simple getter that is cheaper than getString() because we always need to create a char array when doing I/O. Use this instead of getString() where reasonable.WARNING: may return a character array that has spare characters at the end. MUST be used in conjunction with getLength() to be safe.
- Specified by:
getCharArray
in interfaceStringDataValue
- Throws:
StandardException
- Thrown on error
-
getTypeFormatId
public int getTypeFormatId()Return my format identifier.- Specified by:
getTypeFormatId
in interfaceTypedFormat
- Returns:
- The identifier. (A UUID stuffed in an array of 16 bytes).
- See Also:
-
isNull
public boolean isNull()see if the String value is null. -
writeExternal
Writes a non-Clob data value to the modified UTF-8 format used by Derby. The maximum stored size is based upon the UTF format used to stored the String. The format consists of a two byte length field and a maximum number of three bytes for each character.
This puts an upper limit on the length of a stored String. The maximum stored length is 65535, these leads to the worse case of a maximum string length of 21844 ((65535 - 2) / 3).
Strings with stored length longer than 64K is handled with the following format: (1) 2 byte length: will be assigned 0. (2) UTF formated string data. (3) terminate the string with the following 3 bytes: first byte is: +---+---+---+---+---+---+---+---+ | 1 | 1 | 1 | 0 | 0 | 0 | 0 | 0 | +---+---+---+---+---+---+---+---+ second byte is: +---+---+---+---+---+---+---+---+ | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | +---+---+---+---+---+---+---+---+ third byte is: +---+---+---+---+---+---+---+---+ | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | +---+---+---+---+---+---+---+---+ The UTF format: Writes a string to the underlying output stream using UTF-8 encoding in a machine-independent manner.First, two bytes are written to the output stream as if by the
writeShort
method giving the number of bytes to follow. This value is the number of bytes actually written out, not the length of the string. Following the length, each character of the string is output, in sequence, using the UTF-8 encoding for the character.- Specified by:
writeExternal
in interfaceExternalizable
- Throws:
IOException
- if an I/O error occurs.- Since:
- JDK1.0
- See Also:
-
writeUTF
private final void writeUTF(ObjectOutput out, int strLen, boolean isRaw, Reader characterReader) throws IOException Writes the user data value to a stream in the modified UTF-8 format.- Parameters:
out
- destination streamstrLen
- string length of the valueisRaw
-true
if the source israwData
,false
if the source isvalue
characterReader
- Reader from _clobValue if it exists- Throws:
IOException
- if writing to the destination stream fails
-
writeUTF
Write a single character to a stream in the modified UTF-8 format.- Parameters:
out
- the destination streamc
- the character to write- Throws:
IOException
- if writing to the destination stream fails
-
writeClobUTF
Writes the header and the user data for a CLOB to the destination stream.- Parameters:
out
- destination stream- Throws:
IOException
- if writing to the destination stream fails
-
readExternalFromArray
Reads in a string from the specified data input stream. The string has been encoded using a modified UTF-8 format.The first two bytes are read as if by
readUnsignedShort
. This value gives the number of following bytes that are in the encoded string, not the length of the resulting string. The following bytes are then interpreted as bytes encoding characters in the UTF-8 format and are converted into characters.This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.
- Specified by:
readExternalFromArray
in interfaceDataValueDescriptor
- Overrides:
readExternalFromArray
in classDataType
- Parameters:
in
- a data input stream.- Throws:
EOFException
- if the input stream reaches the end before all the bytes.IOException
- if an I/O error occurs.UTFDataFormatException
- if the bytes do not represent a valid UTF-8 encoding of a Unicode string.- See Also:
-
readExternalClobFromArray
Reads a CLOB from the source stream and materializes the value in a character array.- Parameters:
in
- source streamcharLen
- the char length of the value, or0
if unknown- Throws:
IOException
- if reading from the source fails
-
resetForMaterialization
private void resetForMaterialization()Resets state after materializing value from an array. -
readExternal
- Specified by:
readExternal
in interfaceExternalizable
- Throws:
IOException
-
readExternal
Restores the data value from the source stream, materializing the value in memory.- Parameters:
in
- the source streamutflen
- the byte length, or0
if unknownknownStrLen
- the char length, or0
if unknown- Throws:
UTFDataFormatException
- if an encoding error is detectedIOException
- if reading the stream fails
-
growBy
protected int growBy()returns the reasonable minimum amount by which the array can grow . See readExternal. when we know that the array needs to grow by at least one byte, it is not performant to grow by just one byte instead this amount is used to provide a resonable growby size.- Returns:
- minimum reasonable growby size
-
restoreToNull
public void restoreToNull()Description copied from interface:Storable
Restore this object to its (SQL)null value.- Specified by:
restoreToNull
in interfaceStorable
- See Also:
-
compare
public boolean compare(int op, DataValueDescriptor other, boolean orderedNulls, boolean unknownRV) throws StandardException Description copied from interface:DataValueDescriptor
Compare this Orderable with a given Orderable for the purpose of qualification and sorting. The caller gets to determine how nulls should be treated - they can either be ordered values or unknown values.- Specified by:
compare
in interfaceDataValueDescriptor
- Overrides:
compare
in classDataType
- Parameters:
op
- Orderable.ORDER_OP_EQUALS means do an = comparison. Orderable.ORDER_OP_LESSTHAN means compare this < other. Orderable.ORDER_OP_LESSOREQUALS means compare this <= other.other
- The DataValueDescriptor to compare this one to.orderedNulls
- True means to treat nulls as ordered values, that is, treat SQL null as equal to null, and less than all other values. False means to treat nulls as unknown values, that is, the result of any comparison with a null is the UNKNOWN truth value.unknownRV
- The return value to use if the result of the comparison is the UNKNOWN truth value. In other words, if orderedNulls is false, and a null is involved in the comparison, return unknownRV. This parameter is not used orderedNulls is true.- Returns:
- true if the comparison is true (duh!)
- Throws:
StandardException
- thrown on error
-
compare
Description copied from interface:DataValueDescriptor
Compare this Orderable with a given Orderable for the purpose of index positioning. This method treats nulls as ordered values - that is, it treats SQL null as equal to null and greater than all other values.- Specified by:
compare
in interfaceDataValueDescriptor
- Parameters:
other
- The Orderable to compare this one to.- Returns:
- <0 - this Orderable is less than other. 0 - this Orderable equals other. >0 - this Orderable is greater than other. The code should not explicitly look for -1, or 1.
- Throws:
StandardException
- thrown on error
-
cloneHolder
Shallow clone a StreamStorable without objectifying. This is used to avoid unnecessary objectifying of a stream object. The only difference of this method from cloneValue is this method does not objectify a stream.- Specified by:
cloneHolder
in interfaceDataValueDescriptor
- Overrides:
cloneHolder
in classDataType
- Returns:
- A shallow clone.
-
cloneValue
Description copied from interface:DataValueDescriptor
Clone this DataValueDescriptor. Results in a new object that has the same value as this but can be modified independently.Even though the objects can be modified independently regardless of the value of
forceMaterialization
, both the clone and the original may be dependent on the store state ifforceMaterialization
is set tofalse
. An example is if you need to access the value you just read usingcloneValue
after the current transaction has ended, or after the source result set has been closed.- Specified by:
cloneValue
in interfaceDataValueDescriptor
- Parameters:
forceMaterialization
- any streams representing the data value will be materialized iftrue
, the data value will be kept as a stream if possible iffalse
- Returns:
- A clone of the
DataValueDescriptor
with the same initial value as this. - See Also:
-
getNewNull
Description copied from interface:DataValueDescriptor
Get a new null value of the same type as this data value.- Specified by:
getNewNull
in interfaceDataValueDescriptor
- See Also:
-
getValue
Description copied from interface:StringDataValue
Gets either SQLChar/SQLVarchar/SQLLongvarchar/SQLClob(base classes) or CollatorSQLChar/CollatorSQLVarchar/CollatorSQLLongvarch/CollatorSQLClob (subclasses). Whether this method returns the base class or the subclass depends on the value of the RuleBasedCollator. If RuleBasedCollator is null, then the object returned would be baseclass otherwise it would be subcalss.- Specified by:
getValue
in interfaceStringDataValue
- See Also:
-
setValueFromResultSet
public final void setValueFromResultSet(ResultSet resultSet, int colNumber, boolean isNullable) throws SQLException Description copied from interface:DataValueDescriptor
Set the value based on the value for the specified DataValueDescriptor from the specified ResultSet.- Specified by:
setValueFromResultSet
in interfaceDataValueDescriptor
- Parameters:
resultSet
- The specified ResultSet.colNumber
- The 1-based column # into the resultSet.isNullable
- Whether or not the column is nullable (No need to call wasNull() if not)- Throws:
SQLException
- Thrown on error- See Also:
-
setInto
public final void setInto(PreparedStatement ps, int position) throws SQLException, StandardException Set the value into a PreparedStatement.- Specified by:
setInto
in interfaceDataValueDescriptor
- Overrides:
setInto
in classDataType
- Throws:
SQLException
- thrown by the PreparedStatement objectStandardException
- thrown by me accessing my value.
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Specified by:
setValue
in interfaceStringDataValue
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The Clob value to set this DataValueDescriptor to
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The BigDecimal value to set this DataValueDescriptor to
-
setValue
Description copied from class:DataType
Set the value. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- Contains the boolean value to set this to- Throws:
StandardException
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor to the given int value At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The value to set this DataValueDescriptor to- Throws:
StandardException
- Thrown on error
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor to the given double value At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The value to set this DataValueDescriptor to- Throws:
StandardException
- Thrown on error
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor to the given float value At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The value to set this DataValueDescriptor to- Throws:
StandardException
- Thrown on error
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor to the given short value At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The value to set this DataValueDescriptor to- Throws:
StandardException
- Thrown on error
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor to the given long value At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The value to set this DataValueDescriptor to- Throws:
StandardException
- Thrown on error
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor to the given byte value At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The value to set this DataValueDescriptor to- Throws:
StandardException
- Thrown on error
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The byte value to set this DataValueDescriptor to- Throws:
StandardException
-
setBigDecimal
Only to be called when an application through JDBC is setting a SQLChar to a java.math.BigDecimal.- Specified by:
setBigDecimal
in interfaceDataValueDescriptor
- Overrides:
setBigDecimal
in classDataType
- Parameters:
bigDecimal
- required to be a BigDecimal or null.- Throws:
StandardException
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The Date value to set this DataValueDescriptor tocal
- The time zone from the calendar is used to construct the database date value- Throws:
StandardException
- Thrown on error
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The Time value to set this DataValueDescriptor tocal
- The time zone from the calendar is used to construct the database time value- Throws:
StandardException
- Thrown on error
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The Timestamp value to set this DataValueDescriptor tocal
- The time zone from the calendar is used to construct the database timestamp value- Throws:
StandardException
- Thrown on error
-
formatJDBCDate
-
formatJDBCTime
-
setValue
Set the value from the stream which is in the on-disk format.- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theStream
- On disk format of the streamvalueLength
- length of the logical value in characters, orDataValueDescriptor.UNKNOWN_LOGICAL_LENGTH
-
setObjectForCast
public void setObjectForCast(Object theValue, boolean instanceOfResultType, String resultTypeClassName) throws StandardException Allow any Java type to be cast to a character type using Object.toString.- Specified by:
setObjectForCast
in interfaceDataValueDescriptor
- Overrides:
setObjectForCast
in classDataType
- Parameters:
theValue
- The new valueinstanceOfResultType
- Whether or not the new value is an instanceof the result type.resultTypeClassName
- The class name of the resulting (declared) type (for error messages only).- Throws:
StandardException
- thrown on failure- See Also:
-
setFrom
Description copied from class:DataType
Set the value of this DataValueDescriptor based on the value of the specified DataValueDescriptor.- Overrides:
setFrom
in classDataType
- Parameters:
theValue
- The DataValueDescriptor that holds the value to which we want to set this DataValueDescriptor's value.- Throws:
StandardException
-
normalize
public void normalize(DataTypeDescriptor desiredType, DataValueDescriptor source) throws StandardException Normalization method - this method may be called when putting a value into a SQLChar, for example, when inserting into a SQLChar column. See NormalizeResultSet in execution.- Specified by:
normalize
in interfaceDataValueDescriptor
- Overrides:
normalize
in classDataType
- Parameters:
desiredType
- The type to normalize the source column tosource
- The value to normalize- Throws:
StandardException
- Thrown for null into non-nullable column, and for truncation error
-
normalize
protected void normalize(DataTypeDescriptor desiredType, String sourceValue) throws StandardException - Throws:
StandardException
-
hasNonBlankChars
- Throws:
StandardException
-
setWidth
public void setWidth(int desiredWidth, int desiredScale, boolean errorOnTrunc) throws StandardException Set the width of the to the desired value. Used when CASTing. Ideally we'd recycle normalize(), but the behavior is different (we issue a warning instead of an error, and we aren't interested in nullability).- Specified by:
setWidth
in interfaceVariableSizeDataValue
- Parameters:
desiredWidth
- the desired lengthdesiredScale
- the desired scale (ignored)errorOnTrunc
- throw an error on truncation- Throws:
StandardException
- Thrown when errorOnTrunc is true and when a shrink will truncate non-white spaces.
-
getUTF8Length
Get the number of bytes needed to represent a string in modified UTF-8, which is the encoding used bywriteExternal()
andwriteUTF()
.- Parameters:
string
- the string whose length to calculatestart
- start index (inclusive)end
- end index (exclusive)- Throws:
StandardException
-
equals
public BooleanDataValue equals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The = operator as called from the language module, as opposed to the storage module.- Specified by:
equals
in interfaceDataValueDescriptor
- Overrides:
equals
in classDataType
- Parameters:
left
- The value on the left side of the =right
- The value on the right side of the =- Returns:
- A SQL boolean value telling whether the two parameters are equal
- Throws:
StandardException
- Thrown on error
-
notEquals
public BooleanDataValue notEquals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The <> operator as called from the language module, as opposed to the storage module.- Specified by:
notEquals
in interfaceDataValueDescriptor
- Overrides:
notEquals
in classDataType
- Parameters:
left
- The value on the left side of the operatorright
- The value on the right side of the operator- Returns:
- A SQL boolean value telling whether the two parameters are not equal
- Throws:
StandardException
- Thrown on error
-
lessThan
public BooleanDataValue lessThan(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The < operator as called from the language module, as opposed to the storage module.- Specified by:
lessThan
in interfaceDataValueDescriptor
- Overrides:
lessThan
in classDataType
- Parameters:
left
- The value on the left side of the operatorright
- The value on the right side of the operator- Returns:
- A SQL boolean value telling whether the first operand is less than the second operand
- Throws:
StandardException
- Thrown on error
-
greaterThan
public BooleanDataValue greaterThan(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The > operator as called from the language module, as opposed to the storage module.- Specified by:
greaterThan
in interfaceDataValueDescriptor
- Overrides:
greaterThan
in classDataType
- Parameters:
left
- The value on the left side of the operatorright
- The value on the right side of the operator- Returns:
- A SQL boolean value telling whether the first operand is greater than the second operand
- Throws:
StandardException
- Thrown on error
-
lessOrEquals
public BooleanDataValue lessOrEquals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The <= operator as called from the language module, as opposed to the storage module.- Specified by:
lessOrEquals
in interfaceDataValueDescriptor
- Overrides:
lessOrEquals
in classDataType
- Parameters:
left
- The value on the left side of the operatorright
- The value on the right side of the operator- Returns:
- A SQL boolean value telling whether the first operand is less than or equal to the second operand
- Throws:
StandardException
- Thrown on error
-
greaterOrEquals
public BooleanDataValue greaterOrEquals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The >= operator as called from the language module, as opposed to the storage module.- Specified by:
greaterOrEquals
in interfaceDataValueDescriptor
- Overrides:
greaterOrEquals
in classDataType
- Parameters:
left
- The value on the left side of the operatorright
- The value on the right side of the operator- Returns:
- A SQL boolean value telling whether the first operand is greater than or equal to the second operand
- Throws:
StandardException
- Thrown on error
-
charLength
This method implements the char_length function for char.- Specified by:
charLength
in interfaceConcatableDataValue
- Parameters:
result
- The result of a previous call to this method, null if not called yet- Returns:
- A SQLInteger containing the length of the char value
- Throws:
StandardException
- Thrown on error- See Also:
-
concatenate
public StringDataValue concatenate(StringDataValue leftOperand, StringDataValue rightOperand, StringDataValue result) throws StandardException Description copied from interface:StringDataValue
The SQL concatenation '||' operator.- Specified by:
concatenate
in interfaceStringDataValue
- Parameters:
leftOperand
- String on the left hand side of '||'rightOperand
- String on the right hand side of '||'result
- The result of a previous call to this method, null if not called yet.- Returns:
- A ConcatableDataValue containing the result of the '||'
- Throws:
StandardException
- Thrown on error- See Also:
-
like
This method implements the like function for char (with no escape value).- Specified by:
like
in interfaceStringDataValue
- Parameters:
pattern
- The pattern to use- Returns:
- A SQL boolean value telling whether the first operand is like the second operand
- Throws:
StandardException
- Thrown on error
-
like
public BooleanDataValue like(DataValueDescriptor pattern, DataValueDescriptor escape) throws StandardException This method implements the like function for char with an escape value.- Specified by:
like
in interfaceStringDataValue
- Parameters:
pattern
- The pattern to useescape
- the escape character- Returns:
- A SQL boolean value telling whether the first operand is like the second operand
- Throws:
StandardException
- Thrown on error
-
locate
public NumberDataValue locate(StringDataValue searchFrom, NumberDataValue start, NumberDataValue result) throws StandardException This method implements the locate function for char.- Specified by:
locate
in interfaceStringDataValue
- Parameters:
searchFrom
- - The string to search fromstart
- - The position to search from in string searchFromresult
- - The object to return Note: use getString() to get the string to search for.- Returns:
- The position in searchFrom the fist occurrence of this.value. 0 is returned if searchFrom does not contain this.value.
- Throws:
StandardException
- Thrown on error
-
substring
public ConcatableDataValue substring(NumberDataValue start, NumberDataValue length, ConcatableDataValue result, int maxLen) throws StandardException The SQL substr() function.- Specified by:
substring
in interfaceConcatableDataValue
- Parameters:
start
- Start of substrlength
- Length of substrresult
- The result of a previous call to this method, null if not called yet.maxLen
- Maximum length of the result- Returns:
- A ConcatableDataValue containing the result of the substr()
- Throws:
StandardException
- Thrown on error
-
trimInternal
This function public for testing purposes.- Parameters:
trimType
- Type of trim (LEADING, TRAILING, or BOTH)trimChar
- Character to trimsource
- String from which to trim trimChar- Returns:
- A String containing the result of the trim.
-
ansiTrim
public StringDataValue ansiTrim(int trimType, StringDataValue trimChar, StringDataValue result) throws StandardException Description copied from interface:StringDataValue
The SQL Ansi trim function.- Specified by:
ansiTrim
in interfaceStringDataValue
- Parameters:
trimType
- Type of trim (LEADING, TRAILING, or BOTH)trimChar
- Character to trim from this SQLChar (may be null)result
- The result of a previous call to this method, null if not called yet.- Returns:
- A StringDataValue containing the result of the trim.
- Throws:
StandardException
-
upper
Description copied from interface:StringDataValue
Convert the string to upper case.- Specified by:
upper
in interfaceStringDataValue
- Parameters:
result
- The result (reusable - allocate if null).- Returns:
- The string converted to upper case.
- Throws:
StandardException
- Thrown on error- See Also:
-
lower
Description copied from interface:StringDataValue
Convert the string to lower case.- Specified by:
lower
in interfaceStringDataValue
- Parameters:
result
- The result (reusable - allocate if null).- Returns:
- The string converted to lower case.
- Throws:
StandardException
- Thrown on error- See Also:
-
typePrecedence
public int typePrecedence()Description copied from class:DataType
Each built-in type in JSQL has a precedence. This precedence determines how to do type promotion when using binary operators. For example, float has a higher precedence than int, so when adding an int to a float, the result type is float. The precedence for some types is arbitrary. For example, it doesn't matter what the precedence of the boolean type is, since it can't be mixed with other types. But the precedence for the number types is critical. The SQL standard requires that exact numeric types be promoted to approximate numeric when one operator uses both. Also, the precedence is arranged so that one will not lose precision when promoting a type.- Specified by:
typePrecedence
in interfaceDataValueDescriptor
- Overrides:
typePrecedence
in classDataType
- Returns:
- The precedence of this type.
- See Also:
-
stringCompare
Compare two Strings using standard SQL semantics.- Parameters:
op1
- The first Stringop2
- The second String- Returns:
- -1 - op1 < op2 0 - op1 == op2 1 - op1 > op2
-
stringCompare
Compare two SQLChars.- Throws:
StandardException
- Thrown on error
-
stringCompare
protected static int stringCompare(char[] op1, int leftlen, char[] op2, int rightlen) Compare two Strings using standard SQL semantics.- Parameters:
op1
- The first Stringop2
- The second String- Returns:
- -1 - op1 < op2 0 - op1 == op2 1 - op1 > op2
-
getCollationKey
This method gets called for the collation sensitive char classes ie CollatorSQLChar, CollatorSQLVarchar, CollatorSQLLongvarchar, CollatorSQLClob. These collation sensitive chars need to have the collation key in order to do string comparison. And the collation key is obtained using the Collator object that these classes already have.- Returns:
- CollationKey obtained using Collator on the string
- Throws:
StandardException
-
toString
-
hashCode
public int hashCode() -
hashCodeForCollation
int hashCodeForCollation()Hash code implementation for collator sensitive subclasses. -
getNewVarchar
Get a SQLVarchar for a built-in string function.- Returns:
- a SQLVarchar.
- Throws:
StandardException
- Thrown on error
-
setLocaleFinder
-
getLocale
- Throws:
StandardException
- Thrown on error
-
getCollatorForCollation
- Throws:
StandardException
-
getLocaleFinder
-
estimateMemoryUsage
public int estimateMemoryUsage()Description copied from interface:DataValueDescriptor
Estimate the memory usage in bytes of the data value and the overhead of the class.- Specified by:
estimateMemoryUsage
in interfaceDataValueDescriptor
- Returns:
- the estimated memory usage
-
copyState
-
copyState
private void copyState(String otherValue, char[] otherRawData, int otherRawLength, CollationKey otherCKey, InputStream otherStream, Clob otherClobValue, LocaleFinder otherLocaleFinder) -
getTraceString
Gets a trace representation for debugging.- Specified by:
getTraceString
in interfaceDataValueDescriptor
- Overrides:
getTraceString
in classDataType
- Returns:
- a trace representation of this SQL Type.
- Throws:
StandardException
- if getting the data value fails.- See Also:
-
getStreamHeaderGenerator
Returns the default stream header generator for the string data types.- Specified by:
getStreamHeaderGenerator
in interfaceStringDataValue
- Returns:
- A stream header generator.
- See Also:
-
setStreamHeaderFormat
Sets the mode for the database being accessed.- Specified by:
setStreamHeaderFormat
in interfaceStringDataValue
- Parameters:
inSoftUpgradeMode
-true
if the database is being accessed in soft upgrade mode,false
if not, andnull
if unknown
-
getClobLength
- Throws:
StandardException
-
rawGetClobLength
- Throws:
SQLException
-