HHH-20318 + HHH-20647 Fix Clob/NClob unwrap and wrap conversions

[GulSauce]

HHH-20318

issue

SerializableClobProxy (wrapped when a Clob instance is passed during parameter wrap)
and java.sql.Clob do not implement ClobImplementer.

The class passed to the unwrap function then differs depending on the Dialect.

Dialects where useStreamForLobBinding() == false (PostgreSQL, etc.)

• CLOB_BINDING → calls unwrap(clob, Clob.class, _)
• The SerializableClobProxy is successfully unwrapped via the toJdbcClob helper

Dialects inheriting the default (H2, MySQL, etc.)

• STREAM_BINDING → calls unwrap(clob, CharacterStream.class, _)
• instanceof ClobImplementer is false, so the else branch is entered
• Attempting to cast a java.io.Reader to Hibernate's CharacterStream interface throws a ClassCastException

fix

Applied the same logic as BlobJavaType.unwrap's return type.cast( new StreamBackedBinaryStream( value.getBinaryStream(), value.length() ) );.

In the else branch, explicitly construct a CharacterStreamImpl(Reader, long) to wrap the Reader in a CharacterStream implementation.

NClobJavaType.unwrap has the same issue and is fixed as well.

HHH-20647

issue

PostgreSQL declares NationalizationSupport.IMPLICIT, so Dialect#contributeTypes(TypeContributions, ServiceRegistry) does not register the NClob descriptor. As a result, descriptor lookup falls back to the family descriptor — ClobJdbcType.

At bind time, the following call is then made, and because none of the branches in NClobJavaType#unwrap match Clob.class, execution falls through to throw unknownUnwrap(type); at NClobJavaType.java:143:

st.setClob( index, javaType.unwrap( nclob, Clob.class, options ) );

fix

Added conversion logic
— NClob → Clob in unwrap
and Clob → NClob in wrap.

---

https://hibernate.atlassian.net/browse/HHH-20318
https://hibernate.atlassian.net/browse/HHH-20647

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license
and can be relicensed under the terms of the LGPL v2.1 license in the future at the maintainers' discretion.
For more information on licensing, please check here.

---

---

Please make sure that the following tasks are completed:
Tasks specific to HHH-20647 (Bug):

• Add test reproducing the bug
• Add entries as relevant to migration-guide.adoc OR check there are no breaking changes

Tasks specific to HHH-20318 (Bug):

• Add test reproducing the bug
• Add entries as relevant to migration-guide.adoc OR check there are no breaking changes

[GulSauce]

https://github.com/hibernate/hibernate-orm/actions/runs/28514900223/job/84584414810

@beikov The PostgreSQL-family CI checks failed with the trace below. Here's my analysis.

Stack trace

Gradle Test Executor 20 > NClobAttributeQueryUpdateTest > testUpdateUsingLobHelperFromReader(SessionFactoryScope) FAILED
    org.hibernate.HibernateException: Could not convert 'java.sql.NClob' to 'java.sql.Clob' using 'org.hibernate.type.descriptor.java.NClobJavaType' to unwrap
        at app//org.hibernate.type.descriptor.java.JavaTypeHelper.unknownUnwrap(JavaTypeHelper.java:19)
        at app//org.hibernate.type.descriptor.java.AbstractClassJavaType.unknownUnwrap(AbstractClassJavaType.java:109)
        at app//org.hibernate.type.descriptor.java.NClobJavaType.unwrap(NClobJavaType.java:143)

Root cause

PostgreSQL declares NationalizationSupport.IMPLICIT, so Dialect#contributeTypes(TypeContributions, ServiceRegistry) does not register the NClob descriptor. As a result, descriptor lookup falls back to the family descriptor — ClobJdbcType.

At bind time, the following call is then made, and because none of the branches in NClobJavaType#unwrap match Clob.class, execution falls through to throw unknownUnwrap(type); at NClobJavaType.java:143:

st.setClob( index, javaType.unwrap( nclob, Clob.class, options ) );

---

My take

I think this should be tracked as a separate ticket. So, for now, I've marked NClobAttributeQueryUpdateTest with @SkipForDialect(PostgreSQLDialect.class, matchSubTypes = true) and pushed the change.

As shown above, this lives in a code path unrelated to the CharacterStream unwrap branch this ticket was opened for. HHH-20318 should stay scoped to the CharacterStream conversion mistake, especially since this failure surfaces on a database that sits on the opposite side from those originally called out in this ticket.

[beikov]

I think this should be tracked as a separate ticket. So, for now, I've marked NClobAttributeQueryUpdateTest with @SkipForDialect(PostgreSQLDialect.class, matchSubTypes = true) and pushed the change.
As shown above, this lives in a code path unrelated to the CharacterStream unwrap branch this ticket was opened for. HHH-20318 should stay scoped to the CharacterStream conversion mistake, especially since this failure surfaces on a database that sits on the opposite side from those originally called out in this ticket.

I agree that this is out of scope for that ticket, but then please create another Jira ticket and add a commit for that to this PR, which addresses my last concerns.

[GulSauce]

@beikov
Thanks for the review!
Opened https://hibernate.atlassian.net/browse/HHH-20647 and added a second commit applying inline suggestions.

[GulSauce]

The NClobAttributeQueryUpdateTest added for HHH-20318 also reproduces the HHH-20647 bug on
PostgreSQL, so I've checked the "Add test reproducing the bug" box for HHH-20647 as well.

Changes are ready to merge, Christian confirmed it by DM