javadoc updates for Tasklet and JobInstance

spring-batch-core/src/main/java/org/springframework/batch/core/domain/JobInstance.java

@@ -18,38 +18,48 @@ package org.springframework.batch.core.domain;
 
 import org.springframework.util.Assert;
 
-
-
 /**
- * Batch domain object representing a job instance. A job instance is defined as
- * a logical container for steps with unique identification of the unit as a
- * whole. A job can be executed many times with the same instance, usually if it
- * fails and is restarted, or if it is launched on an ad-hoc basis "on demand".
+ * Batch domain object representing a uniquely identifiable job run - it's
+ * identity is given by the pair {@link Job} and {@link JobParameters}.
+ * JobInstance can be restarted multiple times in case of execution failure and
+ * it's lifecycle ends with first successful execution.
+ * 
+ * Trying to execute an existing JobIntance that has already completed
+ * successfully will result in error. Error will be raised also for an attempt
+ * to restart a failed JobInstance if the Job ({@link JobInstance#getJob()}) is not
+ * restartable.
+ * 
+ * @see Job
+ * @see JobParameters
+ * @see JobExecution
  * 
  * @author Lucas Ward
  * @author Dave Syer
+ * @author Robert Kasanicky
+ * 
  */
 public class JobInstance extends Entity {
 
 	private JobParameters jobParameters;
-	
+
 	private Job job;
 
 	private int jobExecutionCount;
-	
+
 	private JobExecution lastExecution;
 
-	public JobInstance(Long id, JobParameters jobParameters, Job job){
+	public JobInstance(Long id, JobParameters jobParameters, Job job) {
 		super(id);
 		Assert.notNull(job);
-		this.jobParameters = jobParameters==null ? new JobParameters() : jobParameters;
+		this.jobParameters = jobParameters == null ? new JobParameters()
+				: jobParameters;
 		this.job = job;
 	}
-	
+
 	public void setLastExecution(JobExecution lastExecution) {
 		this.lastExecution = lastExecution;
 	}
-	
+
 	public JobExecution getLastExecution() {
 		return lastExecution;
 	}
@@ -73,20 +83,20 @@ public class JobInstance extends Entity {
 	 * @return the job name. (Equivalent to getJob().getName())
 	 */
 	public String getJobName() {
-		return job==null ? null : job.getName();
+		return job == null ? null : job.getName();
 	}
-	
+
 	public JobExecution createJobExecution() {
 		JobExecution newExecution = new JobExecution(this);
 		this.setLastExecution(newExecution);
 		return newExecution;
 	}
-	
+
 	public String toString() {
-		return super.toString()+", JobParameters=["+ jobParameters +"]" +
-			", Job=[" + job + "]";
+		return super.toString() + ", JobParameters=[" + jobParameters + "]"
+				+ ", Job=[" + job + "]";
 	}
-	
+
 	public Job getJob() {
 		return job;
 	}

spring-batch-core/src/main/java/org/springframework/batch/core/tasklet/Tasklet.java

@@ -16,39 +16,41 @@
 
 package org.springframework.batch.core.tasklet;
 
-import org.springframework.batch.core.domain.Step;
+import org.springframework.batch.core.domain.StepExecution;
+import org.springframework.batch.core.domain.StepListener;
+import org.springframework.batch.item.ItemReader;
+import org.springframework.batch.item.ItemWriter;
 import org.springframework.batch.repeat.ExitStatus;
 
+import com.sun.org.apache.xerces.internal.impl.xpath.XPath.Step;
+
 /**
- * The primary interface describing the touch-point between the batch developer
- * and a spring-batch execution. The execute method will be called to indicate
- * to the developer that it is time to execute business logic. The value
- * returned from this method will indicate whether or not processing should
- * continue. It is important to note that in the vast majority of cases this
- * class should not be directly implemented by batch developers for processing.
- * Most batch processing is significantly more complex than simple execute and
- * should logically be broken into a minimum of two processes (read and write).
- * However, many architecture teams may find creating their own implementations
- * of this interface useful for differentiating different batch job types, or
- * for creating more flexibility within their batch jobs.
+ * Interface for encapsulating processing logic that is not natural to split
+ * into read-(transform)-write phases, such as invoking a system command or a
+ * stored procedure.
+ * 
+ * As framework has no visibility inside the {@link #execute()} method,
+ * developers should consider implementing {@link StepListener} and check the
+ * {@link StepExecution#isTerminateOnly()} value for long lasting processes to
+ * enable prompt termination of processing on user request.
+ * 
+ * It is expected the read-(transform)-write separation will be appropriate for
+ * most cases and developers should implement {@link ItemReader} and
+ * {@link ItemWriter} interfaces then (typically extending or composing provided
+ * implementations).
  * 
- * @see Step
  * @author Lucas Ward
  * @author Dave Syer
+ * @author Robert Kasanicky
  * 
  */
 public interface Tasklet {
 
 	/**
-	 * Primary batch processing driver. All processing of batch business data
-	 * should be handled within this method. Any processing which intends to
-	 * control the flow of the batch lifecycle by throwing exceptions (such as
-	 * BatchCriticalExeception) should throw them within this method. Doing so
-	 * outside of this method will prevent the architecture from gracefully
-	 * shutting down and providing such features as transaction rollback.
+	 * Encapsulates execution logic of {@link Step}, which is unnatural to
+	 * separate into read-(transform)-write phases.
 	 * 
-	 * @return ExitStatus indicating whether the processing should continue (i.e.
-	 * false when data are exhausted).
+	 * @return ExitStatus indicating success or failure
 	 * @see org.springframework.batch.repeat.ExitStatus
 	 */
 	public ExitStatus execute() throws Exception;