public interface MultiDoc
MultiDoc
specifies the interface for an object that supplies more than one piece of print data for a Print Job. "Doc" is a short, easy-to-pronounce term that means "a piece of print data," and a "multidoc" is a group of several docs. The client passes to the Print Job an object that implements interface MultiDoc
, and the Print Job calls methods on that object to obtain the print data. Interface MultiDoc
provides an abstraction similar to a "linked list" of docs. A multidoc object is like a node in the linked list, containing the current doc in the list and a pointer to the next node (multidoc) in the list. The Print Job can call the multidoc's getDoc()
method to get the current doc. When it's ready to go on to the next doc, the Print Job can call the multidoc's next()
method to get the next multidoc, which contains the next doc. So Print Job code for accessing a multidoc might look like this:
void processMultiDoc(MultiDoc theMultiDoc) { MultiDoc current = theMultiDoc; while (current != null) { processDoc (current.getDoc()); current = current.next(); } }Of course, interface
MultiDoc
can be implemented in any way that fulfills the contract; it doesn't have to use a linked list in the implementation. To get all the print data for a multidoc print job, a Print Service proxy could use either of two patterns:
To address this problem, and to simplify the design of clients providing multiple docs to a Print Job, every Print Service proxy that supports multidoc print jobs is required to access a MultiDoc
object using the interleaved pattern. That is, given a MultiDoc
object, the print service proxy will call getDoc()
one or more times until it successfully obtains the current Doc
object. The print service proxy will then obtain the current doc's print data, not proceeding until all the print data is obtained or an unrecoverable error occurs. If it is able to continue, the print service proxy will then call next()
one or more times until it successfully obtains either the next MultiDoc
object or an indication that there are no more. An implementation of interface MultiDoc
can assume the print service proxy will follow this interleaved pattern; for any other pattern of usage, the MultiDoc
implementation's behavior is unspecified.
There is no restriction on the number of client threads that may be simultaneously accessing the same multidoc. Therefore, all implementations of interface MultiDoc must be designed to be multiple thread safe. In fact, a client thread could be adding docs to the end of the (conceptual) list while a Print Job thread is simultaneously obtaining docs from the beginning of the list; provided the multidoc object synchronizes the threads properly, the two threads will not interfere with each other.
Doc getDoc() throws IOException
IOException
- if an error occurred when reading the documentMultiDoc next() throws IOException
null
if there are no further doc objectsIOException
- if an error occurred locating the next document
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/print/MultiDoc.html