javadoc around nationalized character support

This commit is contained in:
Gavin King 2022-01-24 14:51:29 +01:00
parent 9ad64e5001
commit 596317da0b
3 changed files with 51 additions and 12 deletions

View File

@ -628,11 +628,38 @@ public interface AvailableSettings {
String IGNORE_EXPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS = "hibernate.discriminator.ignore_explicit_for_joined";
/**
* Enables nationalized character support for mappings to {@code VARCHAR} and {@code CLOB}.
* By default, Hibernate maps character data represented by {@link String}s and
* {@link java.sql.Clob}s to the JDBC types {@link java.sql.Types#VARCHAR} and
* {@link java.sql.Types#CLOB}. This setting, when enabled, turns on the use of
* explicit nationalized character support for mappings involving character
* data, specifying that the JDBC types {@link java.sql.Types#NVARCHAR} and
* {@link java.sql.Types#NCLOB} should be used instead.
* <p>
* Default is {@code false}.
* This setting is relevant for use with databases with
* {@linkplain org.hibernate.dialect.NationalizationSupport#EXPLICIT explicit
* nationalization support}, and it is not needed for databases whose native
* {@code varchar} and {@code clob} types support Unicode data. (If you're not
* sure how your database handles Unicode, check out the implementation of
* {@link org.hibernate.dialect.Dialect#getNationalizationSupport()} for its
* SQL dialect.)
* <p>
* Enabling this setting has two effects:
* <ol>
* <li>when interacting with JDBC, Hibernate uses operations like
* {@link java.sql.PreparedStatement#setNString(int, String)}
* {@link java.sql.PreparedStatement#setNClob(int, java.sql.NClob)}
* to pass character data, and
* <li>when generating DDL, the schema export tool uses {@code nvarchar}
* and {@code nclob} as the generated column types when no column
* type is explicitly specified using
* {@link jakarta.persistence.Column#columnDefinition()}.
* </ol>
* This setting is <em>disabled</em> by default, and so Unicode character data
* may not be persisted correctly for databases with explicit nationalization
* support.
*
* @see org.hibernate.boot.MetadataBuilder#enableGlobalNationalizedCharacterDataSupport(boolean)
* @see org.hibernate.dialect.NationalizationSupport
*/
String USE_NATIONALIZED_CHARACTER_DATA = "hibernate.use_nationalized_character_data";

View File

@ -3531,6 +3531,14 @@ public abstract class Dialect implements ConversionContext {
return databaseMetaData != null && databaseMetaData.supportsNamedParameters();
}
/**
* Determines whether this database requires the use
* of explicit nationalized character data types.
* <p>
* That is, whether the use of {@link Types#NCHAR},
* {@link Types#NVARCHAR}, and {@link Types#NCLOB} is
* required for nationalized character data (Unicode).
*/
public NationalizationSupport getNationalizationSupport() {
return NationalizationSupport.EXPLICIT;
}

View File

@ -9,25 +9,29 @@ package org.hibernate.dialect;
import java.sql.Types;
/**
* Indicates how (if) the underlying database supports the use of nationalized data
* Indicates if and how a database supports the use of nationalized
* character data (Unicode).
*
* @see org.hibernate.cfg.AvailableSettings#USE_NATIONALIZED_CHARACTER_DATA
* @see Dialect#getNationalizationSupport()
*/
public enum NationalizationSupport {
/**
* The database's CHAR, VARCHAR, LONGVARCHAR and CLOB types
* inherently handle nationalized data. Generally speaking
* this means the database will not have dedicated nationalized
* data types (NCHAR, ...)
* The {@code CHAR}, {@code VARCHAR}, and {@code CLOB}
* types inherently handle nationalized character data.
* Usually the database will not even define dedicated
* nationalized data types like {@code NVARCHAR}.
*/
IMPLICIT( Types.CHAR, Types.VARCHAR, Types.LONGVARCHAR, Types.CLOB ),
/**
* The database does define/support distinct nationalized
* data types (NCHAR, ...).
* The database does define and support distinct SQL types
* for representing nationalized character data, typically
* named {@code NCHAR}, {@code NVARCHAR}, and {@code NCLOB}.
*/
EXPLICIT( Types.NCHAR, Types.NVARCHAR, Types.LONGNVARCHAR, Types.NCLOB ),
/**
* The database does not define/support distinct nationalized
* data types (NCHAR, ...) and its corresponding base data
* types (CHAR, ...) do not support nationalized data
* The database does not even have support for nationalized
* character data.
*/
UNSUPPORTED;