Provides Optional support inside Hibernate with Panache and MongoDB with Panache

docs/src/main/asciidoc/hibernate-orm-panache.adoc

@@ -161,6 +161,10 @@ List<Person> allPersons = Person.listAll();
 // finding a specific person by ID
 person = Person.findById(personId);
 
+// finding a specific person by ID via an Optional
+Optional<Person> optional = Person.findByIdOptional(personId);
+person = optional.orElseThrow(() -> new NotFoundException());
+
 // finding all living persons
 List<Person> livingPersons = Person.list("status", Status.Alive);
 

docs/src/main/asciidoc/mongodb-panache.adoc

@@ -196,6 +196,10 @@ List<Person> allPersons = Person.listAll();
 // finding a specific person by ID
 person = Person.findById(personId);
 
+// finding a specific person by ID via an Optional
+Optional<Person> optional = Person.findByIdOptional(personId);
+person = optional.orElseThrow(() -> new NotFoundException());
+
 // finding all living persons
 List<Person> livingPersons = Person.list("status", Status.Alive);
 

extensions/panache/hibernate-orm-panache/runtime/src/main/java/io/quarkus/hibernate/orm/panache/PanacheEntityBase.java

@@ -2,6 +2,7 @@
 
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.stream.Stream;
 
 import javax.json.bind.annotation.JsonbTransient;
@@ -115,6 +116,29 @@ public static <T extends PanacheEntityBase> T findById(Object id, LockModeType l
         throw JpaOperations.implementationInjectionMissing();
     }
 
+    /**
+     * Find an entity of this type by ID.
+     *
+     * @param id the ID of the entity to find.
+     * @return if found, an optional containing the entity, else <code>Optional.empty()</code>.
+     */
+    @GenerateBridge
+    public static <T extends PanacheEntityBase> Optional<T> findByIdOptional(Object id) {
+        throw JpaOperations.implementationInjectionMissing();
+    }
+
+    /**
+     * Find an entity of this type by ID.
+     *
+     * @param id the ID of the entity to find.
+     * @param lockModeType the locking strategy to be used when retrieving the entity.
+     * @return if found, an optional containing the entity, else <code>Optional.empty()</code>.
+     */
+    @GenerateBridge
+    public static <T extends PanacheEntityBase> Optional<T> findByIdOptional(Object id, LockModeType lockModeType) {
+        throw JpaOperations.implementationInjectionMissing();
+    }
+
     /**
      * Find entities using a query, with optional indexed parameters.
      *

extensions/panache/hibernate-orm-panache/runtime/src/main/java/io/quarkus/hibernate/orm/panache/PanacheQuery.java

@@ -1,6 +1,7 @@
 package io.quarkus.hibernate.orm.panache;
 
 import java.util.List;
+import java.util.Optional;
 import java.util.stream.Stream;
 
 import javax.persistence.LockModeType;
@@ -163,6 +164,15 @@ public interface PanacheQuery<Entity> {
      */
     public <T extends Entity> T firstResult();
 
+    /**
+     * Returns the first result of the current page index. This ignores the current page size to fetch
+     * a single result.
+     *
+     * @return if found, an optional containing the entity, else <code>Optional.empty()</code>.
+     * @see #singleResultOptional()
+     */
+    public <T extends Entity> Optional<T> firstResultOptional();
+
     /**
      * Executes this query for the current page and return a single result.
      * 
@@ -172,4 +182,13 @@ public interface PanacheQuery<Entity> {
      * @see #firstResult()
      */
     public <T extends Entity> T singleResult();
+
+    /**
+     * Executes this query for the current page and return a single result.
+     *
+     * @return if found, an optional containing the entity, else <code>Optional.empty()</code>.
+     * @throws NonUniqueResultException if there are more than one result
+     * @see #firstResultOptional()
+     */
+    public <T extends Entity> Optional<T> singleResultOptional();
 }

extensions/panache/hibernate-orm-panache/runtime/src/main/java/io/quarkus/hibernate/orm/panache/PanacheRepositoryBase.java

@@ -2,6 +2,7 @@
 
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.stream.Stream;
 
 import javax.persistence.LockModeType;
@@ -113,6 +114,28 @@ public default Entity findById(Id id, LockModeType lockModeType) {
         throw JpaOperations.implementationInjectionMissing();
     }
 
+    /**
+     * Find an entity of this type by ID.
+     *
+     * @param id the ID of the entity to find.
+     * @return if found, an optional containing the entity, else <code>Optional.empty()</code>.
+     */
+    @GenerateBridge
+    public default Optional<Entity> findByIdOptional(Id id) {
+        throw JpaOperations.implementationInjectionMissing();
+    }
+
+    /**
+     * Find an entity of this type by ID.
+     *
+     * @param id the ID of the entity to find.
+     * @return if found, an optional containing the entity, else <code>Optional.empty()</code>.
+     */
+    @GenerateBridge
+    public default Optional<Entity> findByIdOptional(Id id, LockModeType lockModeType) {
+        throw JpaOperations.implementationInjectionMissing();
+    }
+
     /**
      * Find entities using a query, with optional indexed parameters.
      * 

extensions/panache/hibernate-orm-panache/runtime/src/main/java/io/quarkus/hibernate/orm/panache/runtime/JpaOperations.java

@@ -3,6 +3,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Map.Entry;
+import java.util.Optional;
 import java.util.stream.Stream;
 
 import javax.persistence.EntityManager;
@@ -201,6 +202,14 @@ public static Object findById(Class<?> entityClass, Object id, LockModeType lock
         return getEntityManager().find(entityClass, id, lockModeType);
     }
 
+    public static Optional<?> findByIdOptional(Class<?> entityClass, Object id) {
+        return Optional.ofNullable(findById(entityClass, id));
+    }
+
+    public static Optional<?> findByIdOptional(Class<?> entityClass, Object id, LockModeType lockModeType) {
+        return Optional.ofNullable(findById(entityClass, id, lockModeType));
+    }
+
     public static PanacheQuery<?> find(Class<?> entityClass, String query, Object... params) {
         return find(entityClass, query, null, params);
     }

extensions/panache/hibernate-orm-panache/runtime/src/main/java/io/quarkus/hibernate/orm/panache/runtime/PanacheQueryImpl.java

@@ -2,10 +2,12 @@
 
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.stream.Stream;
 
 import javax.persistence.EntityManager;
 import javax.persistence.LockModeType;
+import javax.persistence.NonUniqueResultException;
 import javax.persistence.Query;
 
 import io.quarkus.hibernate.orm.panache.PanacheQuery;
@@ -139,10 +141,27 @@ public <T extends Entity> T firstResult() {
         return list.isEmpty() ? null : list.get(0);
     }
 
+    @Override
+    public <T extends Entity> Optional<T> firstResultOptional() {
+        return Optional.ofNullable(firstResult());
+    }
+
     @Override
     @SuppressWarnings("unchecked")
     public <T extends Entity> T singleResult() {
         jpaQuery.setMaxResults(page.size);
         return (T) jpaQuery.getSingleResult();
     }
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public <T extends Entity> Optional<T> singleResultOptional() {
+        jpaQuery.setMaxResults(2);
+        List<T> list = jpaQuery.getResultList();
+        if (list.size() == 2) {
+            throw new NonUniqueResultException();
+        }
+
+        return list.isEmpty() ? Optional.empty() : Optional.of(list.get(0));
+    }
 }

extensions/panache/mongodb-panache/runtime/src/main/java/io/quarkus/mongodb/panache/PanacheMongoEntityBase.java

@@ -2,6 +2,7 @@
 
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.stream.Stream;
 
 import org.bson.Document;
@@ -85,6 +86,17 @@ public static <T extends PanacheMongoEntityBase> T findById(Object id) {
         throw MongoOperations.implementationInjectionMissing();
     }
 
+    /**
+     * Find an entity of this type by ID.
+     *
+     * @param id the ID of the entity to find.
+     * @return if found, an optional containing the entity, else <code>Optional.empty()</code>.
+     */
+    @GenerateBridge
+    public static <T extends PanacheMongoEntityBase> Optional<T> findByIdOptional(Object id) {
+        throw MongoOperations.implementationInjectionMissing();
+    }
+
     /**
      * Find entities using a query, with optional indexed parameters.
      *

extensions/panache/mongodb-panache/runtime/src/main/java/io/quarkus/mongodb/panache/PanacheMongoRepositoryBase.java

@@ -2,6 +2,7 @@
 
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.stream.Stream;
 
 import org.bson.Document;
@@ -91,6 +92,17 @@ public default Entity findById(Id id) {
         throw MongoOperations.implementationInjectionMissing();
     }
 
+    /**
+     * Find an entity of this type by ID.
+     *
+     * @param id the ID of the entity to find.
+     * @return if found, an optional containing the entity, else <code>Optional.empty()</code>.
+     */
+    @GenerateBridge
+    public default Optional<Entity> findByIdOptional(Id id) {
+        throw MongoOperations.implementationInjectionMissing();
+    }
+
     /**
      * Find entities using a query, with optional indexed parameters.
      * 

extensions/panache/mongodb-panache/runtime/src/main/java/io/quarkus/mongodb/panache/PanacheQuery.java

@@ -1,6 +1,7 @@
 package io.quarkus.mongodb.panache;
 
 import java.util.List;
+import java.util.Optional;
 import java.util.stream.Stream;
 
 import io.quarkus.panache.common.Page;
@@ -147,11 +148,30 @@ public interface PanacheQuery<Entity> {
      */
     public <T extends Entity> T firstResult();
 
+    /**
+     * Returns the first result of the current page index. This ignores the current page size to fetch
+     * a single result.
+     *
+     * @return if found, an optional containing the entity, else <code>Optional.empty()</code>.
+     * @see #singleResultOptional()
+     */
+    public <T extends Entity> Optional<T> firstResultOptional();
+
     /**
      * Executes this query for the current page and return a single result.
      * 
-     * @return the single result (throws if there is not exactly one)
+     * @return the single result
+     * @throws PanacheQueryException if there is not exactly one result.
      * @see #firstResult()
      */
     public <T extends Entity> T singleResult();
+
+    /**
+     * Executes this query for the current page and return a single result.
+     *
+     * @return if found, an optional containing the entity, else <code>Optional.empty()</code>.
+     * @throws PanacheQueryException if there is more than one result.
+     * @see #firstResultOptional()
+     */
+    public <T extends Entity> Optional<T> singleResultOptional();
 }

extensions/panache/mongodb-panache/runtime/src/main/java/io/quarkus/mongodb/panache/runtime/MongoOperations.java

@@ -4,6 +4,7 @@
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -282,6 +283,10 @@ public static Object findById(Class<?> entityClass, Object id) {
         return collection.find(new Document(ID, id)).first();
     }
 
+    public static Optional findByIdOptional(Class<?> entityClass, Object id) {
+        return Optional.ofNullable(findById(entityClass, id));
+    }
+
     public static PanacheQuery<?> find(Class<?> entityClass, String query, Object... params) {
         return find(entityClass, query, null, params);
     }

extensions/panache/mongodb-panache/runtime/src/main/java/io/quarkus/mongodb/panache/runtime/PanacheQueryImpl.java

@@ -2,6 +2,7 @@
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 import java.util.stream.Stream;
 
 import org.bson.Document;
@@ -12,6 +13,7 @@
 
 import io.quarkus.mongodb.panache.PanacheQuery;
 import io.quarkus.panache.common.Page;
+import io.quarkus.panache.common.exception.PanacheQueryException;
 
 public class PanacheQueryImpl<Entity> implements PanacheQuery<Entity> {
     private MongoCollection collection;
@@ -133,14 +135,30 @@ public <T extends Entity> T firstResult() {
         return list.isEmpty() ? null : list.get(0);
     }
 
+    @Override
+    public <T extends Entity> Optional<T> firstResultOptional() {
+        return Optional.ofNullable(firstResult());
+    }
+
     @Override
     @SuppressWarnings("unchecked")
     public <T extends Entity> T singleResult() {
         List<T> list = list();
         if (list.isEmpty() || list.size() > 1) {
-            throw new RuntimeException("There should be only one result");//TODO use proper exception
+            throw new PanacheQueryException("There should be only one result");
         }
 
         return list.get(0);
     }
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public <T extends Entity> Optional<T> singleResultOptional() {
+        List<T> list = list();
+        if (list.size() > 1) {
+            throw new PanacheQueryException("There should be no more than one result");
+        }
+
+        return list.isEmpty() ? Optional.empty() : Optional.of(list.get(0));
+    }
 }

extensions/panache/panache-common/runtime/src/main/java/io/quarkus/panache/common/exception/PanacheQueryException.java

@@ -0,0 +1,7 @@
+package io.quarkus.panache.common.exception;
+
+public class PanacheQueryException extends RuntimeException {
+    public PanacheQueryException(String s) {
+        super(s);
+    }
+}