I think that these ideas are good ones. However, I wonder why we didn't do
anything about this before. In fact, in 2911, it is specifically called
out that we purposely didn't handle this situation (2911, section 3.2.6.1:
"There is no mechanism to allow for the next 'M' jobs after the first 'N'
jobs."). Does anyone remember whether there was a good reason this issue
was sidestepped?
I've made 3 specific comments inline below, marked with <dmc></dmc>.
Dennis Carney
IBM Printing Systems
"Hastings, Tom N"
<hastings at cp10.es To: sm at pwg.org
.xerox.com> cc: ps at pwg.org, ipp at pwg.org
Sent by: Subject: IPP> 2 more significant proposed increases in conformance requirements for the IPP
owner-ipp at pwg.org Document object spec
04/18/03 05:15 PM
In summarizing the significant conformance requirement increases that we
agreed to today in the review of the IPP Document Object spec review, I
forgot two more:
1. Add a REQUIRED way to the Get-Documents operation for the client to get
the Documents following the limit requested in a previous request.
So add the "start-after-document-number" (integer (0:MAX)) Operation
attribute.
2. Add a REQUIRED way to the Get-Jobs operation for the client to get the
Jobs following the limit requested in a previous request.
So add the "start-after-job-id" (integer (0:MAX)) Operation attribute.
Please send any comments on these additions by Friday, May 2, COB.
Here are the complete proposed text for these attributes and the updated
"limit" Operation attribute:
1.1 Get-Jobs ([rfc2911] section 3.2.6)
This REQUIRED Job operation returns requested attributes of either
completed
or not completed Jobs. The following (new) "start-after-job-id"
(integer(0:MAX)) Operation attribute is defined which in combination with
the "limit" operation attribute ([rfc2911] section 3.2.6) permits a client
to request selected ranges of jobs:
1.1.1 "limit" (integer(1:MAX)):
The client OPTIONALLY supplies this Operation
attribute.
The Printer MUST support this Operation attribute. It is an integer value
that determines the maximum number of Jobs that a client will receive from
the Printer even if "which-jobs" or "my-jobs" constrain which jobs are
returned. The limit is a "stateless limit" in that if the value supplied
by
the client is 'N', then only the first 'N' jobs are returned in the
Get-Jobs
Response. If the client does not supply the "limit" attribute, the Printer
responds with all applicable Jobs. However, if the client also supplies
the "start-after-job-id" Operation attribute (section 4.2.2) with a value
'M', the Printer returns the N Jobs starting with the Job following the one
with "job-id" = 'M'.
<dmc>
We need to say what happens if job-id M is no longer in the list. I think
the answer could be different for the two cases (non-completed vs.
completed), making this a bit more complicated.
If asking for *non-completed* jobs after job-id M, it is possible that M
has completed since the client made the last call and is therefore no
longer in the non-completed list. Unfortunately, this gets messy:
1) If M completed successfully, the printer should return the first N
non-completed jobs (i.e. the same as if M hadn't been specified at all).
2) If M was canceled/aborted, it seems like the printer should ideally
return the next job after M, *if* M hadn't been canceled/aborted. This
extra attempt at correctness is, I guess, not really necessary, since the
text below states that the caller can get strange results.
Otherwise, if asking for *completed* jobs after job-id M, it is possible
that M has been managed out of the completed list since the client made the
last call. In *this* case, since completed jobs are returned in the
opposite order of non-completed jobs, the printer should return an empty
list. That is, since completed jobs are returned from newest to oldest, if
M was managed out, jobs "after" (but actually printed before!) M are
presumably also managed out, so there are actually no jobs "after" M in the
completed list. This is the "correctly functioning" case of job-id M not
being in the list, but there is also the "error" case where job-id M is
just a bad value--it does seem strange to mandate that the printer return
an empty list and success whenever the caller sends a bad
"start-after-job-id" value.
Maybe we want some new status-code: something like
client-error-bad-start-id. Or we could possibly reuse client-error-gone or
client-error-not-possible or some other existing status-code. Then there
is just one answer for all the above cases: if M is not in the list, return
an error and let the client decide what to do.
</dmc>
1.1.2 "start-after-job-id" (integer(0:MAX)):
The client OPTIONALLY supplies this Operation
attribute.
The Printer MUST support this Operation attribute. If the client supplies
this attribute with a job-id value 'M', the Printer MUST return Jobs
starting with the Job that is after the one with "job-id" = 'M'. If the
client does not supply this attribute, the Printer assumes a '0' value
which
causes the Printer to return any Jobs with any "job-id" that meet the
requested criteria (specified by "which-jobs" and/or "my-jobs", etc.).
When
the client steps through the jobs N at a time, the client MUST set the
"start-after-job-id" attribute from the "job-id' of the last Job returned
in
a previous Get-Jobs response (rather than just adding 'N', since Printers
MAY assign job-ids out or order).
The client can detect when there are no more jobs
when the
Printer returns fewer jobs than requested by the "limit" Operation
attribute
('N'). In the case when the last number of jobs returned is exactly N
jobs,
the client will make an extra request and receive no jobs back (still with
a
'successful-ok' success code). However, this case still meets the criteria
for no more Jobs since the number of Jobs returned (0) is less than
"limit"..
Note when the client steps through the Jobs
supplying the
"limit" and "start-after-job-id" Operation attributes in successive
Get-Jobs
requests, there are some race conditions which the client implementer needs
to take into account:
* For 'non-completed' Jobs
(see [rfc2911]
section 3.2.6.2), the Printer MUST return the Jobs in the order of the
"expected time to complete" with the first expected to complete being
returned first, etc. Because some Printers MAY: (1) process jobs out of
order received, and/or (2) assign "job-id" in a non-monotonically
increasing
manner, occasionally a race condition MAY cause some jobs not be returned
and some jobs MAY be returned more than once. The only way for a client to
eliminate this race condition for 'not-completed' Jobs is to request all
Jobs by supplying neither the "limit" nor the "start-after-job-id"
Operation
attribute.
* For 'completed' jobs (see
[rfc2911] section
3.2.6.2), the Printer MUST return the jobs in the order of "newest to
oldest" to complete. Therefore, no jobs will be missed and/or doubly
returned.
1.2 Get-Documents Operation
This REQUIRED Job operation allows a client to retrieve the list of
Document
objects belonging to the target Job object. The client MAY also supply a
list of Document attribute names and/or attribute group names. A group of
Document object attributes will be returned for each Document object in the
Job.
This operation is similar to the Get-Document-Attributes operation (see
section 3.5), except that this Get-Documents operation returns attributes
from all Document objects contained in the Job object, instead of from a
single selected Document object in the Job object. As with the
Get-Document-Attributes operation the Printer MUST only return attributes
that were submitted by a client when the Document object was created by the
Create-Document, Send-Document, or Send-URI operations and possibly
modified
by the Set-Document-Attributes operation (see section 3.7).
1.2.1 Get-Documents Request
The client submits the Get-Documents request to a Printer. The
Get-Documents is similar to the Get-Jobs operations (see [rfc2911] section
3.2.6) except that there are no equivalents to the "which-jobs" and
"my-jobs" Operation attributes.
The following groups of attributes are part of the Get-Documents Request:
Group 1: Operation Attributes
Natural Language and Character Set:
The "attributes-charset" and
"attributes-natural-language"
attributes as described in [rfc2911] section 3.1.4.1.
Target:
Either (1) the "printer-uri" (uri) plus "job-id"
(integer(1:MAX)) or (2) the "job-uri" (uri) Operation attribute(s) which
define the target Job object for this operation as described in [rfc2911]
section 3.1.5.
Requesting User Name:
The "requesting-user-name" (name(MAX)) attribute
SHOULD be
supplied by the client as described in [rfc2911] section 8.3.
1.2.1.1 "limit" (integer(1:MAX)):
The client OPTIONALLY supplies this Operation
attribute.
The Printer MUST support this Operation attribute. It is an integer value
that determines the maximum number of Documents that a client will receive
from the Printer. If the client supplies the "limit" attribute with a
value
'N' and the "start-after-document-number" attribute with a value 'M', the
Printer returns the N Documents starting with the Document after the one
with "document-number" = 'M'. The limit is a "stateless limit" in that if
the value supplied by the client is 'N', then only the first 'N' Documents
are returned in the Get-Documents Response. If the client does not supply
the "limit" attribute, the Printer responds with all Documents in the Job.
However, if the client also supplies the "start-after-document-number"
Operation attribute (section 4.3.1.2) with a value 'M', the Printer returns
the N Documents starting with the Document following the one with
"document-number" = 'M'.
<dmc>
Editorial: The above paragraph would flow better without the fourth
sentence (the one starting "If the client supplies...").
</dmc>
1.2.1.2 "start-after-document-number"
(integer(0:MAX)):
The client OPTIONALLY supplies this Operation
attribute.
The Printer MUST support this Operation attribute. If the client supplies
this attribute with a document-number value 'M', the Printer MUST return
Documents starting with the Document that is after the one with
"document-number" = 'M'. If the client does not supply this attribute, the
Printer assumes a '0' value which causes the Printer to return Documents
starting with "document-number" = '1' (which is the first document in the
Job).
Note: canceled Documents (see section 3.7) are
still
returned, but deleted Documents (see section 3.8) are skipped over, since
they don't exist (leaving gaps in the "document-number" sequence).
<dmc>
Due to the fact that deleted Documents disappear, we have the same problem
as discussed above: Document number M might no longer exist. The expected
behavior for this should be similar to that decided upon for jobs, I would
think; however, for Document objects, the "ideal" behavior would be to
return the Documents starting with the first after Document M that hasn't
been deleted. Unfortunately, this "pretend like M is still there" strategy
doesn't really work as a general solution in the Get-Jobs case.
</dmc>
Please send any comments on these additions by Friday, May 2, COB.
Thanks,
Tom