Module jakarta.nosql.core
Package jakarta.nosql

Interface Template

public interface Template
Template is a helper class that increases productivity when performing common NoSQL operations. The Template feature in Jakarta NoSQL simplifies the implementation of common database operations by providing a basic API to the underlying persistence engine. It follows the standard DAO (Data Access Object) pattern, a common design pattern used in software development.

The Template pattern involves creating a skeletal structure for an algorithm, with some steps implemented and others left to be implemented by subclasses. Similarly, the Template feature in Jakarta NoSQL makes a skeleton around NoSQL database operations, allowing developers to focus on implementing the specific logic required for their application.

Overall, the Template feature in Jakarta NoSQL provides a simple and efficient way to implement common database operations while following established design patterns like the Template Method. By using the Template feature, developers can save time and effort in implementing their NoSQL database operations, allowing them to focus on other aspects of their application. 


 @Inject
 Template template;

 Book book = Book.builder()
         .id(id)
         .title("Java Concurrency in Practice")
         .author("Brian Goetz")
         .year(Year.of(2006))
         .edition(1)
         .build();

 template.insert(book);

 Optional<Book> optional = template.find(Book.class, id);

 System.out.println("The result " + optional);

 template.delete(Book.class,id);

Furthermore, in CRUD (Create, Read, Update, Delete) operations, Template provides a fluent API for selecting, deleting, and querying entities, offering the capability to search and remove beyond the ID attribute. Take a look at QueryMapper for more detail about the provided fluent-API. 


 @Inject
 Template template;

 List<Book> books = template.select(Book.class)
         .where("author")
         .eq("Joshua Bloch")
         .and("edition")
         .gt(3)
         .results();

 Stream<Book> books = template.select(Book.class)
         .where("author")
         .eq("Joshua Bloch")
         .stream();

 Optional<Book> optional = template.select(Book.class)
         .where("title")
         .eq("Java Concurrency in Practice")
         .and("author")
         .eq("Brian Goetz")
         .and("year")
         .eq(Year.of(2006))
         .singleResult();

 template.delete(Book.class)
         .where("author")
         .eq("Joshua Bloch")
         .and("edition")
         .gt(3)
         .execute();
Since:
1.0.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    <T> QueryMapper.MapperDeleteFrom
    delete(Class<T> type)
    Start a query builder using the fluent API.
    <T, K> void
    delete(Class<T> type, K id)
    Deletes by ID or key.
    <T, K> Optional<T>
    find(Class<T> type, K id)
    Retrieves an entity by its Id.
    <T> Iterable<T>
    insert(Iterable<T> entities)
    Inserts multiple entities into the database.
    <T> Iterable<T>
    insert(Iterable<T> entities, Duration ttl)
    Inserts multiple entities into the database with the expiration date.
    <T> T
    insert(T entity)
    Inserts an entity into the database.
    <T> T
    insert(T entity, Duration ttl)
    Inserts an entity into the database with an expiration to the entity.
    <T> QueryMapper.MapperFrom
    select(Class<T> type)
    Start a query using the fluent API.
    <T> Iterable<T>
    update(Iterable<T> entities)
    Modifies entities that already exist in the database.
    <T> T
    update(T entity)
    Modifies an entity that already exists in the database.

  • Method Details

    • insert

      <T> T insert(T entity)
      Inserts an entity into the database. If an entity of this type with the same unique identifier already exists in the database and the database supports ACID transactions, then this method raises an error. In databases that follow the BASE model or use an append model to write data, this exception is not thrown.

      The entity instance returned as a result of this method must include all values that were written to the database, including all automatically generated values and incremented values that changed due to the insert. After invoking this method, do not continue to use the instance that is supplied as a parameter. This method makes no guarantees about the state of the instance that is supplied as a parameter.

      Type Parameters:
      T - the entity type
      Parameters:
      entity - the entity to insert. Must not be null.
      Returns:
      the inserted entity, which may or may not be a different instance depending on whether the insert caused values to be generated or automatically incremented.
      Throws:
      NullPointerException - if the entity is null.

    • insert

      <T> T insert(T entity, Duration ttl)
      Inserts an entity into the database with an expiration to the entity. If an entity of this type with the same unique identifier already exists in the database and the database supports ACID transactions, then this method raises an error. In databases that follow the BASE model or use an append model to write data, this exception is not thrown.

      The entity instance returned as a result of this method must include all values that were written to the database, including all automatically generated values and incremented values that changed due to the insert. After invoking this method, do not continue to use the instance that is supplied as a parameter. This method makes no guarantees about the state of the instance that is supplied as a parameter.

      Time-To-Live (TTL) is a feature provided by some NoSQL databases where data is automatically removed from the database after a specified duration. When inserting an entity with a TTL, the entity will be automatically deleted from the database after the specified duration has passed since its insertion. If the database does not support TTL or if the TTL feature is not enabled, this operation will not have any effect on the entity's expiration.

      Type Parameters:
      T - the entity type
      Parameters:
      entity - the entity to insert. Must not be null.
      ttl - time to live
      Returns:
      the inserted entity, which may or may not be a different instance depending on whether the insert caused values to be generated or automatically incremented.
      Throws:
      NullPointerException - if the entity is null.
      UnsupportedOperationException - when the database does not provide TTL

    • insert

      <T> Iterable<T> insert(Iterable<T> entities)
      Inserts multiple entities into the database. If any entity of this type with the same unique identifier as any of the given entities already exists in the database and the database supports ACID transactions, then this method raises an error. In databases that follow the BASE model or use an append model to write data, this exception is not thrown.

      The entities within the returned Iterable must include all values that were written to the database, including all automatically generated values and incremented values that changed due to the insert. After invoking this method, do not continue to use the entity instances that are supplied in the parameter. This method makes no guarantees about the state of the entity instances that are supplied in the parameter. The position of entities within the Iterable return value must correspond to the position of entities in the parameter based on the unique identifier of the entity.

      Type Parameters:
      T - the entity type
      Parameters:
      entities - entities to insert.
      Returns:
      an iterable containing the inserted entities, which may or may not be different instances depending on whether the insert caused values to be generated or automatically incremented.
      Throws:
      NullPointerException - if the iterable is null or any element is null.

    • insert

      <T> Iterable<T> insert(Iterable<T> entities, Duration ttl)
      Inserts multiple entities into the database with the expiration date. If any entity of this type with the same unique identifier as any of the given entities already exists in the database and the database supports ACID transactions, then this method raises an error. In databases that follow the BASE model or use an append model to write data, this exception is not thrown.

      The entities within the returned Iterable must include all values that were written to the database, including all automatically generated values and incremented values that changed due to the insert. After invoking this method, do not continue to use the entity instances that are supplied in the parameter. This method makes no guarantees about the state of the entity instances that are supplied in the parameter. The position of entities within the Iterable return value must correspond to the position of entities in the parameter based on the unique identifier of the entity.

      Time-To-Live (TTL) is a feature provided by some NoSQL databases where data is automatically removed from the database after a specified duration. When inserting entities with a TTL, the entities will be automatically deleted from the database after the specified duration has passed since their insertion. If the database does not support TTL or if the TTL feature is not enabled, this operation will not have any effect on the expiration of the entities.

      Type Parameters:
      T - the entity type
      Parameters:
      entities - entities to insert.
      ttl - time to live
      Returns:
      an iterable containing the inserted entities, which may or may not be different instances depending on whether the insert caused values to be generated or automatically incremented.
      Throws:
      NullPointerException - if the iterable is null or any element is null.
      UnsupportedOperationException - if the database does not provide time-to-live for insert operations.

    • update

      <T> T update(T entity)
      Modifies an entity that already exists in the database.

      For an update to be made, a matching entity with the same unique identifier must be present in the database. In databases that use an append model to write data or follow the BASE model, this method behaves the same as the insert(T) method.

      If the entity is versioned (for example, with an annotation or by another convention from the entity model such as having an attribute named version), then the version must also match. The version is automatically incremented when making the update.

      Non-matching entities are ignored and do not cause an error to be raised.

      Type Parameters:
      T - the entity type
      Parameters:
      entity - the entity to update. Must not be null.
      Returns:
      the updated entity, which may or may not be a different instance depending on whether the update caused values to be generated or automatically incremented.
      Throws:
      NullPointerException - if the entity is null.

    • update

      <T> Iterable<T> update(Iterable<T> entities)
      Modifies entities that already exist in the database.

      For an update to be made to an entity, a matching entity with the same unique identifier must be present in the database. In databases that use an append model to write data or follow the BASE model, this method behaves the same as the insert(Iterable) method.

      If the entity is versioned (for example, with an annotation or by another convention from the entity model such as having an attribute named version), then the version must also match. The version is automatically incremented when making the update.

      Non-matching entities are ignored and do not cause an error to be raised.

      Type Parameters:
      T - the entity class type
      Parameters:
      entities - entities to update.
      Returns:
      the number of matching entities that were found in the database to update.
      Throws:
      NullPointerException - if either the iterable is null or any element is null.

    • find

      <T, K> Optional<T> find(Class<T> type, K id)
      Retrieves an entity by its Id.
      Type Parameters:
      T - the entity class type
      K - the id type
      Parameters:
      type - the entity class
      id - the id value
      Returns:
      the entity instance, otherwise Optional.empty()
      Throws:
      NullPointerException - when either the type or id are null

    • delete

      <T, K> void delete(Class<T> type, K id)
      Deletes by ID or key.
      Type Parameters:
      T - the entity class type
      K - the id type
      Parameters:
      type - the entity class
      id - the id value
      Throws:
      NullPointerException - when either the type or id are null

    • select

      <T> QueryMapper.MapperFrom select(Class<T> type)
      Start a query using the fluent API. The return value is a mutable and non-thread-safe instance.
      Type Parameters:
      T - the entity type
      Parameters:
      type - the entity class
      Returns:
      a QueryMapper.MapperFrom instance
      Throws:
      NullPointerException - when type is null
      UnsupportedOperationException - when the database cannot operate, such as key-value where most operations are key-based.

    • delete

      <T> QueryMapper.MapperDeleteFrom delete(Class<T> type)
      Start a query builder using the fluent API. The returned value is a mutable and non-thread-safe instance.
      Type Parameters:
      T - the entity type
      Parameters:
      type - the entity class
      Returns:
      a QueryMapper.MapperDeleteFrom instance
      Throws:
      NullPointerException - when type is null
      UnsupportedOperationException - when the database cannot operate, such as key-value where most operations are key-based.