Add JSR-305 annotations to public APIs

(Partially) Resolves BATCH-2688

Author: fmbenhassine

spring-batch-core/src/main/java/org/springframework/batch/core/ItemProcessListener.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2007 the original author or authors.
+ * Copyright 2006-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@
 package org.springframework.batch.core;
 
 import org.springframework.batch.item.ItemProcessor;
+import org.springframework.lang.Nullable;
 
 /**
  * Listener interface for the processing of an item.  Implementations
@@ -24,6 +25,7 @@
  * exceptions thrown by the processor.
  * 
  * @author Dave Syer
+ * @author Mahmoud Ben Hassine
  *
  */
 public interface ItemProcessListener<T, S> extends StepListener {
@@ -37,13 +39,13 @@ public interface ItemProcessListener<T, S> extends StepListener {
 
 	/**
 	 * Called after {@link ItemProcessor#process(Object)} returns.  If the
-	 * processor returns null, this method will still be called, with
-	 * a null result, allowing for notification of 'filtered' items.
+	 * processor returns {@code null}, this method will still be called, with
+	 * a {code null} result, allowing for notification of 'filtered' items.
 	 * 
 	 * @param item to be processed
 	 * @param result of processing
 	 */
-	void afterProcess(T item, S result);
+	void afterProcess(T item, @Nullable S result);
 
 	/**
 	 * Called if an exception was thrown from {@link ItemProcessor#process(Object)}.

spring-batch-core/src/main/java/org/springframework/batch/core/ItemReadListener.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2008 the original author or authors.
+ * Copyright 2006-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,11 +17,13 @@
 
 import org.springframework.batch.item.ItemReader;
 import org.springframework.batch.item.ItemWriter;
+import org.springframework.lang.Nullable;
 
 /**
  * Listener interface around the reading of an item.
  * 
  * @author Lucas Ward
+ * @author Mahmoud Ben Hassine
  *
  */
 public interface ItemReadListener<T> extends StepListener {
@@ -36,7 +38,7 @@ public interface ItemReadListener<T> extends StepListener {
 	 * 
 	 * @param item returned from read()
 	 */
-	void afterRead(T item);
+	void afterRead(@Nullable T item);
 
 	/**
 	 * Called if an error occurs while trying to read.

spring-batch-core/src/main/java/org/springframework/batch/core/Job.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2007 the original author or authors.
+ * Copyright 2006-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,14 +15,16 @@
  */
 package org.springframework.batch.core;
 
+import org.springframework.lang.Nullable;
+
 /**
  * Batch domain object representing a job. Job is an explicit abstraction
  * representing the configuration of a job specified by a developer. It should
  * be noted that restart policy is applied to the job as a whole and not to a
  * step.
  * 
  * @author Dave Syer
- * 
+ * @author Mahmoud Ben Hassine
  */
 public interface Job {
 
@@ -47,11 +49,12 @@ public interface Job {
 
 	/**
 	 * If clients need to generate new parameters for the next execution in a
-	 * sequence they can use this incrementer. The return value may be null, in
-	 * the case that this job does not have a natural sequence.
+	 * sequence they can use this incrementer. The return value may be {@code null},
+	 * in the case that this job does not have a natural sequence.
 	 * 
 	 * @return in incrementer to be used for creating new parameters
 	 */
+	@Nullable
 	JobParametersIncrementer getJobParametersIncrementer();
 
 	/**
@@ -60,8 +63,8 @@ public interface Job {
 	 * the execution.
 	 * 
 	 * @return a validator that can be used to check parameter values (never
-	 * null)
+	 * {@code null})
 	 */
 	JobParametersValidator getJobParametersValidator();
 
-}
+}

spring-batch-core/src/main/java/org/springframework/batch/core/JobExecution.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2017 the original author or authors.
+ * Copyright 2006-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,12 +29,14 @@
 import java.util.concurrent.CopyOnWriteArrayList;
 
 import org.springframework.batch.item.ExecutionContext;
+import org.springframework.lang.Nullable;
 
 /**
  * Batch domain object representing the execution of a job.
  *
  * @author Lucas Ward
  * @author Michael Minella
+ * @author Mahmoud Ben Hassine
  *
  */
 @SuppressWarnings("serial")
@@ -91,7 +93,7 @@ public JobExecution(JobExecution original) {
 	 * @param jobConfigurationName {@link String} instance that represents the
 	 * job configuration name (used with JSR-352).
 	 */
-	public JobExecution(JobInstance job, Long id, JobParameters jobParameters, String jobConfigurationName) {
+	public JobExecution(JobInstance job, Long id, @Nullable JobParameters jobParameters, String jobConfigurationName) {
 		super(id);
 		this.jobInstance = job;
 		this.jobParameters = jobParameters == null ? new JobParameters() : jobParameters;

spring-batch-core/src/main/java/org/springframework/batch/core/JobKeyGenerator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2013 the original author or authors.
+ * Copyright 2013-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,11 +15,14 @@
  */
 package org.springframework.batch.core;
 
+import org.springframework.lang.Nullable;
+
 /**
  * Strategy interface for the generation of the key used in identifying
  * unique {@link JobInstance}.
  *
  * @author Michael Minella
+ * @author Mahmoud Ben Hassine
  *
  * @param <T> The type of the source data used to calculate the key.
  * @since 2.2
@@ -29,10 +32,10 @@ public interface JobKeyGenerator<T> {
 	/**
 	 * Method to generate the unique key used to identify a job instance.
 	 *
-	 * @param source Source information used to generate the key
+	 * @param source Source information used to generate the key (can be {@code null})
 	 *
 	 * @return a unique string identifying the job based on the information
 	 * supplied
 	 */
-	String generateKey(T source);
+	String generateKey(@Nullable T source);
 }

spring-batch-core/src/main/java/org/springframework/batch/core/JobParametersIncrementer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2007 the original author or authors.
+ * Copyright 2006-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,11 +15,14 @@
  */
 package org.springframework.batch.core;
 
+import org.springframework.lang.Nullable;
+
 /**
  * Interface for obtaining the next {@link JobParameters} in a sequence.
  * 
  * @author Dave Syer
  * @author Lucas Ward
+ * @author Mahmoud Ben Hassine
  * @since 2.0
  */
 public interface JobParametersIncrementer {
@@ -30,8 +33,8 @@ public interface JobParametersIncrementer {
 	 * instance of a job.
 	 * 
 	 * @param parameters the last value used
-	 * @return the next value to use
+	 * @return the next value to use (never {@code null})
 	 */
-	JobParameters getNext(JobParameters parameters);
+	JobParameters getNext(@Nullable JobParameters parameters);
 
 }

spring-batch-core/src/main/java/org/springframework/batch/core/JobParametersValidator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2010 the original author or authors.
+ * Copyright 2010-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,23 +15,25 @@
  */
 package org.springframework.batch.core;
 
+import org.springframework.lang.Nullable;
 
 /**
  * Strategy interface for a {@link Job} to use in validating its parameters for
  * an execution.
  * 
  * @author Dave Syer
- * 
+ * @author Mahmoud Ben Hassine
+ *
  */
 public interface JobParametersValidator {
 
 	/**
 	 * Check the parameters meet whatever requirements are appropriate, and
 	 * throw an exception if not.
 	 * 
-	 * @param parameters some {@link JobParameters}
+	 * @param parameters some {@link JobParameters} (can be {@code null})
 	 * @throws JobParametersInvalidException if the parameters are invalid
 	 */
-	void validate(JobParameters parameters) throws JobParametersInvalidException;
+	void validate(@Nullable JobParameters parameters) throws JobParametersInvalidException;
 
 }

spring-batch-core/src/main/java/org/springframework/batch/core/StepExecutionListener.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2013 the original author or authors.
+ * Copyright 2006-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,12 +15,14 @@
  */
 package org.springframework.batch.core;
 
+import org.springframework.lang.Nullable;
 
 /**
  * Listener interface for the lifecycle of a {@link Step}.
  *
  * @author Lucas Ward
  * @author Dave Syer
+ * @author Mahmoud Ben Hassine
  *
  */
 public interface StepExecutionListener extends StepListener {
@@ -44,7 +46,8 @@ public interface StepExecutionListener extends StepListener {
 	 *
 	 * @param stepExecution {@link StepExecution} instance.
 	 * @return an {@link ExitStatus} to combine with the normal value. Return
-	 * null to leave the old value unchanged.
+	 * {@code null} to leave the old value unchanged.
 	 */
+	@Nullable
 	ExitStatus afterStep(StepExecution stepExecution);
 }

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/JobLocator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2007 the original author or authors.
+ * Copyright 2006-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,12 +17,14 @@
 
 import org.springframework.batch.core.Job;
 import org.springframework.batch.core.launch.NoSuchJobException;
+import org.springframework.lang.Nullable;
 
 /**
  * A runtime service locator interface for retrieving job configurations by
  * <code>name</code>.
  * 
  * @author Dave Syer
+ * @author Mahmoud Ben Hassine
  * 
  */
 public interface JobLocator {
@@ -37,5 +39,5 @@ public interface JobLocator {
 	 * @throws NoSuchJobException if the required configuration can
 	 * not be found.
 	 */
-	Job getJob(String name) throws NoSuchJobException;
+	Job getJob(@Nullable String name) throws NoSuchJobException;
 }

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/package-info.java

@@ -2,5 +2,9 @@
  * Annotations and builder factories for java based configuration
  *
  * @author Michael Minella
+ * @author Mahmoud Ben Hassine
  */
-package org.springframework.batch.core.configuration.annotation;
+@NonNullApi
+package org.springframework.batch.core.configuration.annotation;
+
+import org.springframework.lang.NonNullApi;

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/package-info.java

@@ -2,5 +2,9 @@
  * Interfaces for registration and location of job configurations.
  *
  * @author Michael Minella
+ * @author Mahmoud Ben Hassine
  */
-package org.springframework.batch.core.configuration;
+@NonNullApi
+package org.springframework.batch.core.configuration;
+
+import org.springframework.lang.NonNullApi;

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/support/DefaultJobLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2013 the original author or authors.
+ * Copyright 2006-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -35,6 +35,7 @@
 import org.springframework.beans.factory.InitializingBean;
 import org.springframework.context.ApplicationContext;
 import org.springframework.context.ConfigurableApplicationContext;
+import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
@@ -45,6 +46,7 @@
  *
  * @author Dave Syer
  * @author Stephane Nicoll
+ * @author Mahmoud Ben Hassine
  */
 public class DefaultJobLoader implements JobLoader, InitializingBean {
 
@@ -77,9 +79,9 @@ public DefaultJobLoader(JobRegistry jobRegistry) {
 	 * Creates a job loader with the job and step registries provided.
 	 *
 	 * @param jobRegistry a {@link JobRegistry}
-	 * @param stepRegistry a {@link StepRegistry}
+	 * @param stepRegistry a {@link StepRegistry} (can be {@code null})
 	 */
-	public DefaultJobLoader(JobRegistry jobRegistry, StepRegistry stepRegistry) {
+	public DefaultJobLoader(JobRegistry jobRegistry, @Nullable StepRegistry stepRegistry) {
 		this.jobRegistry = jobRegistry;
 		this.stepRegistry = stepRegistry;
 	}