Alignment with jakarta.persistence API: @Column can be optional

georgleber commented 1 year ago

Which JNoSQL project the issue refers to?

JNoSQL (Core)

Use case

Coming from an JPA / relational background it was a little counterintuitive that the @Column is mandatory for every field that should be included in the document. Especially for complex relations, that are annotated with @Entity or @Embeddable.

@Entity public class Book {
    @Id  private String id;
    @Column  private String title;
    private Author author; // is not added to document because of missing @Column annotation
}

@Entity
public class Author {
    @Column private String name;
}

Feature proposal

Make @Column optional and mark fields that should be not persisted in the resulting document with @Transient and/or respect the transient keyword.

dearrudam commented 1 year ago

Thanks, @GeorgHenkel for this contribution!

This behavior involves not just only the JNoSQL project but the Jakarta NoSQL specification itself. Maybe it's interesting to address this issue in Jakarta NoSQL specification. What do you think @otaviojava?

otaviojava commented 1 year ago

It is a considerable discussion and requires debates like this.

As with any topic, we are talking about trade-offs.

While the proposal to eliminate the need for the @Column annotation in the Eclipse JNoSQL framework may seem appealing in simplifying the codebase and convention over configuration, it poses several significant drawbacks that outweigh its potential benefits.

Lack of Clarity and Readability: By relying on implicit definitions instead of explicitly stating the mappings with the @Column annotation, the code needs to maintain clarity and become more readable. Other developers unfamiliar with the codebase might need help understanding the underlying mappings between the Java classes and the database schema. Explicit annotations provide clear documentation and make it easier to comprehend the data model.
Potential for Data Inconsistency: Implicit definitions assume that all fields in the Java class correspond to columns in the database. This approach can lead to data inconsistency if there are fields that are not intended to be stored in the database but are mistakenly mapped implicitly. It is crucial to have direct control over which fields are persisted in the database to ensure data integrity and avoid accidental data leakage.
Maintenance and Evolution: Over time, implicit definitions can become harder to manage as the application evolves and the database schema changes. With explicit annotations, modifications to the data model can be easily identified and implemented by updating the corresponding annotations. In contrast, implicit definitions require a thorough analysis of the entire codebase to locate and modify the affected fields, which can be error-prone and time-consuming.
Compatibility and Interoperability: Implicit definitions might only be compatible with some databases and might introduce interoperability issues. Different databases have specific requirements and constraints, and explicit annotations allow for fine-grained control and customization based on the target database. Implicit definitions risk assuming a one-size-fits-all approach, which may not be suitable for all database systems.
For JPA, there is a historical background of several compatibilities, such as XML files. We don't have to support anything like that.

Based on trade-offs, we can define it. One thing we can do is allow the vendor to make this column Optional or not.

georgleber commented 1 year ago

I completely get your points and mostly agree with you that explicit annotations are a better way of documentation and clarity for developers unfamiliar with the codebase. I would definitively go with the current solution of explicit annotations. But I wanted to mentioned it, because with a JPA background I was used to drop the annotations where it is not needed :)

One thing we can do is allow the vendor to make this column Optional or not

When I understand you correct, the vendor can decide, if @Column must be set explicitly or not? In that case I see the need for a new explicit annotation @Transient to make clear, when a field should not be stored. Because if the column is optional, you cannot make transient fields visible except with the Java keyword or an explicit annotation.

otaviojava commented 1 year ago

But I wanted to mentioned it, because with a JPA background I was used to drop the annotations where it is not needed :)

And this point is super important; thank you for raising it.

When I understand you correct, the vendor can decide, if @Column must be set explicitly or not?

It works with explicit annotations, but we can decide to be optional such as JPA or delegates it to the vendors.

eclipse / jnosql