Improved Null-checking annotations

ebean-api/src/main/java/io/ebean/BeanFinder.java

@@ -2,6 +2,7 @@
 
 import io.avaje.lang.NonNullApi;
 import io.avaje.lang.Nullable;
+
 import java.util.List;
 import java.util.Optional;
 
@@ -63,6 +64,7 @@ public Database db() {
   /**
    * Return the current transaction.
    */
+  @Nullable
   public Transaction currentTransaction() {
     return db().currentTransaction();
   }

ebean-api/src/main/java/io/ebean/DB.java

@@ -129,12 +129,13 @@ public static ExpressionFactory expressionFactory() {
    * Return the next identity value for a given bean type.
    * <p>
    * This will only work when a IdGenerator is on this bean type such as a DB
-   * sequence or UUID.
+   * sequence or UUID. Otherwise, <code>null</code> is returned.
    * <p>
    * For DB's supporting getGeneratedKeys and sequences such as Oracle10 you do
    * not need to use this method generally. It is made available for more
    * complex cases where it is useful to get an ID prior to some processing.
    */
+  @Nullable
   public static Object nextId(Class<?> beanType) {
     return getDefault().nextId(beanType);
   }
@@ -232,6 +233,7 @@ public static Transaction beginTransaction(TxScope scope) {
   /**
    * Returns the current transaction or null if there is no current transaction in scope.
    */
+  @Nullable
   public static Transaction currentTransaction() {
     return getDefault().currentTransaction();
   }
@@ -251,7 +253,7 @@ public static Transaction currentTransaction() {
    * </ul>
    */
   public static void flush() {
-    currentTransaction().flush();
+    getDefault().flush();
   }
 
   /**
@@ -313,7 +315,7 @@ public static void endTransaction() {
    * Mark the current transaction as rollback only.
    */
   public static void setRollbackOnly() {
-    getDefault().currentTransaction().setRollbackOnly();
+    Objects.requireNonNull(currentTransaction(),"no currentTransaction").setRollbackOnly();
   }
 
   /**
@@ -1085,7 +1087,9 @@ public static BeanState beanState(Object bean) {
 
   /**
    * Return the value of the Id property for a given bean.
+   * This can be null, if the bean has no id set or no id property at all.
    */
+  @Nullable
   public static Object beanId(Object bean) {
     return getDefault().beanId(bean);
   }

ebean-api/src/main/java/io/ebean/Database.java

@@ -35,7 +35,7 @@
  * <h5>The 'default' Database</h5>
  * <p>
  * One Database can be designated as the 'default' or 'primary' Database
- * (see {@link DatabaseConfig#setDefaultServer(boolean)}. Many methods on DB
+ * (see {@link DatabaseConfig#setDefaultServer(boolean)}). Many methods on DB
  * such as {@link DB#find(Class)} etc are actually just a convenient way to
  * call methods on the 'default/primary' Database.
  *
@@ -120,6 +120,7 @@ public interface Database {
   /**
    * Return the associated read only DataSource for this Database instance (can be null).
    */
+  @Nullable
   DataSource readOnlyDataSource();
 
   /**
@@ -166,13 +167,15 @@ public interface Database {
   /**
    * Return the BeanState for a given entity bean.
    * <p>
-   * This will return null if the bean is not an enhanced entity bean.
+   * This will throw an IllegalArgumentException if the bean is not an enhanced entity bean.
    */
   BeanState beanState(Object bean);
 
   /**
    * Return the value of the Id property for a given bean.
+   * This can be null, if the bean has no id set or no id property at all.
    */
+  @Nullable
   Object beanId(Object bean);
 
   /**
@@ -343,12 +346,13 @@ public interface Database {
    * Return the next unique identity value for a given bean type.
    * <p>
    * This will only work when a IdGenerator is on the bean such as for beans
-   * that use a DB sequence or UUID.
+   * that use a DB sequence or UUID. Otherwise, <code>null</code> is returned.
    * <p>
    * For DB's supporting getGeneratedKeys and sequences such as Oracle10 you do
    * not need to use this method generally. It is made available for more
    * complex cases where it is useful to get an ID prior to some processing.
    */
+  @Nullable
   Object nextId(Class<?> beanType);
 
   /**
@@ -636,6 +640,7 @@ public interface Database {
   /**
    * Returns the current transaction or null if there is no current transaction in scope.
    */
+  @Nullable
   Transaction currentTransaction();
 
   /**
@@ -866,7 +871,7 @@ public interface Database {
    * the bean does not exist then this returns false indicating that nothing was
    * deleted. However, if JDBC batch mode is used then this always returns true.
    */
-  boolean delete(Object bean, Transaction transaction) throws OptimisticLockException;
+  boolean delete(Object bean, @Nullable Transaction transaction) throws OptimisticLockException;
 
   /**
    * Delete a bean permanently without soft delete.
@@ -876,7 +881,7 @@ public interface Database {
   /**
    * Delete a bean permanently without soft delete using an explicit transaction.
    */
-  boolean deletePermanent(Object bean, Transaction transaction) throws OptimisticLockException;
+  boolean deletePermanent(Object bean, @Nullable Transaction transaction) throws OptimisticLockException;
 
   /**
    * Delete all the beans in the collection permanently without soft delete.
@@ -886,7 +891,7 @@ public interface Database {
   /**
    * Delete all the beans in the collection permanently without soft delete using an explicit transaction.
    */
-  int deleteAllPermanent(Collection<?> beans, Transaction transaction) throws OptimisticLockException;
+  int deleteAllPermanent(Collection<?> beans, @Nullable Transaction transaction) throws OptimisticLockException;
 
   /**
    * Delete the bean given its type and id.
@@ -896,7 +901,7 @@ public interface Database {
   /**
    * Delete the bean given its type and id with an explicit transaction.
    */
-  int delete(Class<?> beanType, Object id, Transaction transaction);
+  int delete(Class<?> beanType, Object id, @Nullable Transaction transaction);
 
   /**
    * Delete permanent given the bean type and id.
@@ -906,7 +911,7 @@ public interface Database {
   /**
    * Delete permanent given the bean type and id with an explicit transaction.
    */
-  int deletePermanent(Class<?> beanType, Object id, Transaction transaction);
+  int deletePermanent(Class<?> beanType, Object id, @Nullable Transaction transaction);
 
   /**
    * Delete all the beans in the collection.
@@ -916,7 +921,7 @@ public interface Database {
   /**
    * Delete all the beans in the collection using an explicit transaction.
    */
-  int deleteAll(Collection<?> beans, Transaction transaction) throws OptimisticLockException;
+  int deleteAll(Collection<?> beans, @Nullable Transaction transaction) throws OptimisticLockException;
 
   /**
    * Delete several beans given their type and id values.
@@ -926,7 +931,7 @@ public interface Database {
   /**
    * Delete several beans given their type and id values with an explicit transaction.
    */
-  int deleteAll(Class<?> beanType, Collection<?> ids, Transaction transaction);
+  int deleteAll(Class<?> beanType, Collection<?> ids, @Nullable Transaction transaction);
 
   /**
    * Delete permanent for several beans given their type and id values.
@@ -936,7 +941,7 @@ public interface Database {
   /**
    * Delete permanent for several beans given their type and id values with an explicit transaction.
    */
-  int deleteAllPermanent(Class<?> beanType, Collection<?> ids, Transaction transaction);
+  int deleteAllPermanent(Class<?> beanType, Collection<?> ids, @Nullable Transaction transaction);
 
   /**
    * Execute a Sql Update Delete or Insert statement. This returns the number of
@@ -987,7 +992,7 @@ public interface Database {
    * Execute a ORM insert update or delete statement with an explicit
    * transaction.
    */
-  int execute(Update<?> update, Transaction transaction);
+  int execute(Update<?> update, @Nullable Transaction transaction);
 
   /**
    * For making calls to stored procedures.
@@ -1048,17 +1053,17 @@ public interface Database {
    * @param transaction the transaction to use (can be null)
    */
   @Nullable
-  <T> T find(Class<T> beanType, Object id, Transaction transaction);
+  <T> T find(Class<T> beanType, Object id, @Nullable Transaction transaction);
 
   /**
    * Insert or update a bean with an explicit transaction.
    */
-  void save(Object bean, Transaction transaction) throws OptimisticLockException;
+  void save(Object bean, @Nullable Transaction transaction) throws OptimisticLockException;
 
   /**
    * Save all the beans in the collection with an explicit transaction.
    */
-  int saveAll(Collection<?> beans, Transaction transaction) throws OptimisticLockException;
+  int saveAll(Collection<?> beans, @Nullable Transaction transaction) throws OptimisticLockException;
 
   /**
    * This method checks the uniqueness of a bean. I.e. if the save will work. It will return the
@@ -1110,7 +1115,7 @@ public interface Database {
   /**
    * Same as {@link #checkUniqueness(Object)}. but with given transaction.
    */
-  Set<Property> checkUniqueness(Object bean, Transaction transaction, boolean useQueryCache, boolean skipClean);
+  Set<Property> checkUniqueness(Object bean, @Nullable Transaction transaction, boolean useQueryCache, boolean skipClean);
 
   /**
    * Marks the entity bean as dirty.
@@ -1159,7 +1164,7 @@ public interface Database {
   /**
    * Update a bean additionally specifying a transaction.
    */
-  void update(Object bean, Transaction transaction) throws OptimisticLockException;
+  void update(Object bean, @Nullable Transaction transaction) throws OptimisticLockException;
 
   /**
    * Update a collection of beans. If there is no current transaction one is created and used to
@@ -1170,7 +1175,7 @@ public interface Database {
   /**
    * Update a collection of beans with an explicit transaction.
    */
-  void updateAll(Collection<?> beans, Transaction transaction) throws OptimisticLockException;
+  void updateAll(Collection<?> beans, @Nullable Transaction transaction) throws OptimisticLockException;
 
   /**
    * Merge the bean using the default merge options (no paths specified, default delete).
@@ -1193,13 +1198,13 @@ public interface Database {
    * @param bean    The bean to merge
    * @param options The options to control the merge
    */
-  void merge(Object bean, MergeOptions options, Transaction transaction);
+  void merge(Object bean, MergeOptions options, @Nullable Transaction transaction);
 
   /**
    * Merges two beans (without saving them). All modified properties from <code>bean</code> are copied to <code>existing</code>.
    * Returns <code>existing</code> bean. If <code>null</code> is passed, a new instance of bean is retuned.
    */
-  <T> T mergeBeans(T bean, T existing, BeanMergeOptions options);
+  <T> T mergeBeans(T bean, T existing, @Nullable BeanMergeOptions options);
 
   /**
    * Insert the bean.
@@ -1213,7 +1218,7 @@ public interface Database {
   /**
    * Insert the bean with a transaction.
    */
-  void insert(Object bean, Transaction transaction);
+  void insert(Object bean, @Nullable Transaction transaction);
 
   /**
    * Insert a collection of beans. If there is no current transaction one is created and used to
@@ -1224,17 +1229,17 @@ public interface Database {
   /**
    * Insert a collection of beans with an explicit transaction.
    */
-  void insertAll(Collection<?> beans, Transaction transaction);
+  void insertAll(Collection<?> beans, @Nullable Transaction transaction);
 
   /**
    * Execute explicitly passing a transaction.
    */
-  int execute(SqlUpdate updSql, Transaction transaction);
+  int execute(SqlUpdate updSql, @Nullable Transaction transaction);
 
   /**
    * Execute explicitly passing a transaction.
    */
-  int execute(CallableSql callableSql, Transaction transaction);
+  int execute(CallableSql callableSql, @Nullable Transaction transaction);
 
   /**
    * Execute a Runnable in a Transaction with an explicit scope.
@@ -1396,7 +1401,7 @@ public interface Database {
    * @param transaction the transaction the publish process should use (can be null)
    */
   @Nullable
-  <T> T publish(Class<T> beanType, Object id, Transaction transaction);
+  <T> T publish(Class<T> beanType, Object id, @Nullable Transaction transaction);
 
   /**
    * Publish a single bean given its type and id returning the resulting live bean.
@@ -1420,7 +1425,7 @@ public interface Database {
    * @param query       the query used to select the draft beans to publish
    * @param transaction the transaction the publish process should use (can be null)
    */
-  <T> List<T> publish(Query<T> query, Transaction transaction);
+  <T> List<T> publish(Query<T> query, @Nullable Transaction transaction);
 
   /**
    * Publish the beans that match the query returning the resulting published beans.
@@ -1445,7 +1450,7 @@ public interface Database {
    * @param transaction the transaction the restore process should use (can be null)
    */
   @Nullable
-  <T> T draftRestore(Class<T> beanType, Object id, Transaction transaction);
+  <T> T draftRestore(Class<T> beanType, Object id, @Nullable Transaction transaction);
 
   /**
    * Restore the draft bean back to the live state.
@@ -1470,7 +1475,7 @@ public interface Database {
    * @param query       the query used to select the draft beans to restore
    * @param transaction the transaction the restore process should use (can be null)
    */
-  <T> List<T> draftRestore(Query<T> query, Transaction transaction);
+  <T> List<T> draftRestore(Query<T> query, @Nullable Transaction transaction);
 
   /**
    * Restore the draft beans matching the query back to the live state.

ebean-api/src/main/java/io/ebean/ExpressionList.java

@@ -242,7 +242,7 @@ public interface ExpressionList<T> {
    *
    * @return the number of rows that were deleted.
    */
-  int delete(Transaction transaction);
+  int delete(@Nullable Transaction transaction);
 
   /**
    * Execute as a update query.
@@ -258,7 +258,7 @@ public interface ExpressionList<T> {
    * @return the number of rows that were updated.
    * @see UpdateQuery
    */
-  int update(Transaction transaction);
+  int update(@Nullable Transaction transaction);
 
   /**
    * Execute the query returning true if a row is found.
@@ -404,6 +404,7 @@ public interface ExpressionList<T> {
    *
    * }</pre>
    */
+  @Nullable
   default <A> A findSingleAttribute() {
     List<A> list = findSingleAttributeList();
     return !list.isEmpty() ? list.get(0) : null;