Showing the changes to java/pkg/javax/print/MultiDoc.java (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,136 @@ | |||
| 1 | /* | ||
| 2 | * Copyright (c) 2000, Oracle and/or its affiliates. All rights reserved. | ||
| 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | ||
| 4 | * | ||
| 5 | * This code is free software; you can redistribute it and/or modify it | ||
| 6 | * under the terms of the GNU General Public License version 2 only, as | ||
| 7 | * published by the Free Software Foundation. Oracle designates this | ||
| 8 | * particular file as subject to the "Classpath" exception as provided | ||
| 9 | * by Oracle in the LICENSE file that accompanied this code. | ||
| 10 | * | ||
| 11 | * This code is distributed in the hope that it will be useful, but WITHOUT | ||
| 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | ||
| 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | ||
| 14 | * version 2 for more details (a copy is included in the LICENSE file that | ||
| 15 | * accompanied this code). | ||
| 16 | * | ||
| 17 | * You should have received a copy of the GNU General Public License version | ||
| 18 | * 2 along with this work; if not, write to the Free Software Foundation, | ||
| 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | ||
| 20 | * | ||
| 21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | ||
| 22 | * or visit www.oracle.com if you need additional information or have any | ||
| 23 | * questions. | ||
| 24 | */ | ||
| 25 | |||
| 26 | package javax.print; | ||
| 27 | |||
| 28 | import java.io.IOException; | ||
| 29 | |||
| 30 | /** | ||
| 31 | * Interface MultiDoc specifies the interface for an object that supplies more | ||
| 32 | * than one piece of print data for a Print Job. "Doc" is a short, | ||
| 33 | * easy-to-pronounce term that means "a piece of print data," and a "multidoc" | ||
| 34 | * is a group of several docs. The client passes to the Print Job an object | ||
| 35 | * that implements interface MultiDoc, and the Print Job calls methods on | ||
| 36 | * that object to obtain the print data. | ||
| 37 | * <P> | ||
| 38 | * Interface MultiDoc provides an abstraction similar to a "linked list" of | ||
| 39 | * docs. A multidoc object is like a node in the linked list, containing the | ||
| 40 | * current doc in the list and a pointer to the next node (multidoc) in the | ||
| 41 | * list. The Print Job can call the multidoc's {@link #getDoc() | ||
| 42 | * <CODE>getDoc()</CODE>} method to get the current doc. When it's ready to go | ||
| 43 | * on to the next doc, the Print Job can call the multidoc's {@link #next() | ||
| 44 | * <CODE>next()</CODE>} method to get the next multidoc, which contains the | ||
| 45 | * next doc. So Print Job code for accessing a multidoc might look like this: | ||
| 46 | * <PRE> | ||
| 47 | * void processMultiDoc(MultiDoc theMultiDoc) { | ||
| 48 | * | ||
| 49 | * MultiDoc current = theMultiDoc; | ||
| 50 | |||
| 51 | * while (current != null) { | ||
| 52 | * processDoc (current.getDoc()); | ||
| 53 | * current = current.next(); | ||
| 54 | * } | ||
| 55 | * } | ||
| 56 | * </PRE> | ||
| 57 | * <P> | ||
| 58 | * Of course, interface MultiDoc can be implemented in any way that fulfills | ||
| 59 | * the contract; it doesn't have to use a linked list in the implementation. | ||
| 60 | * <P> | ||
| 61 | * To get all the print data for a multidoc print job, a Print Service | ||
| 62 | * proxy could use either of two patterns: | ||
| 63 | * <OL TYPE=1> | ||
| 64 | * <LI> | ||
| 65 | * The <B>interleaved</B> pattern: Get the doc from the current multidoc. Get | ||
| 66 | * the print data representation object from the current doc. Get all the print | ||
| 67 | * data from the print data representation object. Get the next multidoc from | ||
| 68 | * the current multidoc, and repeat until there are no more. (The code example | ||
| 69 | * above uses the interleaved pattern.) | ||
| 70 | * <P> | ||
| 71 | * <LI> | ||
| 72 | * The <B>all-at-once</B> pattern: Get the doc from the current multidoc, and | ||
| 73 | * save the doc in a list. Get the next multidoc from the current multidoc, and | ||
| 74 | * repeat until there are no more. Then iterate over the list of saved docs. Get | ||
| 75 | * the print data representation object from the current doc. Get all the print | ||
| 76 | * data from the print data representation object. Go to the next doc in the | ||
| 77 | * list, and repeat until there are no more. | ||
| 78 | * </OL> | ||
| 79 | * Now, consider a printing client that is generating print data on the fly and | ||
| 80 | * does not have the resources to store more than one piece of print data at a | ||
| 81 | * time. If the print service proxy used the all-at-once pattern to get the | ||
| 82 | * print data, it would pose a problem for such a client; the client would have | ||
| 83 | * to keep all the docs' print data around until the print service proxy comes | ||
| 84 | * back and asks for them, which the client is not able to do. To work with such | ||
| 85 | * a client, the print service proxy must use the interleaved pattern. | ||
| 86 | * <P> | ||
| 87 | * To address this problem, and to simplify the design of clients providing | ||
| 88 | * multiple docs to a Print Job, every Print Service proxy that supports | ||
| 89 | * multidoc print jobs is required to access a MultiDoc object using the | ||
| 90 | * interleaved pattern. That is, given a MultiDoc object, the print service | ||
| 91 | * proxy will call {@link #getDoc() <CODE>getDoc()</CODE>} one or more times | ||
| 92 | * until it successfully obtains the current Doc object. The print service proxy | ||
| 93 | * will then obtain the current doc's print data, not proceeding until all the | ||
| 94 | * print data is obtained or an unrecoverable error occurs. If it is able to | ||
| 95 | * continue, the print service proxy will then call {@link #next() | ||
| 96 | * <CODE>next()</CODE>} one or more times until it successfully obtains either | ||
| 97 | * the next MultiDoc object or an indication that there are no more. An | ||
| 98 | * implementation of interface MultiDoc can assume the print service proxy will | ||
| 99 | * follow this interleaved pattern; for any other pattern of usage, the MultiDoc | ||
| 100 | * implementation's behavior is unspecified. | ||
| 101 | * <P> | ||
| 102 | * There is no restriction on the number of client threads that may be | ||
| 103 | * simultaneously accessing the same multidoc. Therefore, all implementations of | ||
| 104 | * interface MultiDoc must be designed to be multiple thread safe. In fact, a | ||
| 105 | * client thread could be adding docs to the end of the (conceptual) list while | ||
| 106 | * a Print Job thread is simultaneously obtaining docs from the beginning of the | ||
| 107 | * list; provided the multidoc object synchronizes the threads properly, the two | ||
| 108 | * threads will not interfere with each other | ||
| 109 | */ | ||
| 110 | |||
| 111 | public interface MultiDoc { | ||
| 112 | |||
| 113 | |||
| 114 | /** | ||
| 115 | * Obtain the current doc object. | ||
| 116 | * | ||
| 117 | * @return Current doc object. | ||
| 118 | * | ||
| 119 | * @exception IOException | ||
| 120 | * Thrown if a error ocurred reading the document. | ||
| 121 | */ | ||
| 122 | public Doc getDoc() throws IOException; | ||
| 123 | |||
| 124 | /** | ||
| 125 | * Go to the multidoc object that contains the next doc object in the | ||
| 126 | * sequence of doc objects. | ||
| 127 | * | ||
| 128 | * @return Multidoc object containing the next doc object, or null if | ||
| 129 | * there are no further doc objects. | ||
| 130 | * | ||
| 131 | * @exception IOException | ||
| 132 | * Thrown if an error occurred locating the next document | ||
| 133 | */ | ||
| 134 | public MultiDoc next() throws IOException; | ||
| 135 | |||
| 136 | } | ||