Ease use of records of basic types

[nlisker]

JPA allows fields to be Basic Types or Embeddable Classes, the latter of which can be a record. An existing pattern for type safety is to wrap a Java primitive types, UUID, or String (all of which are basic types) in a record. For example, instead of representing all the IDs as longs or UUIDs and all names as String, one can use record BookId(long id), record CatalogId(long id), record BookName(String name), and record StreetName(String name) as a means to enforce correctness.

Currently, this is possible through embeddable types:

@Entity
public class Library {

    @EmbeddedId
    LibraryId id;

    @Embedded
    LibraryName name;

    @Embedded
    StreetName streetName;

    @Embedded
    CatalogId catalogId;
}

// no annotation needed according to @EmbeddedId's docs
public record LibraryId(UUID libraryId) {}

@Embeddable
public record StreetName(String streetName) {}

@Embeddable
public record LibraryName(String name) {}

@Embeddable
public record CatalogId(long catalogId) {}

The use of records in such a way will probably increase in popularity when value classes are introduced, which will minimize the performance impact of the wrapper indirection.

I'd like to explore the idea of extending the allowed persistent fields to include "records of Basic Types". This will eliminate the "noise"/ceremony of the @Embeddable <-> @Embedded annotations. In terms of implementation, there is no ambiguity - the field is created through the canonical constructor and retrieved through its accessor. This change is also backwards compatible. The risk here is increasing the complexity of the mental model of the user and the code as it may not be clear if a type requires the annotations or not. However, this is part of the user's domain and their responsibility, and the current list of allowed non-primitive types is already relatively arbitrary (I use this term loosely, it's various time-related classes).

[gavinking]

Since the @Embedded annotation is already optional, this amounts to a request that @Embeddable be made optional, but only for certain classes (record types with just one member).

But I guess I'm struggling to see the logic in that. We could just as easily remove the requirement for the @Embeddable annotation all embeddable types, and say something like: if the field has no mapping annotation, and the type of the field is not a basic type, and has no auto-applied converter, then it is interpreted as an embeddable type (in section 2.10).

So then the first question would be: is there any good or logical reason to special case "records with just one member" in the specification?

Well, actually, I can imagine one justification for special-casing "records with just one member", though your proposal doesn't mention it. It would let you write something like this, which is not currently possible with embeddable types:

    @Embedded
    @Column("library_name")
    LibraryName name;

That is, we might be able to let you put the @Column annotation on the use-side, which is better than having to use the ugly @AttributeOverride annotation. So that's something.

But, I dunno, the value here seems quite marginal. I guess I would probably want to see some good evidence that this idiom is actually popular before taking any action on this.

[nlisker]

the @Embedded annotation is already optional

Interesting, I haven't seen this mentioned in its specs nor in its JavaDoc.

So then the first question would be: is there any good or logical reason to special case "records with just one member" in the specification?

My proposal is more restricted, it's "records with just on Basic Type member" (or, including records of embeddable types). A "record of any just one member" doesn't really help because when that member is not one of the listed above, there's no conversion for it. As least that's what I understand.

But I guess I'm struggling to see the logic in that. We could just as easily remove the requirement for the @embeddable annotation all embeddable types, and say something like: if the field has no mapping annotation, and the type of the field is not a basic type, and has no auto-applied converter, then it is interpreted as an embeddable type (in section 2.10).

Then I must ask why was @Embeddable needed to begin with? I could ask the same about @Embedded.

But, I dunno, the value here seems quite marginal. I guess I would probably want to see some good evidence that this idiom is actually popular before taking any action on this.

Yes, the value is not that large even if @Embedded was not optional, but it's a relatively small disruption for a QOL feature. It's why I asked to explore the idea and not to "just" do it :)
As for the popularity, it's difficult for me to gauge. I know I use it. I can link to several talks in which this idiom has been promoted. My thinking was that this should be available before value classes are introduced (during their preview for example) so that we won't need to wait for another EE release after that.

[beikov]

My understanding is that if the Java type of a persistent attribute that has no @Basic or @Embedded is:

• Not a supported basic type
• Not a known @Embeddable type

Then there is a fallback to use Java Serialization if the type implements the java.io.Serializable interface. Since many embeddable types are also Serializable, the @Embedded or @Embeddable annotations would serve to disambiguate such cases and allow to decide for one or the other mapping.

[gavinking]

Interesting, I haven't seen this mentioned in its specs nor in its JavaDoc.

So this is very clearly stated in:

1. the spec section I already linked in my previous comment, and
2. in the Hibernate documentation.

among many other sources.

FTR, the spec says:

If the type of the field or property is a class annotated with the Embeddable annotation, the field or property is treated as if it were annotated with the Embedded annotation

And the Hibernate docs say:

JPA provides an @Embedded annotation to identify an attribute of an entity that refers to an embeddable type. This annotation is completely optional, and so we don’t usually use it.

So TBF this is not really a secret.

I agree that it would be worth mentioning this explicitly in the Javadoc for @Embedded.

[gavinking]

Then I must ask why was @Embeddable needed to begin with? I could ask the same about @Embedded.

Around here we are not in general especially keen on "implicit magic". And indeed the case @beikov mentions above is a pretty good example of why: I think we all agree that the magical default of "persist any serializable Java type via serialization to binary" is a misfeature and not something we should have done.