Bug 5375 - Spec contradicts itself when talking about uninitialized exit status (TCK assumes 'null')
Spec contradicts itself when talking about uninitialized exit status (TCK ass...
Status: NEW
Product: jbatch
Classification: Unclassified
Component: SPEC
1
All All
: P5 normal
: ---
Assigned To: ScottKurz
1.0_mr_pending
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2013-09-09 21:30 UTC by ScottKurz
Modified: 2014-03-24 14:09 UTC (History)
2 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description ScottKurz 2013-09-09 21:30:38 UTC
As noted in ML discussion: "ExecuteTests#testMyStepContextBatchlet question", the TCK assumes that a JobContext.getExitStatus() will return 'null' if setExitStatus() has not been called. 

As mentioned in the email thread, maybe it should be returning the BatchStatus, e.g. STARTED.

TCK: Assuming no spec change, this affects a large number of TCK tests though it might be possible to abstract away the difference in the TCK.
Comment 1 mminella 2013-09-16 16:47:34 UTC
Just to point out, the place that the spec states the ExitStatus matches the BatchStatus by default is page 47 in section 8.7:

"
The batch and exit status of the job is set as follows:
    1. Batch status is initially set to STARTING by the batch runtime. Immediately before starting the first step, the batch runtime sets the batch status to STARTED. Exit status is initially set to the string form of the batch status.
"
Comment 2 ScottKurz 2013-11-07 05:32:40 UTC
I'm thinking about just leaving this alone, rather than updating the TCK.

Within the Javadoc itself (for JobContext and StepContext), the behavior of getExitStatus() is clearly specified in the manner that the TCK expects.  I.e. if setExitStatus() hasn't been called, then a 'null' is returned.

It could be confusing, I agree, to reconcile this with the wording in 8.7 and 8.7.1:  "Exit status is initially set to the string form of the batch status".

However this could be clarified by saying that the exit status in this context, is the exit status seen via the JobExecution/StepExecution (by the JobOperator).

It is not necessarily obvious that the exit status described in 8.7, 8.7.1 MUST at all times have the same value as that returned by the getExitStatus() methods.  Without the Javadoc description, it would be a reasonable and obvious assumption, but we have the description here.

Let's step back and think about how this API would actually be used.

What value is there in a batch artifact getting a runtime-provided value on StepContext.getExitStatus()?   If the artifact has control, then the BatchStatus must be either STARTED or STOPPING.  Maybe one could do something different depending on which of the two but the same could be accomplished via getBatchStatus().

To me it seems the only value is to see a value that some other artifact in the job/step has set into setExitStatus().  This can be accomplished just as well with a 'null' initial value as it can with a value reflecting the current BatchStatus.

Does this really seem worth updating the TCK or excluding tests for?
Comment 3 mminella 2013-11-14 20:03:27 UTC
I'm confused about the javadoc you're referring to in the StepContext and JobContext.  On page 94 of the spec, the javadoc for StepContext#setExitStatus(String status) states:

"If setExitStatus was not called or was called with a null value, then the exit status defaults to the batch status of the step."

This is clearly in line with section 8.7 as I pointed out that states that the status is initially set to the BatchStatus.  The corresponding getter (StepContext#getExitStatus() just implies that null is a possible value, not that it is the default return value if the setExitStatus was not called.  In fact, I would argue that the setter verbiage goes even further since it says that if it is called with a null value (aka myStepContext.setExitStatus(null);) it should still be set to the BatchStatus.

The same language is used in the javadoc on the JobContext.
Comment 4 ScottKurz 2013-11-18 21:28:15 UTC
(In reply to mminella from comment #3)
> I'm confused about the javadoc you're referring to in the StepContext and
> JobContext.  On page 94 of the spec, the javadoc for
> StepContext#setExitStatus(String status) states:
> 
> "If setExitStatus was not called or was called with a null value, then the
> exit status defaults to the batch status of the step."

The full paragraph is:

* The setExitStatus method assigns the user-specified exit status for
* the current step. When the step ends, the exit status of the step is
* the value specified through setExitStatus. If setExitStatus was not
* called or was called with a null value, then the exit status
* defaults to the batch status of the step.

So the last sentence (mentioning the defaulting) follows the sentence:  "When the step ends...".   If you read it this way, that the default is applied once the step ends, then it's consistent with my interpretation.  

---

But in any case, I think we've reached the end of the road trying to find clarity looking back over the existing spec wording.  We are interpreting this differently and built the RI and TCK with a different, though I think reasonable, interpretation.  I think it would help then to update the spec, through an errata, to clarify the behavior here.

So I'm proposing, again, clarifying the spec that the defaulting of exit status to batch status doesn't occur until after the job/step execution finishes (loosely speaking... maybe I'm glossing over a detail or two but not one that's come up in this discussion).

This would then leave the TCK unchanged.
Comment 5 mminella 2013-11-18 21:40:58 UTC
I still disagree, even with the sentence I pointed out in it's full context.  What you are describing is that the default is applied at the end.  That doesn't make it the default…that makes it the end result.  I view this as nothing more than a minor error in the javadoc on the getExitStatus.  Everywhere else in the spec is consistent in that the default value for the ExitStatus should be the BatchStatus.  The only way that the status could be null in any scenario is if you assume that null is the "default" during the execution of the step when setExitStatus has not been called.  From a developer's standpoint, that seems like a very unintuitive interpretation.  From the developer's perspective, I now have two "defaults".  One while the step is executing (null) and one once it ends (the BatchStatus).
Comment 6 ScottKurz 2013-11-18 21:51:14 UTC
(In reply to mminella from comment #5)
>  The only way that the status could be
> null in any scenario is if you assume that null is the "default" during the
> execution of the step when setExitStatus has not been called.  From a
> developer's standpoint, that seems like a very unintuitive interpretation. 
> From the developer's perspective, I now have two "defaults".  One while the
> step is executing (null) and one once it ends (the BatchStatus).

Yes, that's exactly what I'm proposing.  I don't think it's that complicated, but it does deserve some explanation.   

Basically, while the step artifacts are executing, 'exitStatus' is just a bean property of JobContext/StepContext.   The more detailed behavior described in 8.7 applies only once the step/job is no longer executing, at which time exit status becomes a property of JobExecution/StepExecution and is also (for step exit status) relevant for transitioning between execution elements.
Comment 7 mminella 2013-11-18 21:58:18 UTC
You're saying that the StepExeuction's ExitStatus and the StepContexts's ExitsStatus wouldn't be consistent?  Now we have two ExitStatuses for the same step at the same time, one in the StepContext and one in the StepExecution.  Is that correct?
Comment 8 mminella 2013-11-19 14:43:27 UTC
One other note.  Although we keep talking about this in the scope of the Step (StepContext and StepExecution), I believe the JobContext and JobExecution have the same semantics.  Because of that, we should consider how that defaulting behavior applies at the job level as well.
Comment 9 ScottKurz 2013-11-19 14:53:22 UTC
(In reply to mminella from comment
Comment 10 ScottKurz 2013-11-19 15:01:24 UTC
(In reply to mminella from comment #7)

When a job/step begins executing, the exitStatus is initialized to null.

When execution completes, the exitStatus, if not currently set to a non-null value, defaults to batch status.

So there's only one exit status "at a time", but the rules in play are different depending on whether we're executing or not.   

This fits well with the idea that this "exit status" has a different significance once execution is over (e.g. it then is potentially used to transition between steps).
----

Let me back up and point out that I'm more resistant to change only because the TCK is already out there.   Changing the behavior at this point means the change must be picked up by all implementations.   It's not that I'm claiming my interpretation is clearly superior.

My references to the spec have been to show that there is something in there to back our view of this behavior, that we're not blatantly contradicting the spec yet marching forwards only because of the TCK implementation.   I think the spec is unclear.... not in complete contradiction with the TCK.

Your proposal is a bit simpler than mine... but I don't think it offers any more utility.   

So I'm still planning on leaving the TCK alone, and adding a clarification as a spec errata in our next maintenance release.

Also in reply to comment #8, I am considering both job/step in this response.
Comment 11 ScottKurz 2014-01-08 22:46:24 UTC
OK, this is a decent-sized change since there are assertions scattered throughout.

The bottom line will be that the job/step exit status is initialized to 'null', and is only defaulted to batch status when job/step execution ends. 

Again, I don't claim this is superior to the other interpretation, (that the exit status defaults to batch status at any point).  But we had an ambiguity and the TCK took this approach, so I'm going with that and hoping that this won't be too great a burden on migration of legacy SB apps.

------------------
Six changes here:
------------------

1) (This is only tangentially related, but it seemed close enough and small enough to lump together rather than using another bug:)

At the end of the main paragraph of Section 8.5 (Decision), change last sentence from:

  The decider may set a new exit status to facilitate the transition choice.

to: 

  The decider return value will also be set as the current value of the job exit status, in addition to being matched against the decision’s own child transition elements to decide the next transition.

---

2) Sec. 8.7 (2nd paragraph):

Change from:

  A job and each step in a job end with a batch status and exit status value. Batch status is set by the batch runtime; exit status may be set through the Job XML or by the batch application. By default, the exit status is the same as the batch status. Note if a batch artifact explicitly sets the exit status that overrides the default. The batch and exit status values are available in the JobContext and StepContext runtime objects.....

to:

  A job and each step in a job end with a batch status and exit status value. Batch status is set by the batch runtime; exit status may be set through the Job XML or by the batch application.  The exit status for a job and a step will be initially set to ‘null’.   At the time that the job or step completes execution, if the exit status is equal to ‘null’, it will then be defaulted to the string value of the batch status, which will be its final value.   The batch and exit status values are available in the JobContext and StepContext runtime objects, and the exit status can be set explicitly via any batch artifact.....

---

3) Also Sec. 8.7 

Change from (i.e. delete the last line shown in the current text):

 The batch and exit status of the job is set as follows:

 1.  Batch status is initially set to STARTING by the batch runtime. Immediately before starting the first step, the batch runtime sets the batch status to STARTED. Exit status is initially set to the string form of the batch status.

To:
 
  The batch and exit status of the job is set as follows:

 1.  Batch status is initially set to STARTING by the batch runtime.  Immediately before starting the first step, the batch runtime sets the batch status to STARTED.  

---

4) Sec. 8.7.1

Remove sentence:

 "Step exit status is initially set to the same value as batch status."

---

5) Sec. 8.7.1

Change last sentence to:

  "If no batch artifact sets the exit status, the batch runtime will default the value to the string form of the batch status value of the step when step execution completes."

---

6) Sec. 8.7.2.

Change last sentence in first paragraph to:

  "If the exit status is not set it defaults to batch status at the end of step execution, the same as for a non-partitioned step."
Comment 12 ScottKurz 2014-03-24 14:09:37 UTC
Change #7 (from M. Minella comment): 

Rework change #2 above (in this same bug) to rephrase "defaulted".  The sentence in question now reads:

"At the time that the job or step completes execution, if the exit status is equal to ‘null’, it will then be set by the runtime implementation to the string value of the batch status, which will be its final value."