add a section & example about DialectOverride

hibernate-core/src/main/java/org/hibernate/annotations/DialectOverride.java

@@ -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

hibernate-core/src/main/java/org/hibernate/annotations/package-info.java

@@ -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;