@CustomType

[sebersole]

TLDR; Introduce @CustomType as a type-safe replacement for @Type.

https://hibernate.atlassian.net/browse/HHH-14856

We've had a few discussions now about wanting to move away from Type determination being based on Strings and to define a more type-safe way to accomplish that.

I propose the following annotation:

public @interface CustomType {
	/**
	 * The attribute "name" to which the type applies.  The
	 * "name" can also specify that it applies to the key
	 * of the Map attribute, etc.
	 *
	 * We recognize the standard Jakarta Persistence values, when applied Map attributes:<ul>
	 *     <li>{@code "key"}</li>
	 *     <li>{@code "value"}</li>
	 * </ul>
	 */
	String attributeName() default "";

	/**
	 * The custom type implementation
	 */
	Class<? extends UserType<?>> typeImplementation();

	/**
	 * Parameters to be injected into the custom type implementation
	 * after it is instantiated. To receive the parameters, the custom
	 * type implementation must implement
	 * {@link org.hibernate.usertype.ParameterizedType}
	 */
	Parameter[] parameters() default {};
}

With regard to #attributeName, it was suggested by @beikov and I think its a great idea. Rather than needing additional annotations such as @MapKeyCustomType, etc we can just have a single annotation and specify what the type applies to. This follows the pattern used by JPA so that's good(ish)

I also propose that we drop @Type, @MapKeyType, @TypeDef, @TypeDefs as part of this work. We have better ways for users to accomplish these, so there is good migration story. Keeping UserType and providing @CustomType covers the remaining cases where people want/have to continue to use UserType impls. And it gets us out of the String-based resolution at all. Well, from annotations at least.

[sebersole]

org.hibernate.annotations.AnyMetaDef also uses "type name" : #metaType and #idType

[yrodiere]

What would be the solution for automatically applying a custom type to a given class? We used to have @TypeDef#defaultForType, but if you remove @TypeDef...

Thinking about it, shouldn't the solution be similar to @Converter(autoApply = true)? I.e. ask users to just apply an annotation on their custom type, and detect that during classpath scanning?

[sebersole]

Depending on exactly what the custom UserType did...

1. Using AttributeConverter would be the first suggestion. Its good for what it does, though not "complete" - e.g. it misses anything related to what we call MutabilityPlan. And yes, it can be auto-discovered.
2. A custom @JavaTypeRegistration which can also be supplied by TypeContributor, Dialect, etc. TypeContributor is also auto-detected.

[gavinking]

@sebersole I don't think I like this attributeName thing, but I think maybe you already moved away from that, is that right?

[sebersole]

No I like it. It helps solve the fugly annotations-dont-have-inheritance-so-we-need-to-wrap-the-annotation-we-are-interested-in-within-other-annotations. In other words, I find this nicer

@CustomType( typeImplementation = MyUserType.class )
@CustomType( typeImplementation = AnotherUserType.class, attributeName = "key" )
Map someMap;

than

@CustomType( typeImplementation = MyUserType.class )
@MapKeyCustomType( CustomType( typeImplementation = AnotherUserType.class ) )
Map someMap;

at least from the perspective of implementing support for it. In my opinion its arguable which is better from a user perspective and some will prefer one while others prefer the other. But the one argument for it as-is is consistency with JPA e.g. with @Convert, @AttributeOverride, etc

And keep in mind, its not just @MapKeyCustomType that needs this.. we also have

• @AnyMetaDef#metaType
• @AnyMetaDef#idType
• @CollectionId#type
• @ParamDef#type

[beikov]

Are TYPE_USE annotations available via reflection?

Yes, so that will help with the sane cases. If users want to use raw types, they still can use the attribute/path approach

[sebersole]

P.S. on a minor point @sebersole you wrote:

@CustomType( typeImplementation = MyUserType.class )

I think typeImplementation really should be value, otherwise you're disrupting the overwhelmingly most common case which is the use of these annotations on Java fields. For this common case I want to write @JavaType( BitSetJavaType.class ) not @JavaType( typeDescriptor = BitSetJavaType.class ).

Yes. But that was just copy/paste from the form defining attributeName as well. Yes, if there is just one value I'd use value. Ofc then your risk the problem of needing to add an attribute later and then value is (most likely) no longer the right name.

But I agree in that I would do the same with just one attribute

[sebersole]

My point is that:

For things that aren't fields, we don't have a place to put annotations.

And that's the root source of the discomfort.

So create such a place.

Its actually possible to understand what you are saying and yet still disagree with you ;)

I understand exactly what you are saying.

Personally I hate these TYPE_USE annotations generally speaking. I think they make code way harder to read. But its an elegant solution for sure

[sebersole]

Are TYPE_USE annotations available via reflection?

Yes, so that will help with the sane cases. If users want to use raw types, they still can use the attribute/path approach

Minor point, but there will never be such a place for a collection-id.

[sebersole]

Nor ANY mappings

[sebersole]

As I played with prototyping this (and porting tests, especially) I wonder if it is worthwhile to still provide a @TypeDef-like annotation, though limited in its scope to just the "auto-apply" aspect of TypeDef (no "name"). In other words, I think this might be worth-while:

@Repeatable( CustomTypeRegistrations.class )
public @interface CustomTypeRegistration {
	Class<? extends UserType<?>> typeImplementation();
	Class<?>[] autoApplyTo() default {};
	Parameter[] parameters() default {};
}

As well as adjusting TypeContributions:

interface TypeContributions {
    ...
    void contributeType(Class<? extends UserType> impl, Class<?>... autoApplyTo);
}

Coming back to the enum point.. as I mentioned, I think it depends on what we want to support. 2 things in particular I'd like to support that we need to consider here:

1. overrides for embeddable values (think @AttributeOverride, etc)
2. applying this for "entity metadata" - discriminator mostly

And of course it depends how we want to support those.

For discriminator, e.g, do we add a @DiscriminatorCustomType annotation? That kind of defeats the purpose of having a singular annotation for applying custom-types. On the other hand, the alternative is to allow using @CustomType to the entity/mapped-super which makes it confusing - then certain "paths" are valid based on where it is used and #attributeName is required.

For overrides, the difference comes back to needing to supply open-ended values (i.e. actual attribute names)

Don't know the answers yet; just some thoughts that ran through my head as I started implementing this

[gavinking]

My only concern with stuff like @CustomTypeRegistration though it's by no means specific to this annotation, and applies to others that we already have, is: where do I put this annotation that properly reflects to scope to which it applies?

[sebersole]

My only concern with stuff like @CustomTypeRegistration though it's by no means specific to this annotation, and applies to others that we already have, is: where do I put this annotation that properly reflects to scope to which it applies?

I'd limit those to just package and class and say they are global. It's really just an easy form of using TypeContributor

[beikov]

If it is just "sugar", I'd opt to not having the annotation at all and require a TypeContributor instead.

[sebersole]

Yes, it is "sugar". But sugar that is very useful for tests. Unless we add something like @domainmodel( ... typeContributors=... )

Which is fine as well.

[sebersole]

My concern there though is that if our tests need it, it is likely users will also. But I am fine aggressively and proactively defining what we want here and maybe needing to go back and add something like this if enough users complain

[sebersole]

So I changed my mind a bit. I (and I think all of us) would preferred annotations to be able to implement a common interface, but it ofc does not. So the next best thing is to use the nested annotation approach. We can look at the type-use approach later as a possible improvement. So I'll do:

@interface CustomType {
    Class<? extends UserType> value();
    Parameter[] parameters() default [];
}

@interface MapKeyMapping {
    CustomType customType() default ...;
    JavaType javaTypeDescriptor() default ...;
    JdbcType jdbcTypeDescriptor() default ...;
    JavaTypeCode jdbcTypeCode() default ...;
    Mutability mutabilityPlan() default ...;
    // Could just rely on JPA's {@link Convert#attributeName},
    // but I like it being available here as well
    Class<? extends AttributeConverter> converter();
}

/** Could just add to `@CollectionId` instead
@interface CollectionIdMapping {
    CustomType customType() default ...;
    JavaType javaTypeDescriptor() default ...;
    JdbcType jdbcTypeDescriptor() default ...;
    JavaTypeCode jdbcTypeCode() default ...;
    Mutability mutabilityPlan() default ...;
    // Could just rely on JPA's {@link Convert#attributeName},
    // but I like it being available here as well
    Class<? extends AttributeConverter> converter();
}

...

Though, even this might be better to allow for adding addition mapping details

@interface CustomType {
    Class<? extends UserType> value();
    Parameter[] parameters() default [];
}

@interface BasicMapping {
    CustomType customType() default ...;
    JavaType javaTypeDescriptor() default ...;
    JdbcType jdbcTypeDescriptor() default ...;
    JavaTypeCode jdbcTypeCode() default ...;
    Mutability mutabilityPlan() default ...;
    // Could just rely on JPA's {@link Convert#attributeName},
    // but I like it being available here as well
    Class<? extends AttributeConverter> converter();
}

@interface BasicMapKey {
    BasicMapping mapping() default @BasicMapping;
    ...
}

/** 
@interface BasicMapKey {
    BasicMapping mapping() default @BasicMapping;
    ...
}

@interface CollectionId {
    ...
    BasicMapping mapping() default @BasicMapping;
    ...
}

// etc

[sebersole]

I'll send a PR when I am done, so we can fix any of this we need to later, but I am wondering if anyone has improvements to these javadocs so far:

/**
 * Describes the mapping of a basic value.  Supports 2 main approaches for adjusting the
 * default mapping Hibernate will use:<ul>
 *     <li>
 *         (the preferred approach) using composition - <ul>
 *             <li>{@link #javaType()}</li>
 *             <li>{@link #jdbcType()}</li>
 *             <li>{@link #jdbcTypeCode()}</li>
 *             <li>{@link #mutability()}</li>
 *             <li>{@link #immutable()}</li>
 *             <li>{@link #converter()}</li>
 *         </ul>
 *     </li>
 *     <li>
 *         contracted via the {@link UserType} interface and {@link #customType()}
 *     </li>
 * </ul>
 *
 * @see jakarta.persistence.Basic
 */
public @interface BasicMapping {
	/**
	 * Defines the {@link org.hibernate.type.descriptor.java.BasicJavaDescriptor} to use.
	 *
	 * To apply this descriptor as the default for all references of this Java type in
	 * the domain model, use {@link JavaTypeRegistration} or
	 * {@link org.hibernate.boot.model.TypeContributor} instead
	 *
	 * @apiNote Mutually exclusive with specifying {@link #customType()}
	 * @implSpec The supplied Class is resolved as a {@link org.hibernate.resource.beans.spi.ManagedBean}
	 */
	JavaType javaType() default @JavaType( NoJavaTypeDescriptor.class );

	/**
	 * Defines the {@link org.hibernate.type.descriptor.jdbc.JdbcTypeDescriptor} to use
	 *
	 * To apply this descriptor as the default for all resolutions of a particular
	 * type-code (see {@link #jdbcTypeCode()}) within the SessionFactory
	 *
	 * @apiNote Mutually exclusive with specifying {@link #jdbcTypeCode()} or {@link #customType()}
	 * @implSpec The supplied Class is resolved as a {@link org.hibernate.resource.beans.spi.ManagedBean}
	 */
	JdbcType jdbcType() default @JdbcType( NoJdbcTypeDescriptor.class );

	/**
	 * Defines the code the is then used to resolve the
	 * {@link org.hibernate.type.descriptor.jdbc.JdbcTypeDescriptor} to use from the
	 * {@link org.hibernate.type.descriptor.jdbc.spi.JdbcTypeDescriptorRegistry} which
	 * is a configurable mapping of a type-code to a descriptor to use
	 *
	 * @apiNote Mutually exclusive with specifying {@link #jdbcType()} or {@link #customType()}
	 */
	JdbcTypeCode jdbcTypeCode() default @JdbcTypeCode( Integer.MIN_VALUE );

	/**
	 * Defines the {@link org.hibernate.type.descriptor.java.MutabilityPlan} to
	 * apply to the mapping.
	 *
	 * @see Immutable
	 *
	 * @apiNote Mutually exclusive with specifying {@link #immutable()} or {@link #customType()}
	 * @implSpec The supplied Class is resolved as a {@link org.hibernate.resource.beans.spi.ManagedBean}
	 */
	Mutability mutability() default @Mutability( NoMutabilityPlan.class );

	/**
	 * By default, basic value mapping are considered mutability (most anyway, depending
	 * on usage site).  This indicates to treat the value as immutable.  Simplified
	 * alternative to {@link #mutability()} for the common case.
	 *
	 * @apiNote Mutually exclusive with specifying {@link #mutability()} or {@link #customType()}
	 */
	boolean immutable() default false;

	/**
	 * Defines a conversion to be applied to the values
	 *
	 * @apiNote Mutually exclusive with specifying {@link #customType()}
	 * @implSpec The supplied Class is resolved as a {@link org.hibernate.resource.beans.spi.ManagedBean}
	 */
	Class<? extends AttributeConverter> converter() default NoAttributeConverter.class;

	/**
	 * Defines a {@link UserType} implementation to use for mapping the values
	 *
	 * @apiNote Mutually exclusive with specifying {@link #javaType()}, {@link #jdbcType()},
	 * 		{@link #jdbcTypeCode()}, {@link #mutability()}, {@link #immutable()} and {@link #converter()}
	 * @implSpec The supplied Class is resolved as a {@link org.hibernate.resource.beans.spi.ManagedBean}
	 */
	CustomType customType() default @CustomType( NoUserType.class );
}

[yrodiere]

LGTM.

It's interesting, because I think the use case seems somewhat similar to what we have in Hibernate Search, so I'll go ahead and suggest an API similar to what we did in Hibernate Search 6. If that's not relevant, that's fine; I just want to bring it to your attention in case you like it.

I'm assuming that all those options you are providing (javaTypeDescriptor, jdbcTypeDescriptor, mutabilityPlan, etc.) only have a limited amount of valid combinations. If that's wrong, please ignore the rest of this message, as the solution I'm about to propose probably won't be a good fit.

In Hibernate Search, we have a concept of "bridge" and "binder". Both are user-implemented callbacks:

• The "binder" gets called during the mapping phase. It gets access to metadata about the property being "bound", and is able to set metadata about the resulting "column". In your case that metadata would be the javaTypeDescriptor (... I guess?), jdbcTypeDescriptor, mutabilityPlan, and more if you need to.
• The bridge gets called at runtime to perform all operations related to read/write. In your case, I believe that would be the CustomType?

What I'm suggesting is, instead of exposing lots of options in your annotations, you could just provide some "binder" API:

@BasicBinding(binder = MyBinder.class)
MyType myProperty;

public class MyBinder implements CustomTypeBinder {
    public void bind(CustomTypeBindingContext context) {
        context.mutabilityPlan( MutabilityPlan.SOMETHING );
        context.jdbcTypeDescriptor( SomeJdbcTypeDescriptor.INSTANCE );
        context.customType( new MyCustomType() );
    }

    private static class MyCustomType implements CustomType {
        // ...
    }
}

This gives a lot of flexibility. The binder could inspect the property and assign a different custom type depending on the property type, for example:

public class MyBinder implements CustomTypeBinder {
    public void bind(CustomTypeBindingContext context) {
        if ( context.propertyRawType() == String.class ) {
            context.mutabilityPlan( MutabilityPlan.SOMETHING );
            context.jdbcTypeDescriptor( SomeJdbcTypeDescriptor.INSTANCE );
            context.customType( new MyCustomType() );
        }
        else {
            context.mutabilityPlan( MutabilityPlan.SOMETHING_ELSE );
            context.jdbcTypeDescriptor( SomeOtherJdbcTypeDescriptor.INSTANCE );
            context.customType( new MyOtherCustomType() );
        }
    }

    private static class MyCustomType implements CustomType {
        // ...
    }
    private static class MyOtherCustomType implements CustomType {
        // ...
    }
}

Another advantage, though it's in no way necessary if you don't like it, is that you're able to move operations out of CustomType and into multiple interfaces, each dedicated to a certain aspect of reading/writing. You could have a dedicated interface for toXMLString/fromXMLString, a dedicated interface for mutability (with isDirty + deepCopy + any method that only makes sense for mutable types), etc. It helps create an API with more cohesive interfaces.

Here's the documentation of binders/bridges in Hibernate Search, though I don't think it will be very useful to you, since the context operations are not likely to be relevant to Hibernate ORM (they're mostly about defining index fields):

• https://docs.jboss.org/hibernate/search/6.1/reference/en-US/html_single/#mapper-orm-bridge-valuebridge-valuebinder
• https://docs.jboss.org/hibernate/search/6.1/reference/en-US/html_single/#mapper-orm-bridge-propertybridge

[sebersole]

It's a bit difference. All of them affect the resolution of mapping details during boot. At runtime they are all used when actually reading (not yet writing always) values of the particular mapping

[sebersole]

Going to make a change as I got into implementing this...

First, I am going to drop:

• @JavaType
• @JdbcType
• @JdbcTypeCode
• @MutabilityPlan
• @MapKeyJavaType
• @MapKeyJdbcType
• @MapKeyJdbcTypeCode

Then define @BasicMapping as follows (with mostly the same Javadoc as before):

@interface BasicMapping {
    Class<? extends BasicJavaDescriptor<?>> javaType() default NoJavaTypeDescriptor.class;
    Class<? extends JdbcTypeDescriptor<?>> jdbcType() default NoJdbcTypeDescriptor.class;
    int jdbcTypeCode() default Integer.MIN_VALUE;
    Class<? extends MutabilityPlan<?>> mutability() default NoMutabilityPlan.class;
    Class<? extends AttributeConverter> converter() default NoAttributeConverter.class;
    CustomType customType() default @CustomType( NoUserType.class );
}

And then:

@interface BasicMapKey {
    BasicMapping mapping() default @BasicMapping();
    ...
}

@interface CollectionId {
    BasicMapping mapping() default @BasicMapping();
    ...
}

...