Peter has relayed some discussion in the Semantic Model WG meeting in New
Orleans about which Document object operations are REQUIRED and which are
OPTIONAL for a Printer to support. Some folks suggested (considering the
low end Printer):
A. Change Create-Document and Send-Data operations from REQUIRED to OPTIONAL
for a Printer to support.
B. Don't even define "document-number" operation attribute for
Create-Document, Send-Document, and Send-URI. Then there can't be holes in
the document numbers. Make the client create the documents in the order
wanted in the output, so that the Printer will number them as the client
wants. (Also need to deprecate the "document-number" operation attribute
for use with the Send-Document and Send-URI operations in the PWG Document
Overrides specification).
Here is a rather long note that proposes to:
1. eliminate the REQUIRED Validate-Document operation altogether.
2. but keep Create-Document and Send-Data REQUIRED (see reasoning below).
3. Remove the "document-number" operation attribute because it isn't needed
if Create-Document is available (see reasoning below).
4. Also consider changing the REQUIRED Send-Document operation back to
OPTIONAL to agree with RFC 2911.
5. Consider deleting the Cancel-Current-Document, since its pretty funky if
"copies" is > 1.
Goals and Requirements for the Document object spec:
Goal 1. In order to improve interoperability, we need to eliminate
operations and operation attributes that are OPTIONAL for a Printer to
support. In fact, if an operation or operation attribute is OPTIONAL for a
Printer to support, it is highly unlikely that clients will bother to
support the feature. Also we want to define as small a number of different
ways to submit a multi-document job as possible, as long as they cover the
important use cases.
Goal 2: The Document object should be supportable by a non-spooling low end
printer as well as a higher end spooling printer.
The non-spooling low end printer can't support making copies (except for
really short documents), except for "sheet-collate" = 'uncollated'. Such a
Printer starts to mark document data as it is received. So such a Printer
cannot support "multiple-document-handling" =
'separate-document-collated-copies'.
In principle, the spooling printer can support all values of "sheet-collate"
and "multiple-document-handling".
However, the non-spooling Printer MUST keep the Document object (but not the
data) for the lifetime of the Job. The Printer cannot throw away the
Document object as soon as the Document has been printed, but MUST keep it
until the Job is completed. This requirement means that there is no extra
burden on a non-spooling Printer to have to accept multiple Create-Document
requests for a given job before getting any data. It has to keep all of the
Document objects for the life of the job anyway.
Goal 3. There are two client use cases that the spec needs to support:
Use Case A. A client should be able to validate all the documents in a
multi-document job, before sending the data for any of them. If the Printer
can't support a document or can't support it when combined with other
documents in the same job, the client can avoid sending any data, or decide
with the user which documents to actually submit in the Document Creation
operations.
Usage Case B. A client should be able to validate a document and send the
data, validate the next document and send its data, etc.
Given the above, here are my suggestions for the spec with my reasons:
1. Validate-Document should be removed from the spec (even though Printer's
are REQUIRED to support it in the current version).
If the client performs a Create-Document with "ipp-attribute-fidelity" =
'true', then it is practically the same as Validate-Document. If any of the
supplied attributes or values are unsupported, the Printer rejects the
operation and its the same a Validate-Document. Only if the Create-Document
succeeds, does the Printer actually create the Document object which is
probably what the client would want anyway (Use Case B). (In the unlikely
case that the client didn't want to create the Document object, the client
can do a Cancel-Document operation).
For the Validate-Document case when not supplying the "job-id", the client
can obtain the same functionality by using Validate-Job with each Document
separately, before sending any data (Use Case A).
Another reason to get rid of Validate-Document is because it doesn't
completely allow validation of all documents before sending any data (Use
Case A). For example, if a Printer object represents a one-sided color
printer and a two-sided black and white printer, Validate-Document will not
correctly validate a two-document job consisting of a two-sided black and
white document and a one-sided color job. This is because one of the
Document objects has to be created in order to validate the other Document
in combination. Secondly, if we REQUIRE Create-Document, there is no need
for Validate-Document, since Create-Document creates the Document object and
validates it in the context of the job (without the client sending any
data).
Also eliminating Validate-Document removes another REQUIRED operation
attribute for the Printer to support in Validate-Document, namely, the
"job-id". So the Printer doesn't have to have two validate paths, one for a
document in the context of a job and the other for the document by itself,
thereby simplifying Printer implementation and eliminating another set of
cases to be tested.
I know that the PSI also has Validate-Document, so we'll need to try to
convince them to drop Validate-Document as well.
2. Remove the "document-number" OPTIONAL operation attribute from the spec
for Create-Document, Send-Document, and Send-URI (Goal 1 above). The
"document-number" operation attribute was added to the Document Override
spec per request from Carl Kugler to support sending multiple document data
in parallel (on separate channels) for high end applications. The client
can force the Printer to number the documents by ordering the
Create-Document operations in the desired order and then send the data in
parallel for the documents. In order to meet the requirements of a
non-spooling printer, the client MUST issue the Send-Data request for each
document in order. If the Printer gets a Send-Data out of order (and can't
spool), then the Printer rejects the Send-Data with an error code:
"client-error-documents-not-in-order". If the client had a race between
different threads, then each thread will back off an try again when it gets
this error. If the client is single threaded, then the error indicates a
bug in the client.
3. Keep Create-Document and Send-Data as REQUIRED for the Printer to
support. Then these two operations are the preferred way for a client to
submit a multi-document job. Keeping them REQUIRED means that clients will
bother to support them. If they are OPTIONAL, most clients won't bother
supporting them. Finally, keeping them REQUIRED means that we can remove
the "document-number" operation attribute all together (as in point number 2
above), since Clients that want to submit data in parallel can do so using
multiple Create-Document calls in serial followed by multiple Send-Data
operations in parallel (on separate channels).
Having two operations, one to create the Document object and the other to
send the data, does REQUIRE the Printer to deal with the time-out problem.
But multi-document jobs already have to deal with the time-out problem,
after a Create-Job operation anyway, so timing out a Send-Data the didn't
happen soon enough after a Create-Document shouldn't be much of an extra
burden on the Printer.
After we did IPP/1.1, we wished that we had made Create-Job and
Send-Document REQUIRED, instead of Print-Job. After operational experience,
even Paul Moore regretted that Microsoft had demanded that the IPP WG make
Print-Job be REQUIRED and Create-Job/Send-Document be OPTIONAL. The problem
with Print-Job (and Send-Document) is that the client has to wait to get
back a failure status code in a Print-Job response until after the client
has wasted its time sending all of the data. Lets learn from our
experience with IPP/1.1 on the Job object and not repeat the same mistakes
on the Document object.
Maybe we should also consider whether to change Send-Document from REQUIRED
to OPTIONAL (as it is in RFC 2911).
Existing clients that use the OPTIONAL Send-Document can still interoperate
with Printers that support Send-Document.
Here is the list of operations:
Operation Name Printer Printer
support support
V0.1 proposed
Create-Document REQUIRED REQUIRED
Send-Data REQUIRED REQUIRED
Send-Document * REQUIRED keep OPTIONAL - OK?
Send-URI * OPTIONAL OPTIONAL
Validate-Document REQUIRED delete
Get-Document-Attributes REQUIRED REQUIRED
Get-Documents REQUIRED REQUIRED
Set-Document-Attributes OPTIONAL OPTIONAL
Cancel-Document REQUIRED REQUIRED
Cancel-Current-Document OPTIONAL delete **?
Delete-Document OPTIONAL OPTIONAL
* The existing IPP/1.1 operations defined in [RFC2911] with an extension so
the client can supply Document Template attributes in a new attribute Group
in the request.
** Cancel-Current-Job is fine, but Cancel-Current-Document is pretty funky
if the job has multiple documents and "copies" is greater than 1.
Comments?
Thanks,
Tom