Jakarta NoSQL

The complete list of Jakarta NoSQL contributors may be found here.

A field of an entity class may or may not represent state which is persistent in the datastore. A persistent field has some corresponding representation in the data schema of the entity.

Every programming model for entity classes must support direct field access, that is, access to the persistent fields of an entity class without triggering any intermediating user-written code such as JavaBeans-style property accessors.

A programming model might place constraints on the visibility of persistent fields.

Jakarta NoSQL distinguishes three kinds of persistent field within entity classes.

Every Jakarta NoSQL provider must support the following basic types within its programming model:

For example, the following entity class has five basic fields:

In addition to the types listed above, an entity programming model might support additional domain-specific basic types. This extended set of basic types might include types with a nontrivial internal structure. An entity programming model might even provide mechanisms to convert between user-written types and natively-supported basic types, defined at the AttributeConverter interface.

An embeddable class differs from an entity class in that:

An embedded field is a field whose type is an embeddable class.

Embeddable classes may have basic, embeddable, and association fields, but unlike entities, they do not have identifier fields.

Like entities, a programming model for entity classes might support mutable embeddable classes, immutable embeddable classes, or both.

Jakarta NoSQL defines an annotation identifying a user-written class as an embeddable class: jakarta.nosql.Embeddable.

There are two natural ways that a Jakarta NoSQL provider might store the state of an instance of an embedded class in a database:

In a flattened representation of an embedded field, the fields of the embeddable class occur directly alongside the basic fields of the entity class in the data schema of the entity. There is no representation of the embeddable class itself in the data schema.

To ensure compatibility with Jakarta NoSQL, an embeddable class must adhere to the following constructor rules:

For example, consider the following Java classes:

In a document, wide-column, or graph database, the JSON representation of an instance of the Person entity where the Address class is flat might be:

In a structured representation, when the embeddable field is grouping it will be together in the data schema.

In a document, wide-column, or graph database, the JSON representation of an instance of the Person entity where the Address class is grouping might be:

When an embeddable class is used within an iterable field of an entity class, both embedding strategies, namely flattening and grouping, will function as grouping. This means that the fields of the embeddable class will be grouped together within the data schema, regardless of whether the embeddable class is marked for flattening or grouping.

For example, consider the following entity class Driver containing an iterable of Car instances:

In this scenario, the Car embeddable class is used within the cars field, which is an iterable in the Driver entity class. As a result, the embedding strategy will behave as grouping, regardless of whether the Car class is marked with the @Embeddable(GROUPING) annotation.

The JSON representation of an instance of the Driver entity might appear as follows:

In this JSON representation, the cars field contains an array of Car objects, each with its own plate and category fields. This structure reflects the grouping embedding strategy, where the fields of the Car embeddable class are grouped together within the Driver entity’s data schema.

Additionally, it’s important to note that support for embedding with a Map may vary by NoSQL database and Jakarta NoSQL provider. Different providers may have different approaches or limitations regarding the embedding of data structures such as maps with embeddable classes. Developers should consult the documentation of their chosen NoSQL database and Jakarta NoSQL provider for specific details and considerations regarding map embedding.

An association field is a field of an entity class whose declared type is also an entity class. Given an instance of the first entity class, its association field references an instance of a second entity class.

For example, consider the following Java classes:

For example, the JSON representation of Author might be:

In this scenario, the association between Author and Book is represented by the books field in the Author entity class. Since NoSQL databases do not support joins, the association field behaves as a grouping embedded field defined at Embedded Fields and Embeddable Classes . It means that the books field groups together instances of the Book entity within the Author entity’s data schema.

A persistent field or property of an entity or embeddable class may correspond to a collection of a basic type, embeddable, or entity class.

No action is required beyond including the Column annotation for a collection of basic types.

The entity class will behave as an embeddable grouping class. This support may vary among NoSQL providers and might require a UDT name presentation in the case of embeddable or entity.

For key-value databases, the serialization will occur through a unique blob, a process outside the scope of the Jakarta NoSQL specification.

Collections within entities can accommodate various types of data, including basic types and complex structures like lists of strings. Jakarta NoSQL provides flexibility in handling such collections, ensuring seamless integration with the underlying NoSQL database.

Java Map collections offer a convenient way to represent associations and key-value pairs within entities in Jakarta NoSQL. Jakarta NoSQL handles map collections, allowing developers to manage complex data structures efficiently.

JSON representation:

In the example above, the Contact entity includes a socialMedia field, represented as a Map where the key is a string representing the social media platform, and the value is the corresponding username or profile link.

The behavior of map collections remains consistent regardless of whether the map values are basic types, embeddable classes, or entity classes. However, for embeddable or entity classes used as map values, the udt attribute may be required in the @Column annotation to specify the user-defined type.

For instance, consider the following example:

JSON representation:

The Computer entity includes a programs field, a map where the keys represent program names, and the values are instances of the Program embeddable class. Each Program instance contains its own socialMedia map, representing the social media profiles associated with that program.

It’s important to note that support for map collections may vary depending on the NoSQL database and Jakarta NoSQL provider used. Developers should consult the documentation of their chosen provider for specific details and considerations regarding map collections.

Within an entity, property names must be unique ignoring case. For simple entity properties, the field or accessor method name serves as the entity property name. In the case of embedded classes, entity property names are computed by concatenating the field or accessor method names at each level, optionally joined by a delimiter.

First, let’s establish a reference for entity definition, denoted by Entity Classes. In Jakarta NoSQL, an entity class is typically annotated with @Entity to indicate its persistent nature.

In this example, the Person class is defined as an entity with an id field annotated with @Id, which designates it as the primary key, and a name field annotated with @Column, indicating it as a persistent attribute.

One of the notable features of Jakarta NoSQL is its support for immutable and mutable entity classes. For immutable classes, Jakarta NoSQL provides compatibility with Java records, allowing developers to define compact and immutable entity structures concisely.

In this sample, the Person class is defined as a record, capturing its immutable nature. The @Id and @Column annotations are applied directly to the constructor parameters, indicating the primary key and persistent attributes.

The serialization method of entity classes may vary depending on the NoSQL vendor and configuration. Here’s a sample JSON structure representing a Person entity:

This JSON structure captures the serialized representation of a Person entity with its id and name attributes. The specific serialization method may differ based on the chosen NoSQL vendor and its corresponding serialization mechanisms.

One of the powerful features of Jakarta NoSQL is its ability to associate entities with each other, enabling the creation of complex data structures. When an entity is related to another entity, it is incorporated as an embeddable group within the parent entity, as defined by Embedded Fields and Embeddable Classes . Let’s consider an example where a Person entity is associated with an Address entity:

In this example, the Person entity includes a field address of type Address, indicating the association between the two entities. The address field will be represented as a nested structure within the Person entity when serialized.

The serialization method of entity classes may vary depending on the NoSQL vendor. Here’s a sample JSON structure representing a Person entity with an associated Address:

This JSON structure represents a serialized Person entity with id, name, and address attributes. The address field is a nested structure that includes city and street attributes from the associated Address entity.

Entities can also be associated using collection types like Iterable, such as List or Set. Let’s consider an example where an Owner entity is associated with multiple Car entities:

In this example, the Owner entity includes a field cars of type List<Car>, indicating an association between the two entities. The cars field will hold a collection of Car entities associated with the Owner.

The serialization method of entity classes may vary depending on the NoSQL vendor. Here’s a sample JSON structure representing an Owner entity with associated Car entities:

This JSON structure represents a serialized Owner entity with name and cars attributes. The cars field is an array containing nested structures representing associated Car entities.

In Jakarta NoSQL, an abstract class can be specified as an entity, providing a mechanism for defining common attributes and behaviors that are shared among multiple concrete subclasses. An abstract entity class is annotated with the @Entity annotation, indicating its role as a mapped entity within the data model.

Abstract entity classes in Jakarta NoSQL differ from concrete entities primarily in their inability to be directly instantiated. Instead, abstract entities serve as templates or blueprints for concrete subclasses, encapsulating shared functionality and defining a common interface for their subclasses to implement.

Despite being abstract, abstract entity classes are fully mapped as entities and can participate in data manipulation operations such as queries. Queries targeting abstract entity classes will operate over and/or retrieve instances of their concrete subclasses, allowing for polymorphic queries that span the entire inheritance hierarchy.

By leveraging abstract entity classes, developers can effectively organize and structure their data model, promoting code reuse, maintainability, and scalability. Abstract entities encapsulate common attributes and behaviors, fostering a modular and extensible design approach within Jakarta NoSQL applications.

The @MappedSuperclass annotation designates a class whose mapping information is applied to the entities that inherit from it. Unlike regular entities, a mapped superclass does not imply the existence of a separate storage structure such as tables in relational databases.

In NoSQL databases, where data is often stored in a schema-less or schema-flexible manner, the concept of inheritance may not directly correspond to table inheritance as seen in relational databases. However, the @MappedSuperclass annotation serves a similar purpose by allowing common mappings to be defined in a superclass and inherited by its subclasses.

For example, consider a mapped superclass Animal:

In this example, the Animal class serves as a mapped superclass where common attributes like breed and age are defined. Subclasses, such as Dog, can then inherit these mappings, enabling a consistent data model across entities while accommodating the flexibility of NoSQL database structures.

Here’s a JSON sample demonstrating the usage of Animal in a subclass Dog:

In this JSON representation, the attributes breed and age from the Animal superclass are inherited by the Dog entity, showcasing the application of mapped superclass mappings to its subclasses.

The @Inheritance annotation in Jakarta NoSQL enables the use of inheritance strategies within the data model, allowing for the creation of class hierarchies where subclasses inherit attributes and behaviors from their superclass. By applying @Inheritance to the superclass, developers can define the inheritance strategy to be used for mapping the class hierarchy to the underlying NoSQL database.

Consider the following example:

In Jakarta NoSQL, a unique strategy is employed where a single data structure per class hierarchy is utilized. In this strategy, all classes in the hierarchy are mapped to a single data structure in the database. The structure includes a "discriminator column," which serves to identify the specific subclass to which each instance belongs. This approach facilitates polymorphic relationships between entities and enables queries that span the entire class hierarchy.

However, this strategy does have a drawback: it requires that fields corresponding to subclass-specific state be nullable. Despite this limitation, the @Inheritance annotation provides a powerful mechanism for organizing and structuring data within Jakarta NoSQL applications, supporting code reuse, maintainability, and flexibility in data modeling.

It’s important to note that the @Inheritance annotation works in conjunction with other annotations such as @DiscriminatorValue and @DiscriminatorColumn, which further refine the inheritance mapping strategy and specify how subclass instances are differentiated within the single data structure.

The @DiscriminatorColumn annotation is utilized to specify the discriminator column for the inheritance mapping strategy within an entity class hierarchy. This annotation is typically applied at the root of the hierarchy, although it can also be used within subhierarchies if a different inheritance strategy is applied.

When using inheritance mapping, the discriminator column serves as a means to differentiate between different subclasses of the entity. This column holds a value that identifies the specific subclass represented by each entity instance in the database.

If the @DiscriminatorColumn annotation is not explicitly provided, and a discriminator column is required, the default name for the column is typically "DTYPE" or "dtype", depending on the NoSQL provider. The discriminator type is set to STRING.

It’s essential to note that the @DiscriminatorColumn annotation can be applied to both concrete and abstract entity classes. This flexibility allows for precise control over the inheritance mapping strategy within the entity hierarchy.

Let’s illustrate the usage of the @DiscriminatorColumn annotation with an example:

In this example, the Notification class is marked as abstract and serves as the root of an inheritance hierarchy. The @DiscriminatorColumn("type") annotation specifies that the discriminator column for this hierarchy will be named "type". This column will hold values indicating the specific subclass type for each entity instance.

This annotation specifies the value of the discriminator column for entities of the given type.

The DiscriminatorValue annotation can only be specified on a concrete entity class. If the DiscriminatorValue annotation is not specified, a provider-specific function will be used to generate a value representing the entity type. By default, the discriminator value is derived from the Class.getSimpleName().

The inheritance strategy and the discriminator column are only specified in the root of an entity class hierarchy or subhierarchy in which a different inheritance strategy is applied. The discriminator value, if not defaulted, should be specified for each entity class in the hierarchy.

This JSON structure represents three different types of notifications: SMS, Email, and Social Media. Each notification has a unique ID, a name, a creation date, and type-specific attributes such as phone number or username. The discriminator value "type" indicates the specific subclass of the Notification entity.

In case of querying an entity using the @Inheritance annotation as defined by @Inheritance, the Jakarta NoSQL provider must automatically include the condition where the value from @DiscriminatorColumn equals the value of @DiscriminatorValue.

For example, given the sample code from @Inheritance and executing the query for SmsNotification, the generated query should include a condition such as type = 'SMS' or its equivalent in the respective NoSQL database.

The fluent API query is essential for Java developers as it simplifies retrieving and manipulating data from the NoSQL database. By providing a fluent interface, Jakarta NoSQL enables developers to express their query logic concisely and readably, making it easier to understand and maintain the codebase.

The fluent API query also allows developers to build dynamic queries at runtime by chaining together various methods and conditions. This flexibility enables applications to adapt to changing requirements and user inputs, providing a more robust and responsive user experience.

Furthermore, the fluent API query promotes code reuse and modularity by encapsulating query logic within reusable components. Developers can define and combine reusable query fragments to construct more complex queries, reducing duplication and improving code maintainability.

It is worth noting that the select and delete methods of the Template class may not be fully compatible with key-value databases. This limitation arises because key-value databases primarily rely on key-value pairs for data retrieval and deletion rather than complex query predicates.

The primary data access mode in key-value databases is through direct lookup by key. It is challenging to support complex query operations like those provided by the fluent API query. As a result, attempts to use the select and delete methods with key-value databases may throw an UnsupportedOperationException by Jakarta NoSQL, indicating that the underlying database technology does not support the operation.

The fluent API query offers a wide range of supported methods through the QueryMapper class for other types of NoSQL databases, such as document-oriented or column-family databases. These methods may include filtering, sorting, and basic querying capabilities, providing developers with flexible data retrieval and manipulation tools.

However, it’s essential to consider that the availability of certain query methods may vary depending on the specific NoSQL database being used. NoSQL databases that do not support certain operations can raise UnsupportedOperationException.

Attempting to use unsupported operations with the fluent API query may result in runtime exceptions or unexpected behavior. Developers should consult the documentation of their chosen NoSQL database to understand its query capabilities and limitations and adjust their application logic accordingly.

In Jakarta NoSQL, the query navigation hierarchy refers to navigating through the properties of entities and their associated classes when constructing queries. Within an entity, property names must be unique, ignoring cases. For simple entity properties, the field or accessor method name serves as the entity property name. In the case of embedded and association classes, entity property names are computed by concatenating the field or accessor method names at each level, optionally joined by a dot or period, ., delimiter.

Within a given entity or embeddable class, names assigned to persistent fields must be unique, ignoring cases.

Furthermore, within the context of a given entity, each persistent field of an embeddable class reachable by navigation from the entity class may be assigned a compound name. The compound name is obtained by concatenating the names assigned to each field traversed by navigation from the entity class to the persistent field of the embedded class, optionally joined by a delimiter.

For example, consider the following data model:

In this scenario, querying for records based on the zip code of the MailingAddress class requires accessing the address field of Person and the zipcode property of MailingAddress.

In the above example, the fluent API query navigates through the properties of the Person entity to access the zipcode property of the MailingAddress embedded class. The where clause specifies the path to the zipcode property using dot notation (address.zipcode). The orderBy clause similarly specifies the path to the city property for sorting the results by city in ascending order.

This query navigation hierarchy enables developers to construct complex queries traverse multiple levels of entity properties, facilitating flexible and precise data retrieval and manipulation in Jakarta NoSQL.

In environments where CDI Full or CDI Lite is available, Jakarta NoSQL providers can leverage CDI extensions to enhance the integration and discovery of entities or implementations. While Jakarta NoSQL does not prescribe a specific type of CDI extension, it does require Jakarta NoSQL providers to ensure that template implementations are injected into appropriate injection points, typically interfaces, without additional qualifiers.

It’s important to note the distinction between CDI Full and CDI Lite: CDI Full, part of the Jakarta Web profile and Jakarta Platform, includes support for jakarta.enterprise.inject.spi.Extension, whereas CDI Lite (Jakarta Core profile) does not. However, both CDI Full and CDI Lite support jakarta.enterprise.inject.build.compatible.spi.BuildCompatibleExtension.

To avoid conflicts between the BuildCompatibleExtension and portable Extension in CDI Full environments, Jakarta NoSQL providers can utilize CDI’s @SkipIfPortableExtensionPresent annotation.

CDI provides a robust foundation for integrating Jakarta NoSQL repositories into Jakarta EE applications, offering flexibility and extensibility to meet diverse requirements and use cases.