org.eigenbase.sql
Class SqlLiteral

java.lang.Object
  org.eigenbase.sql.SqlNode
      org.eigenbase.sql.SqlLiteral

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

SqlAbstractDateTimeLiteral, SqlAbstractStringLiteral, SqlIntervalLiteral, SqlNumericLiteral

public class SqlLiteral
extends SqlNode

A SqlLiteral is a constant. It is, appropriately, immutable.

How is the value stored? In that respect, the class is somewhat of a black box. There is a getValue() method which returns the value as an object, but the type of that value is implementation detail, and it is best that your code does not depend upon that knowledge. It is better to use task-oriented methods such as SqlNode.toSqlString(SqlDialect) and toValue().

If you really need to access the value directly, you should switch on the value of the typeName field, rather than making assumptions about the runtime type of the value.

The allowable types and combinations are:

TypeName	Meaing	Value type
SqlTypeName.NULL	The null value. It has its own special type.	null
SqlTypeName.BOOLEAN	Boolean, namely TRUE, FALSE or UNKNOWN.	Boolean, or null represents the UNKNOWN value
SqlTypeName.DECIMAL	Exact number, for example 0, -.5, 12345.	BigDecimal
SqlTypeName.DOUBLE	Approximate number, for example 6.023E-23.	BigDecimal
SqlTypeName.DATE	Date, for example DATE '1969-04'29'	Calendar
SqlTypeName.TIME	Time, for example TIME '18:37:42.567'	Calendar
SqlTypeName.TIMESTAMP	Timestamp, for example TIMESTAMP '1969-04-29 18:37:42.567'	Calendar
SqlTypeName.CHAR	Character constant, for example 'Hello, world!', '', _N'Bonjour', _ISO-8859-1'It''s superman!' COLLATE SHIFT_JIS$ja_JP$2. These are always CHAR, never VARCHAR.	NlsString
SqlTypeName.BINARY	Binary constant, for example X'ABC', X'7F'. Note that strings with an odd number of hexits will later become values of the BIT datatype, because they have an incomplete number of bytes. But here, they are all binary constants, because that's how they were written. These constants are always BINARY, never VARBINARY.	BitString
SqlTypeName.SYMBOL	A symbol is a special type used to make parsing easier; it is not part of the SQL standard, and is not exposed to end-users. It is used to hold a symbol, such as the LEADING flag in a call to the function TRIM([LEADING|TRAILING|BOTH] chars FROM string).	A class which implements the SqlLiteral.SqlSymbol interface
SqlTypeName.INTERVAL_DAY_TIME	Interval, for example INTERVAL '1:34' HOUR.	<SqlIntervalLiteral.IntervalValue.

Version:

$Id: //open/dev/farrago/src/org/eigenbase/sql/SqlLiteral.java#44 $

Author:

jhyde

Nested Class Summary

static interface

SqlLiteral.SqlSymbol A value must implement this interface if it is to be embedded as a SqlLiteral of type SYMBOL.

Field Summary

private SqlTypeName	typeName The type with which this literal was declared.
protected Object	value The value of this literal.

Fields inherited from class org.eigenbase.sql.SqlNode

emptyArray

Constructor Summary

protected

SqlLiteral(Object value, SqlTypeName typeName, SqlParserPos pos) Creates a SqlLiteral.

Method Summary

<R> R	accept(SqlVisitor<R> visitor) Accepts a generic visitor.
BigDecimal	bigDecimalValue() Returns a numeric literal's value as a BigDecimal.
static boolean	booleanValue(SqlNode node) Converts extracts the value from a boolean literal.
SqlNode	clone(SqlParserPos pos) Clones a SqlNode with a different position.
static SqlNumericLiteral	createApproxNumeric(String s, SqlParserPos pos)
static SqlBinaryStringLiteral	createBinaryString(byte[] bytes, SqlParserPos pos) Creates a literal like X'ABAB' from an array of bytes.
static SqlBinaryStringLiteral	createBinaryString(String s, SqlParserPos pos) Creates a literal like X'ABAB'.
static SqlLiteral	createBoolean(boolean b, SqlParserPos pos) Creates a boolean literal.
static SqlCharStringLiteral	createCharString(String s, SqlParserPos pos) Creates a string literal in the system character set.
static SqlCharStringLiteral	createCharString(String s, String charSet, SqlParserPos pos) Creates a string literal, with optional character-set.
static SqlDateLiteral	createDate(Calendar calendar, SqlParserPos pos)
static SqlNumericLiteral	createExactNumeric(String s, SqlParserPos pos)
static SqlIntervalLiteral	createInterval(int sign, String intervalStr, SqlIntervalQualifier intervalQualifier, SqlParserPos pos) Creates an interval literal.
static SqlNumericLiteral	createNegative(SqlNumericLiteral num, SqlParserPos pos)
static SqlLiteral	createNull(SqlParserPos pos) Creates a NULL literal.
static SqlLiteral	createSample(SqlSampleSpec sampleSpec, SqlParserPos pos) Creates a literal which represents a sample specification.
RelDataType	createSqlType(RelDataTypeFactory typeFactory)
static SqlLiteral	createSymbol(SqlLiteral.SqlSymbol o, SqlParserPos pos) Creates a literal which represents a parser symbol, for example the TRAILING keyword in the call Trim(TRAILING 'x' FROM 'Hello world!').
static SqlTimeLiteral	createTime(Calendar calendar, int precision, SqlParserPos pos)
static SqlTimestampLiteral	createTimestamp(Calendar calendar, int precision, SqlParserPos pos)
static SqlLiteral	createUnknown(SqlParserPos pos)
boolean	equals(Object obj)
boolean	equalsDeep(SqlNode node, boolean fail) Returns whether this node is structurally equivalent to another node.
SqlKind	getKind() Returns the type of node this is, or SqlKind.Other if it's nothing special.
SqlMonotonicity	getMonotonicity(SqlValidatorScope scope) Returns whether expression is always ascending, descending or constant.
String	getStringValue()
SqlTypeName	getTypeName()
Object	getValue() Returns the value of this literal.
int	hashCode()
int	intValue(boolean exact) Returns the integer value of this literal.
long	longValue(boolean exact) Returns the long value of this literal.
static SqlSampleSpec	sampleValue(SqlNode node) Extracts the SqlSampleSpec value from a symbol literal.
static String	stringValue(SqlNode node) Extracts the string value from a string literal, a chain of string literals, or a CAST of a string literal.
static SqlLiteral.SqlSymbol	symbolValue(SqlNode node) Extracts the enumerated value from a symbol literal.
String	toValue() For calc program builder - value may be different than unparse(org.eigenbase.sql.SqlWriter, int, int) Typical values: Hello, world! 12.34 {null} 1969-04-29
SqlLiteral	unescapeUnicode(char unicodeEscapeChar) Transforms this literal (which must be of type character) into a new one in which 4-digit Unicode escape sequences have been replaced with the corresponding Unicode characters.
void	unparse(SqlWriter writer, int leftPrec, int rightPrec) Writes a SQL representation of this node to a writer.
void	validate(SqlValidator validator, SqlValidatorScope scope) Validates this node.
static boolean	valueMatchesType(Object value, SqlTypeName typeName)

Methods inherited from class org.eigenbase.sql.SqlNode

clone, cloneArray, equalDeep, findValidOptions, getParserPosition, isA, toSqlString, toSqlString, toString, validateExpr

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

typeName

private final SqlTypeName typeName

The type with which this literal was declared. This type is very approximate: the literal may have a different type once validated. For example, all numeric literals have a type name of SqlTypeName.DECIMAL, but on validation may become SqlTypeName.INTEGER.

value

protected final Object value

The value of this literal. The type of the value must be appropriate for the typeName, as defined by the valueMatchesType(java.lang.Object, org.eigenbase.sql.type.SqlTypeName) method.

Constructor Detail

SqlLiteral

protected SqlLiteral(Object value,
                     SqlTypeName typeName,
                     SqlParserPos pos)

Creates a SqlLiteral.

"Precondition:"

typeName != null, valueMatchesType(value,typeName)

Method Detail

getTypeName

public SqlTypeName getTypeName()

Returns:

value of typeName

valueMatchesType

public static boolean valueMatchesType(Object value,
                                       SqlTypeName typeName)

Returns:

whether value is appropriate for its type (we have rules about these things)

clone

public SqlNode clone(SqlParserPos pos)

Description copied from class: SqlNode

Clones a SqlNode with a different position.

Overrides:

clone in class SqlNode

getKind

public SqlKind getKind()

Description copied from class: SqlNode

Returns the type of node this is, or SqlKind.Other if it's nothing special.

Overrides:

getKind in class SqlNode

Returns:

a SqlKind value, never null

getValue

public Object getValue()

Returns the value of this literal.

Try not to use this method! There are so many different kinds of values, it's better to to let SqlLiteral do whatever it is you want to do.

See Also:

booleanValue(SqlNode), symbolValue(SqlNode)

booleanValue

public static boolean booleanValue(SqlNode node)

Converts extracts the value from a boolean literal.

Throws:

ClassCastException - if the value is not a boolean literal

symbolValue

public static SqlLiteral.SqlSymbol symbolValue(SqlNode node)

Extracts the enumerated value from a symbol literal.

Throws:

ClassCastException - if the value is not a symbol literal

See Also:

createSymbol(SqlSymbol, SqlParserPos)

sampleValue

public static SqlSampleSpec sampleValue(SqlNode node)

Extracts the SqlSampleSpec value from a symbol literal.

Throws:

ClassCastException - if the value is not a symbol literal

See Also:

createSymbol(SqlSymbol, SqlParserPos)

stringValue

public static String stringValue(SqlNode node)

Extracts the string value from a string literal, a chain of string literals, or a CAST of a string literal.

toValue

public String toValue()

For calc program builder - value may be different than unparse(org.eigenbase.sql.SqlWriter, int, int) Typical values:

• Hello, world!
• 12.34
• {null}
• 1969-04-29

Returns:

string representation of the value

validate

public void validate(SqlValidator validator,
                     SqlValidatorScope scope)

Description copied from class: SqlNode

Validates this node.

The typical implementation of this method will make a callback to the validator appropriate to the node type and context. The validator has methods such as SqlValidator.validateLiteral(org.eigenbase.sql.SqlLiteral) for these purposes.

Specified by:

validate in class SqlNode

scope - Validator

accept

public <R> R accept(SqlVisitor<R> visitor)

Description copied from class: SqlNode

Accepts a generic visitor.

Implementations of this method in subtypes simply call the appropriate visit method on the visitor object.

The type parameter R must be consistent with the type parameter of the visitor.

Specified by:

accept in class SqlNode

equalsDeep

public boolean equalsDeep(SqlNode node,
                          boolean fail)

Description copied from class: SqlNode

Returns whether this node is structurally equivalent to another node. Some examples:

• 1 + 2 is structurally equivalent to 1 + 2
• 1 + 2 + 3 is structurally equivalent to (1 + 2) + 3, but not to 1 + (2 + 3), because the '+' operator is left-associative

Specified by:

equalsDeep in class SqlNode

getMonotonicity

public SqlMonotonicity getMonotonicity(SqlValidatorScope scope)

Description copied from class: SqlNode

Returns whether expression is always ascending, descending or constant. This property is useful because it allows to safely aggregte infinite streams of values.

The default implementation returns SqlMonotonicity.NotMonotonic.

Overrides:

getMonotonicity in class SqlNode

createNull

public static SqlLiteral createNull(SqlParserPos pos)

Creates a NULL literal.

There's no singleton constant for a NULL literal. Instead, nulls must be instantiated via createNull(), because different instances have different context-dependent types.

createBoolean

public static SqlLiteral createBoolean(boolean b,
                                       SqlParserPos pos)

Creates a boolean literal.

createUnknown

public static SqlLiteral createUnknown(SqlParserPos pos)

createSymbol

public static SqlLiteral createSymbol(SqlLiteral.SqlSymbol o,
                                      SqlParserPos pos)

Creates a literal which represents a parser symbol, for example the TRAILING keyword in the call Trim(TRAILING 'x' FROM 'Hello world!').

See Also:

symbolValue(SqlNode)

createSample

public static SqlLiteral createSample(SqlSampleSpec sampleSpec,
                                      SqlParserPos pos)

Creates a literal which represents a sample specification.

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

intValue

public int intValue(boolean exact)

Returns the integer value of this literal.

Parameters:

exact - Whether the value has to be exact. If true, and the literal is a fraction (e.g. 3.14), throws. If false, discards the fractional part of the value.

Returns:

Integer value of this literal

longValue

public long longValue(boolean exact)

Returns the long value of this literal.

Parameters:

exact - Whether the value has to be exact. If true, and the literal is a fraction (e.g. 3.14), throws. If false, discards the fractional part of the value.

Returns:

Long value of this literal

bigDecimalValue

public BigDecimal bigDecimalValue()

Returns a numeric literal's value as a BigDecimal.

getStringValue

public String getStringValue()

unparse

public void unparse(SqlWriter writer,
                    int leftPrec,
                    int rightPrec)

Description copied from class: SqlNode

Writes a SQL representation of this node to a writer.

The leftPrec and rightPrec parameters give us enough context to decide whether we need to enclose the expression in parentheses. For example, we need parentheses around "2 + 3" if preceded by "5 *". This is because the precedence of the "*" operator is greater than the precedence of the "+" operator.

The algorithm handles left- and right-associative operators by giving them slightly different left- and right-precedence.

If SqlWriter.isAlwaysUseParentheses() is true, we use parentheses even when they are not required by the precedence rules.

For the details of this algorithm, see SqlCall.unparse(org.eigenbase.sql.SqlWriter, int, int).

Specified by:

unparse in class SqlNode

Parameters:

writer - Target writer

leftPrec - The precedence of the SqlNode immediately preceding this node in a depth-first scan of the parse tree

rightPrec - The precedence of the SqlNode immediately

createSqlType

public RelDataType createSqlType(RelDataTypeFactory typeFactory)

createDate

public static SqlDateLiteral createDate(Calendar calendar,
                                        SqlParserPos pos)

createTimestamp

public static SqlTimestampLiteral createTimestamp(Calendar calendar,
                                                  int precision,
                                                  SqlParserPos pos)

createTime

public static SqlTimeLiteral createTime(Calendar calendar,
                                        int precision,
                                        SqlParserPos pos)

createInterval

public static SqlIntervalLiteral createInterval(int sign,
                                                String intervalStr,
                                                SqlIntervalQualifier intervalQualifier,
                                                SqlParserPos pos)

Creates an interval literal.

Parameters:

intervalStr - input string of '1:23:04'

intervalQualifier - describes the interval type and precision

pos - Parser position

createNegative

public static SqlNumericLiteral createNegative(SqlNumericLiteral num,
                                               SqlParserPos pos)

createExactNumeric

public static SqlNumericLiteral createExactNumeric(String s,
                                                   SqlParserPos pos)

createApproxNumeric

public static SqlNumericLiteral createApproxNumeric(String s,
                                                    SqlParserPos pos)

createBinaryString

public static SqlBinaryStringLiteral createBinaryString(String s,
                                                        SqlParserPos pos)

Creates a literal like X'ABAB'. Although it matters when we derive a type for this beastie, we don't care at this point whether the number of hexits is odd or even.

createBinaryString

public static SqlBinaryStringLiteral createBinaryString(byte[] bytes,
                                                        SqlParserPos pos)

Creates a literal like X'ABAB' from an array of bytes.

Parameters:

bytes - Contents of binary literal

pos - Parser position

Returns:

Binary string literal

createCharString

public static SqlCharStringLiteral createCharString(String s,
                                                    SqlParserPos pos)

Creates a string literal in the system character set.

Parameters:

s - a string (without the sql single quotes)

pos - Parser position

createCharString

public static SqlCharStringLiteral createCharString(String s,
                                                    String charSet,
                                                    SqlParserPos pos)

Creates a string literal, with optional character-set.

Parameters:

s - a string (without the sql single quotes)

charSet - character set name, null means take system default

pos - Parser position

Returns:

A string literal

Throws:

UnsupportedCharsetException - if charSet is not null but there is no character set with that name in this environment

unescapeUnicode

public SqlLiteral unescapeUnicode(char unicodeEscapeChar)

Transforms this literal (which must be of type character) into a new one in which 4-digit Unicode escape sequences have been replaced with the corresponding Unicode characters.

Parameters:

unicodeEscapeChar - escape character (e.g. backslash) for Unicode numeric sequences; 0 implies no transformation

Returns:

transformed literal