CAMEL-22640: Add JSpecify null safety annotations to camel-api

core/camel-api/pom.xml

@@ -39,6 +39,11 @@
 
     <dependencies>
 
+        <dependency>
+            <groupId>org.jspecify</groupId>
+            <artifactId>jspecify</artifactId>
+        </dependency>
+
         <dependency>
             <groupId>org.apache.camel</groupId>
             <artifactId>camel-util</artifactId>

core/camel-api/src/main/java/org/apache/camel/AggregationStrategy.java

@@ -16,6 +16,7 @@
  */
 package org.apache.camel;
 
+import org.jspecify.annotations.Nullable;
 import org.slf4j.LoggerFactory;
 
 /**
@@ -64,7 +65,8 @@ public interface AggregationStrategy {
      * @return             a combined composite of the two exchanges, return either the old or new exchange from the
      *                     input parameters; favor returning the old exchange whenever possible)
      */
-    Exchange aggregate(Exchange oldExchange, Exchange newExchange);
+    @Nullable
+    Exchange aggregate(@Nullable Exchange oldExchange, @Nullable Exchange newExchange);
 
     /**
      * Aggregates an old and new exchange together to create a single combined exchange.
@@ -82,7 +84,8 @@ public interface AggregationStrategy {
      * @return               a combined composite of the two exchanges, return either the old or new exchange from the
      *                       input parameters; favor returning the old exchange whenever possible)
      */
-    default Exchange aggregate(Exchange oldExchange, Exchange newExchange, Exchange inputExchange) {
+    default @Nullable Exchange aggregate(
+            @Nullable Exchange oldExchange, @Nullable Exchange newExchange, Exchange inputExchange) {
         return aggregate(oldExchange, newExchange);
     }
 
@@ -105,7 +108,7 @@ default boolean canPreComplete() {
      * @return             <tt>true</tt> to complete current group and start a new group, or <tt>false</tt> to keep
      *                     using current
      */
-    default boolean preComplete(Exchange oldExchange, Exchange newExchange) {
+    default boolean preComplete(@Nullable Exchange oldExchange, @Nullable Exchange newExchange) {
         return false;
     }
 

core/camel-api/src/main/java/org/apache/camel/BinaryPredicate.java

@@ -16,6 +16,8 @@
  */
 package org.apache.camel;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * A predicate which evaluates a binary expression.
  * <p/>
@@ -55,6 +57,7 @@ public interface BinaryPredicate extends Predicate {
      * @param  exchange the message exchange
      * @return          <tt>null</tt> if the predicate matches.
      */
+    @Nullable
     String matchesReturningFailureMessage(Exchange exchange);
 
 }

core/camel-api/src/main/java/org/apache/camel/CamelAuthorizationException.java

@@ -16,13 +16,15 @@
  */
 package org.apache.camel;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * An exception thrown for either authentication or authorization errors occurring in a Camel exchange. Intended to be
  * used when a user is denied an action and Camel should not process the message as a result.
  */
 public class CamelAuthorizationException extends CamelExchangeException {
 
-    private final String policyId;
+    private final @Nullable String policyId;
 
     public CamelAuthorizationException(String message, Exchange exchange) {
         super(message, exchange);
@@ -34,7 +36,7 @@ public CamelAuthorizationException(String message, Exchange exchange, Throwable
         policyId = exchange.getIn().getHeader(Exchange.AUTHENTICATION_FAILURE_POLICY_ID, String.class);
     }
 
-    public String getPolicyId() {
+    public @Nullable String getPolicyId() {
         return policyId;
     }