2.3.9. Mapping Nationalized Character Data

<div class="paragraph">

JDBC 4 added the ability to explicitly handle nationalized character data.
To this end it added specific nationalized character data types.

</div>
<div class="ulist">

• NCHAR
• NVARCHAR
• LONGNVARCHAR

• NCLOB </div>

  Example 36. `NVARCHAR` - SQL

  `CREATE TABLE Product (

  id INTEGER NOT NULL ,
  name VARCHAR(255) ,
  warranty NVARCHAR(255) ,
  PRIMARY KEY ( id )
  

  )`</pre> </div> </div> </div> </div>

  To map a specific attribute to a nationalized variant data type, Hibernate defines the @Nationalized annotation.

  </div>

  Example 37. `NVARCHAR` mapping

  `@Entity(name = "Product")
  public static class Product {

  @Id
  private Integer id;
  
  private String name;
  
  @Nationalized
  private String warranty;
  
  //Getters and setters are omitted for brevity
  

  }`</pre> </div> </div> </div> </div>

  Just like with CLOB, Hibernate can also deal with NCLOB SQL data types:

  </div>

  Example 38. `NCLOB` - SQL

  `CREATE TABLE Product (

  id INTEGER NOT NULL ,
  name VARCHAR(255) ,
  warranty nclob ,
  PRIMARY KEY ( id )
  

  )`</pre> </div> </div> </div> </div>

  Hibernate can map the NCLOB to a java.sql.NClob

  </div>

  Example 39. `NCLOB` mapped to `java.sql.NClob`

  `@Entity(name = "Product")
  public static class Product {

  @Id
  private Integer id;
  
  private String name;
  
  @Lob
  @Nationalized
  // Clob also works, because NClob extends Clob.
  // The database type is still NCLOB either way and handled as such.
  private NClob warranty;
  
  //Getters and setters are omitted for brevity
  

  }`</pre> </div> </div> </div> </div>

  To persist such an entity, you have to create a NClob using plain JDBC:

  </div>

  Example 40. Persisting a `java.sql.NClob` entity

  `String warranty = "My product warranty";

  final Product product = new Product(); product.setId( 1 ); product.setName( "Mobile phone" );

  session.doWork( connection -> {

  product.setWarranty( connection.createNClob() );
  product.getWarranty().setString( 1, warranty );
  

  } );

  entityManager.persist( product );`</pre> </div> </div> </div> </div>

  To retrieve the NClob content, you need to transform the underlying java.io.Reader:

  </div>

  Example 41. Returning a `java.sql.NClob` entity

  `Product product = entityManager.find( Product.class, productId );
  try (Reader reader = product.getWarranty().getCharacterStream()) {

  assertEquals( "My product warranty", toString( reader ) );
  

  }`</pre> </div> </div> </div> </div>

  We could also map the NCLOB in a materialized form. This way, we can either use a String or a char[].

  </div>

  Example 42. `NCLOB` mapped to `String`

  `@Entity(name = "Product")
  public static class Product {

  @Id
  private Integer id;
  
  private String name;
  
  @Lob
  @Nationalized
  private String warranty;
  
  //Getters and setters are omitted for brevity
  

  }`</pre> </div> </div> </div> </div>

  We might even want the materialized data as a char array.

  </div>

  Example 43. NCLOB - materialized `char[]` mapping

  `@Entity(name = "Product")
  public static class Product {

  @Id
  private Integer id;
  
  private String name;
  
  @Lob
  @Nationalized
  private char[] warranty;
  
  //Getters and setters are omitted for brevity
  

  }`</pre> </div> </div> </div> </div>

  </td>

  If you application and database are entirely nationalized you may instead want to enable nationalized character data as the default. You can do this via the hibernate.use_nationalized_character_data setting or by calling MetadataBuilder#enableGlobalNationalizedCharacterDataSupport during bootstrap.

  </div> </td> </tr> </table> </div> </div>