|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Dialect
Description of an SQL dialect.
A dialect is instantiated via a DialectFactory
.
In JDBC terms, a dialect is analogous to a Connection
,
and a dialect factory is analogous to a Driver
, in the
sense that the JDBC driver manager maintains a chain of registered drivers,
and each driver in turn is given the opportunity to create a connection
that can handle a particular JDBC connect string. For dialects, each
registered dialect factory is given the chance to create a dialect that
matches a particular connection.
A dialect factory may be explicit or implicit:
public
static final
member in the dialect class called
"FACTORY
".Connection
as its
sole parameter, and the DialectManager
creates an implicit
factory that calls that constructor.Dialect factories can also be the means for caching or pooling dialects.
See allowsDialectSharing()
and
DialectFactory
for more details.
A dialect needs to be registered with the system in order to be used.
Call DialectManager.register(DialectFactory)
to register a dialect factory, or
DialectManager.register(Class)
to register a dialect
class.
Mondrian can load dialects on startup. To enable this for your dialect,
META-INF/services/mondrian.spi.Dialect
", containing the
name of your dialect class.To implement a dialect, write a class that implements the Dialect
interface. It is recommended that you subclass
JdbcDialectImpl
, to help to make your
dialect is forwards compatible, but it is not mandatory.
A dialects should be immutable. Mondrian assumes that dialects can safely
be shared between threads that use the same
JDBC connection
without synchronization. If
allowsDialectSharing()
returns true, Mondrian
may use the same dialect for different connections from the same
JDBC data source
.
Load the FoodMart data set into your database, and run Mondrian's suite of
regression tests. In particular, get mondrian.test.DialectTest
to run
cleanly first; this will ensure that the dialect's claims are consistent with
the actual behavior of your database.
DialectFactory
,
DialectManager
Nested Class Summary | |
---|---|
static class |
Dialect.DatabaseProduct
Enumeration of common database types. |
static class |
Dialect.Datatype
Datatype of a column. |
static class |
Dialect.NullCollation
Description of how NULL values are ordered in an ORDER BY
clause. |
Method Summary | |
---|---|
boolean |
allowsAs()
Returns whether the SQL dialect allows "AS" in the FROM clause. |
boolean |
allowsCompoundCountDistinct()
Returns whether this Dialect allows multiple arguments to the COUNT(DISTINCT ...) aggregate function, for example
|
boolean |
allowsCountDistinct()
Returns whether this Dialect supports distinct aggregations. |
boolean |
allowsDdl()
Returns whether this dialect supports common SQL Data Definition Language (DDL) statements such as CREATE TABLE and
DROP INDEX . |
boolean |
allowsDialectSharing()
Returns whether this Dialect object can be used for all connections from the same data source. |
boolean |
allowsFromQuery()
Returns whether this Dialect allows a subquery in the from clause, for example SELECT * FROM (SELECT * FROM t) AS
x |
boolean |
allowsMultipleCountDistinct()
Returns whether this Dialect supports more than one distinct aggregation in the same query. |
boolean |
allowsMultipleDistinctSqlMeasures()
Returns whether this Dialect has performant support of distinct SQL measures in the same query. |
boolean |
allowsOrderByAlias()
Returns true if aliases defined in the SELECT clause can be used as expressions in the ORDER BY clause. |
boolean |
allowsSelectNotInGroupBy()
Returns whether the database currently permits queries to include in the SELECT clause expressions that are not listed in the GROUP BY clause. |
void |
appendHintsAfterFromClause(java.lang.StringBuilder buf,
java.util.Map<java.lang.String,java.lang.String> hints)
Assembles and returns a string containing any hints that should be appended after the FROM clause in a SELECT statement, based on any hints provided. |
java.lang.String |
caseWhenElse(java.lang.String cond,
java.lang.String thenExpr,
java.lang.String elseExpr)
Generates a conditional statement in this dialect's syntax. |
java.lang.String |
generateInline(java.util.List<java.lang.String> columnNames,
java.util.List<java.lang.String> columnTypes,
java.util.List<java.lang.String[]> valueList)
Generates a SQL statement to represent an inline dataset. |
java.lang.String |
generateOrderItem(java.lang.String expr,
boolean nullable,
boolean ascending)
Generates an item for an ORDER BY clause, sorting in the required direction, and ensuring that NULL values collate after all non-NULL values. |
Dialect.DatabaseProduct |
getDatabaseProduct()
Returns the database for this Dialect, or Dialect.DatabaseProduct.UNKNOWN if the database is
not a common database. |
int |
getMaxColumnNameLength()
Returns the maximum length of the name of a database column or query alias allowed by this dialect. |
Dialect.NullCollation |
getNullCollation()
Returns the rule which determines whether NULL values appear first or last when sorted using ORDER BY. |
java.lang.String |
getQuoteIdentifierString()
Returns the character which is used to quote identifiers, or null if quoting is not supported. |
boolean |
needsExponent(java.lang.Object value,
java.lang.String valueString)
If Double values need to include additional exponent in its string represenation. |
void |
quote(java.lang.StringBuilder buf,
java.lang.Object value,
Dialect.Datatype datatype)
Appends to a buffer a value quoted for its type. |
void |
quoteBooleanLiteral(java.lang.StringBuilder buf,
java.lang.String value)
Appends to a buffer a boolean literal. |
void |
quoteDateLiteral(java.lang.StringBuilder buf,
java.lang.String value)
Appends to a buffer a date literal. |
java.lang.String |
quoteIdentifier(java.lang.String val)
Encloses an identifier in quotation marks appropriate for this Dialect. |
void |
quoteIdentifier(java.lang.StringBuilder buf,
java.lang.String... names)
Appends to a buffer a list of identifiers, quoted appropriately for this Dialect. |
java.lang.String |
quoteIdentifier(java.lang.String qual,
java.lang.String name)
Encloses an identifier in quotation marks appropriate for the current SQL dialect. |
void |
quoteIdentifier(java.lang.String val,
java.lang.StringBuilder buf)
Appends to a buffer an identifier, quoted appropriately for this Dialect. |
void |
quoteNumericLiteral(java.lang.StringBuilder buf,
java.lang.String value)
Appends to a buffer a numeric literal. |
void |
quoteStringLiteral(java.lang.StringBuilder buf,
java.lang.String s)
Appends to a buffer a single-quoted SQL string. |
void |
quoteTimeLiteral(java.lang.StringBuilder buf,
java.lang.String value)
Appends to a buffer a time literal. |
void |
quoteTimestampLiteral(java.lang.StringBuilder buf,
java.lang.String value)
Appends to a buffer a timestamp literal. |
boolean |
requiresAliasForFromQuery()
Returns whether this Dialect requires subqueries in the FROM clause to have an alias. |
boolean |
requiresGroupByAlias()
Returns true if this Dialect can include expressions in the GROUP BY clause only by adding an expression to the SELECT clause and using its alias. |
boolean |
requiresOrderByAlias()
Returns true if this Dialect can include expressions in the ORDER BY clause only by adding an expression to the SELECT clause and using its alias. |
boolean |
requiresUnionOrderByExprToBeInSelectClause()
Returns true if this dialect allows an expression in the ORDER BY clause of a UNION (or other set operation) query only if it occurs in the SELECT clause. |
boolean |
requiresUnionOrderByOrdinal()
Returns true if this dialect allows only integers in the ORDER BY clause of a UNION (or other set operation) query. |
boolean |
supportsGroupByExpressions()
Returns whether this Dialect supports expressions in the GROUP BY clause. |
boolean |
supportsGroupingSets()
Returns whether this Dialect allows the GROUPING SETS construct in the GROUP BY clause. |
boolean |
supportsMultiValueInExpr()
Returns true if this dialect supports multi-value IN expressions. |
boolean |
supportsResultSetConcurrency(int type,
int concurrency)
Returns whether this Dialect supports the given concurrency type in combination with the given result set type. |
boolean |
supportsUnlimitedValueList()
Returns whether this Dialect places no limit on the number of rows which can appear as elements of an IN or VALUES expression. |
java.lang.String |
toUpper(java.lang.String expr)
Converts an expression to upper case. |
Method Detail |
---|
java.lang.String toUpper(java.lang.String expr)
For example, for MySQL, toUpper("foo.bar")
returns
"UPPER(foo.bar)"
.
expr
- SQL expression
expr
into upper case.java.lang.String caseWhenElse(java.lang.String cond, java.lang.String thenExpr, java.lang.String elseExpr)
For example, caseWhenElse("b", "1", "0")
returns
"case when b then 1 else 0 end"
on Oracle,
"Iif(b, 1, 0)"
on Access.
cond
- Predicate expressionthenExpr
- Expression if condition is trueelseExpr
- Expression if condition is false
java.lang.String quoteIdentifier(java.lang.String val)
For example,
quoteIdentifier("emp")
yields a string containing
"emp"
in Oracle, and a string containing
[emp]
in Access.
val
- Identifier
void quoteIdentifier(java.lang.String val, java.lang.StringBuilder buf)
val
- identifier to quote (must not be null).buf
- Bufferjava.lang.String quoteIdentifier(java.lang.String qual, java.lang.String name)
quoteIdentifier("schema","table")
yields a string
containing "schema"."table"
.
qual
- Qualifier. If it is not null,
"qual".
is prepended.name
- Name to be quoted.
void quoteIdentifier(java.lang.StringBuilder buf, java.lang.String... names)
Names in the list may be null, but there must be at least one non-null name in the list.
buf
- Buffernames
- List of names to be quotedjava.lang.String getQuoteIdentifierString()
void quoteStringLiteral(java.lang.StringBuilder buf, java.lang.String s)
For example, in the default dialect,
quoteStringLiteral(buf, "Can't")
appends
"'Can''t'
" to buf
.
buf
- Buffer to append tos
- Literalvoid quoteNumericLiteral(java.lang.StringBuilder buf, java.lang.String value)
In the default dialect, numeric literals are printed as is.
buf
- Buffer to append tovalue
- Literalvoid quoteBooleanLiteral(java.lang.StringBuilder buf, java.lang.String value)
In the default dialect, boolean literals are printed as is.
buf
- Buffer to append tovalue
- Literalvoid quoteDateLiteral(java.lang.StringBuilder buf, java.lang.String value)
For example, in the default dialect,
quoteStringLiteral(buf, "1969-03-17")
appends DATE '1969-03-17'
.
buf
- Buffer to append tovalue
- Literalvoid quoteTimeLiteral(java.lang.StringBuilder buf, java.lang.String value)
For example, in the default dialect,
quoteStringLiteral(buf, "12:34:56")
appends TIME '12:34:56'
.
buf
- Buffer to append tovalue
- Literalvoid quoteTimestampLiteral(java.lang.StringBuilder buf, java.lang.String value)
For example, in the default dialect,
quoteStringLiteral(buf, "1969-03-17 12:34:56")
appends TIMESTAMP '1969-03-17 12:34:56'
.
buf
- Buffer to append tovalue
- Literalboolean requiresAliasForFromQuery()
allowsFromQuery()
boolean allowsAs()
boolean allowsFromQuery()
SELECT * FROM (SELECT * FROM t) AS
x
requiresAliasForFromQuery()
boolean allowsCompoundCountDistinct()
COUNT(DISTINCT ...) aggregate function, for example
SELECT COUNT(DISTINCT x, y) FROM t
- Returns:
- whether Dialect allows multiple arguments to COUNT DISTINCT
- See Also:
allowsCountDistinct()
,
allowsMultipleCountDistinct()
boolean allowsCountDistinct()
For example, Access does not allow
select count(distinct x) from t
boolean allowsMultipleCountDistinct()
In Derby 10.1,
select couunt(distinct x) from t
is OK, but
select couunt(distinct x), count(distinct y) from t
gives "Multiple DISTINCT aggregates are not supported at this time."
boolean allowsMultipleDistinctSqlMeasures()
java.lang.String generateInline(java.util.List<java.lang.String> columnNames, java.util.List<java.lang.String> columnTypes, java.util.List<java.lang.String[]> valueList)
For example, for Oracle, generates
SELECT 1 AS FOO, 'a' AS BAR FROM dual UNION ALL SELECT 2 AS FOO, 'b' AS BAR FROM dual
For ANSI SQL, generates:
VALUES (1, 'a'), (2, 'b')
columnNames
- List of column namescolumnTypes
- List of column types ("String" or "Numeric")valueList
- List of rows values
boolean needsExponent(java.lang.Object value, java.lang.String valueString)
value
- Double value to generate string forvalueString
- java string representation for this value.
void quote(java.lang.StringBuilder buf, java.lang.Object value, Dialect.Datatype datatype)
buf
- Buffer to append tovalue
- Valuedatatype
- Datatype of valueboolean allowsDdl()
CREATE TABLE
and
DROP INDEX
.
Access seems to allow DDL iff the .mdb file is writeable.
DatabaseMetaData.isReadOnly()
Dialect.NullCollation getNullCollation()
According to the SQL standard, this is implementation-specific.
The default behavior is
Dialect.NullCollation.POSINF
.
java.lang.String generateOrderItem(java.lang.String expr, boolean nullable, boolean ascending)
By default, generateOrderItem(expr, true)
generates "expr ASC"
and generateOrderItem(expr, false)
generates "expr DESC". But
depending on getNullCollation()
and ascending
, there
may need to be additional code.
For example, on Oracle, where NULLs collate higher than all other
values, generateOrderItem(expr, true)
generates "expr ASC" and
generateOrderItem(expr, false)
generates "expr DESC NULLS LAST".
On MySQL, where NULLs collate lower than all other values,
generateOrderItem(expr, true)
generates "ISNULL(expr), expr ASC"
and generateOrderItem(expr, false)
generates "expr DESC".
expr
- Expressionnullable
- Whether expression may have NULL valuesascending
- Whether to sort expression ascending
boolean supportsGroupByExpressions()
boolean supportsGroupingSets()
boolean supportsUnlimitedValueList()
boolean requiresGroupByAlias()
For example, in such a dialect,
SELECT x, x FROM t GROUP BY x
would be illegal, but
SELECT x AS a, x AS b FROM t ORDER BY a, b
would be legal.
Infobright is the only such dialect.
boolean requiresOrderByAlias()
For example, in such a dialect,
SELECT x FROM t ORDER BY x + y
would be illegal, but
SELECT x, x + y AS z FROM t ORDER BY z
would be legal.
MySQL, DB2 and Ingres are examples of such dialects.
boolean allowsOrderByAlias()
For example, in such a dialect,
SELECT x, x + y AS z FROM t ORDER BY z
would be legal.
MySQL, DB2 and Ingres are examples of dialects where this is true; Access is a dialect where this is false.
boolean requiresUnionOrderByOrdinal()
For example,
SELECT x, y + z FROM t
is allowed but
UNION ALL
SELECT x, y + z FROM t
ORDER BY 1, 2SELECT x, y, z FROM t
is not.
UNION ALL
SELECT x, y, z FROM t
ORDER BY x
Teradata is an example of a dialect with this restriction.
boolean requiresUnionOrderByExprToBeInSelectClause()
For example,
SELECT x, y + z FROM t
is allowed but
UNION ALL
SELECT x, y + z FROM t
ORDER BY y + zSELECT x, y, z FROM t
UNION ALL
SELECT x, y, z FROM t
ORDER BY y + zSELECT x, y, z FROM t ORDER BY y + z
is not.
Access is an example of a dialect with this restriction.
boolean supportsMultiValueInExpr()
WHERE (col1, col2) IN ((val1a, val2a), (val1b, val2b))
boolean supportsResultSetConcurrency(int type, int concurrency)
The result is similar to
DatabaseMetaData.supportsResultSetConcurrency(int, int)
,
except that the JdbcOdbc bridge in JDK 1.6 overstates its abilities.
See bug 1690406.
type
- defined in ResultSet
concurrency
- type defined in ResultSet
true
if so; false
otherwiseint getMaxColumnNameLength()
DatabaseMetaData.getMaxColumnNameLength()
Dialect.DatabaseProduct getDatabaseProduct()
Dialect.DatabaseProduct.UNKNOWN
if the database is
not a common database.
void appendHintsAfterFromClause(java.lang.StringBuilder buf, java.util.Map<java.lang.String,java.lang.String> hints)
buf
- The Stringbuffer to which the dialect-specific syntax
for any relevant table hints may be appended. Must not be null.hints
- A map of table hints provided in the schema definitionboolean allowsDialectSharing()
The default implementation returns true
, and this allows
dialects to be cached and reused in environments where connections are
allocated from a pool based on the same data source.
Data sources are deemed 'equal' by the same criteria used by Java
collections, namely the Object.equals(Object)
and
Object.hashCode()
methods.
DialectFactory.createDialect(javax.sql.DataSource, java.sql.Connection)
boolean allowsSelectNotInGroupBy()
For example, SELECT empno, first_name || ' ' || last_name FROM
emps GROUP BY empno
is valid because empno
is the primary key of
the emps
table, and therefore all columns are dependent on it.
For a given value of empno
,
first_name || ' ' || last_name
has a unique value.
Most databases do not, MySQL is an example of one that does (if the functioality is enabled).
|
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |