add a section & example about DialectOverride

This commit is contained in:
Gavin 2022-12-27 10:40:26 +01:00 committed by Gavin King
parent 11760d3ce3
commit 518328d364
2 changed files with 44 additions and 0 deletions

View File

@ -24,6 +24,21 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <p>
* For example, a {@link org.hibernate.annotations.Formula} annotation may be
* customized for a given {@code Dialect} using the {@link Formula} annotation.
* <pre>
* &#64;Formula(value = "(rate * 100) || '%'")
* &#64;DialectOverride.Formula(dialect = MySQLDialect.class,
* override = &#64;Formula("concat(rate * 100, '%')"))
* &#64;DialectOverride.Formula(dialect = DB2Dialect.class,
* override = &#64;Formula("varchar_format(rate * 100) || '%'"))
* &#64;DialectOverride.Formula(dialect = OracleDialect.class,
* override = &#64;Formula("to_char(rate * 100) || '%'"))
* &#64;DialectOverride.Formula(dialect = SQLServerDialect.class,
* override = &#64;Formula("ltrim(str(rate * 100, 10, 2)) + '%'"))
* &#64;DialectOverride.Formula(dialect = SybaseDialect.class,
* override = &#64;Formula("ltrim(str(rate * 100, 10, 2)) + '%'"))
* private String ratePercent;
* </pre>
* <p>
* An annotation may even be customized for a specific range of <em>versions</em>
* of the dialect by specifying a {@link Version}.
* <ul>
@ -34,6 +49,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <li>{@link Formula#before() before} specifies that the override applies
* to all versions earlier than the given version.
* </ul>
* <p>
*
* @since 6.0
* @author Gavin King

View File

@ -56,5 +56,33 @@
* over the compositional approach.
* <p>
* Please see the User Guide for a more in-depth discussion.
*
* <h2 id="basic-value-mapping">Dialect-specific native SQL</h2>
*
* Many annotations in this package allow the specification of native SQL expressions or
* even complete statements. For example:
* <ul>
* <li>{@link org.hibernate.annotations.Formula} allows a field or property to map to an
* arbitrary SQL expression instead of a column,
* <li>{@link org.hibernate.annotations.Check} specifies a check constraint condition,
* <li>{@link org.hibernate.annotations.ColumnDefault} specifies default value, and
* {@link org.hibernate.annotations.GeneratedColumn} specifies a generated value,
* <li>{@link org.hibernate.annotations.Filter} and {@link org.hibernate.annotations.Where}
* each specify a restriction written in SQL,
* <li>{@link org.hibernate.annotations.OrderBy} specifies an ordering written in SQL, and
* <li>{@link org.hibernate.annotations.SQLUpdate}, {@link org.hibernate.annotations.SQLInsert},
* and {@link org.hibernate.annotations.SQLDelete} allow a whole handwritten SQL statement
* to be given in place of the SQL generated by Hibernate.
* </ul>
* <p>
* A major disadvantage to annotation-based mappings for programs which target multiple databases
* is that there can be only one source of metadata which must work on every supported database.
* Fortunately, there's a&mdash;slightly inelegant&mdash;solution.
* <p>
* The annotations belonging to {@link org.hibernate.annotations.DialectOverride} allow native
* SQL to be overridden for a particular {@linkplain org.hibernate.dialect.Dialect SQL dialect}.
* For example {@link org.hibernate.annotations.DialectOverride.Formula @DialectOverride.Formula}
* may be used to customize a {@link org.hibernate.annotations.Formula @Formula} for a given version
* of a given database.
*/
package org.hibernate.annotations;