Bug 5583 - CheckpointAlgorithm needs to specify timeunit (seconds) and other javadoc fixes
CheckpointAlgorithm needs to specify timeunit (seconds) and other javadoc fixes
Status: NEW
Product: jbatch
Classification: Unclassified
Component: SPEC
1
All All
: P5 major
: ---
Assigned To: ScottKurz
1.0_mr_pending
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2013-11-20 15:36 UTC by cf126330
Modified: 2014-01-09 23:11 UTC (History)
1 user (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description cf126330 2013-11-20 15:36:42 UTC
CheckpointAlgorithm method
int checkpointTimeout() throws Exception

does not specify the timeunit (seconds) for the return value in the current javadoc: 

http://docs.oracle.com/javaee/7/api/javax/batch/api/chunk/CheckpointAlgorithm.html

Its javadoc contains a @param, but this method has no param.
Comment 1 ScottKurz 2014-01-03 20:13:35 UTC
Just looking at this again.  I ran Checkstyle against the API package, and got 157 warnings.   A good chunk of these reflect the fact that we didn't comment each of the exception constructors, which I don't think is a big deal.But I'm going to have to spend some time sorting through this.
Comment 2 ScottKurz 2014-01-09 23:11:00 UTC
Fixed this one method with this Javadoc text:

	/**
	 * The checkpointTimeout is invoked at the beginning of a new 
	 * checkpoint interval for the purpose of establishing the checkpoint 
	 * timeout. 
	 * It is invoked before the next checkpoint transaction begins. This 
         * method returns an integer value, which is the timeout value (expressed
         * in seconds) which will be used for the next checkpoint transaction.  
         * This method is useful to automate the setting of the 
	 * checkpoint timeout based on factors known outside the job 	
	 * definition. 
	 * 
	 * @return the timeout interval (time unit = seconds) to use for the 
         * next checkpoint interval 
	 * @throws Exception thrown for any errors.
	 */
	public int checkpointTimeout() throws Exception;

Made some other changes..  I don't think it's too interesting to list them all.  A couple were bugs but most were additions of things that had been omitted up until now.

One I caught was:  in the spec we have a method described as StepExecution#getUserPersistentData but in the RI and TCK it's been changed to StepExecution#getPersistentUserData.  So I updated the spec accordingly (I may have mentioned this in another bug).

Note the spec contains a lot of the Javadoc but not 100% of the RI's API Javadoc, so not every update will go into the spec.   Will try to refresh the spec with the latest Javadoc but this is a bit of a manual merge and my master copy is the RI.   

In other words, help keep me honest here if you see additional bugs in Javadoc.