This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch feature/null-annotations-jobmanager in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-event-api.git
commit 4fae36395d6b0b49d0ff2008261d0014d596565d Author: Konrad Windszus <[email protected]> AuthorDate: Sat Apr 5 18:02:38 2025 +0200 SLING-12740 Add null annotations to JobManager Clarify some javadocs --- .../org/apache/sling/event/jobs/JobManager.java | 36 ++++++++++++---------- .../org/apache/sling/event/jobs/package-info.java | 2 +- 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/src/main/java/org/apache/sling/event/jobs/JobManager.java b/src/main/java/org/apache/sling/event/jobs/JobManager.java index 105b611..de1532f 100644 --- a/src/main/java/org/apache/sling/event/jobs/JobManager.java +++ b/src/main/java/org/apache/sling/event/jobs/JobManager.java @@ -21,6 +21,8 @@ package org.apache.sling.event.jobs; import java.util.Collection; import java.util.Map; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; import org.osgi.annotation.versioning.ProviderType; @@ -45,26 +47,26 @@ public interface JobManager { * Return statistics information about all queues. * @return The statistics. */ - Statistics getStatistics(); + @NotNull Statistics getStatistics(); /** * Return statistics information about job topics. * @return The statistics for all topics. */ - Iterable<TopicStatistics> getTopicStatistics(); + @NotNull Iterable<TopicStatistics> getTopicStatistics(); /** * Return a queue with a specific name (if running) * @param name The queue name * @return The queue or <code>null</code> */ - Queue getQueue(String name); + @Nullable Queue getQueue(@NotNull String name); /** * Return an iterator for all available queues. * @return An iterator for all queues. */ - Iterable<Queue> getQueues(); + @NotNull Iterable<Queue> getQueues(); /** * The requested job types for the query. @@ -99,11 +101,11 @@ public interface JobManager { * as well. * * @param topic The required job topic. - * @param properties Optional job properties. The properties must be serializable. + * @param properties Optional job properties. The properties must be serializable. May be <code>null</code>. * @return The new job - or <code>null</code> if the job could not be created. * @since 1.2 */ - Job addJob(String topic, Map<String, Object> properties); + @Nullable Job addJob(@NotNull String topic, Map<String, Object> properties); /** * Return a job based on the unique id. @@ -115,7 +117,7 @@ public interface JobManager { * @return A job or <code>null</code> * @since 1.2 */ - Job getJobById(String jobId); + @Nullable Job getJobById(@NotNull String jobId); /** * Removes the job even if it is currently in processing. @@ -129,7 +131,7 @@ public interface JobManager { * <code>false</code> otherwise. * @since 1.2 */ - boolean removeJobById(String jobId); + boolean removeJobById(@NotNull String jobId); /** * Find a job - either queued or active. @@ -142,11 +144,11 @@ public interface JobManager { * * @param topic Topic is required. * @param template The map acts like a template. The searched job - * must match the template (AND query). + * must match the template (AND query). May be <code>null</code>. * @return A job or <code>null</code> * @since 1.2 */ - Job getJob(String topic, Map<String, Object> template); + @Nullable Job getJob(@NotNull String topic, Map<String, Object> template); /** * Return all jobs of a given type. @@ -161,7 +163,7 @@ public interface JobManager { * The returned job objects are a snapshot of the jobs state taken at the time of the call. Updates * to the job states are not reflected and the client needs to get new job objects. * - * @param type Required parameter for the type. See above. + * @param type Required parameter for the type. See above. * @param topic Topic can be used as a filter, if it is non-null, only jobs with this topic will be returned. * @param limit A positive number indicating the maximum number of jobs returned by the iterator. A value * of zero or less indicates that all jobs should be returned. @@ -171,7 +173,7 @@ public interface JobManager { * @return A collection of jobs - the collection might be empty. * @since 1.2 */ - Collection<Job> findJobs(QueryType type, String topic, long limit, Map<String, Object>... templates); + @NotNull Collection<Job> findJobs(@NotNull QueryType type, String topic, long limit, Map<String, Object>... templates); /** * Stop a job. @@ -181,7 +183,7 @@ public interface JobManager { * @param jobId The job id * @since 1.3 */ - void stopJobById(String jobId); + void stopJobById(@NotNull String jobId); /** * Retry a cancelled job. @@ -191,7 +193,7 @@ public interface JobManager { * @param jobId The job id. * @return If the job is requeued, the new job object otherwise <code>null</code> */ - Job retryJobById(String jobId); + Job retryJobById(@NotNull String jobId); /** * Fluent API to create, start and schedule new jobs @@ -199,14 +201,14 @@ public interface JobManager { * @return A job builder * @since 1.3 */ - JobBuilder createJob(final String topic); + @NotNull JobBuilder createJob(@NotNull final String topic); /** * Return all available job schedules. * @return A collection of scheduled job infos * @since 1.3 */ - Collection<ScheduledJobInfo> getScheduledJobs(); + @NotNull Collection<ScheduledJobInfo> getScheduledJobs(); /** * Return all matching available job schedules. @@ -219,5 +221,5 @@ public interface JobManager { * @return All matching scheduled job infos. * @since 1.4 */ - Collection<ScheduledJobInfo> getScheduledJobs(String topic, long limit, Map<String, Object>... templates); + @NotNull Collection<ScheduledJobInfo> getScheduledJobs(String topic, long limit, Map<String, Object>... templates); } diff --git a/src/main/java/org/apache/sling/event/jobs/package-info.java b/src/main/java/org/apache/sling/event/jobs/package-info.java index 6ea3e5c..1f371b0 100644 --- a/src/main/java/org/apache/sling/event/jobs/package-info.java +++ b/src/main/java/org/apache/sling/event/jobs/package-info.java @@ -17,7 +17,7 @@ * under the License. */ [email protected]("2.0.1") [email protected]("2.0.2") package org.apache.sling.event.jobs;
