KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > print > MultiDoc


1 /*
2  * @(#)MultiDoc.java 1.4 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.print;
9
10 import java.io.IOException JavaDoc;
11
12 /**
13  * Interface MultiDoc specifies the interface for an object that supplies more
14  * than one piece of print data for a Print Job. "Doc" is a short,
15  * easy-to-pronounce term that means "a piece of print data," and a "multidoc"
16  * is a group of several docs. The client passes to the Print Job an object
17  * that implements interface MultiDoc, and the Print Job calls methods on
18  * that object to obtain the print data.
19  * <P>
20  * Interface MultiDoc provides an abstraction similar to a "linked list" of
21  * docs. A multidoc object is like a node in the linked list, containing the
22  * current doc in the list and a pointer to the next node (multidoc) in the
23  * list. The Print Job can call the multidoc's {@link #getDoc()
24  * <CODE>getDoc()</CODE>} method to get the current doc. When it's ready to go
25  * on to the next doc, the Print Job can call the multidoc's {@link #next()
26  * <CODE>next()</CODE>} method to get the next multidoc, which contains the
27  * next doc. So Print Job code for accessing a multidoc might look like this:
28  * <PRE>
29  * void processMultiDoc(MultiDoc theMultiDoc) {
30  *
31  * MultiDoc current = theMultiDoc;
32
33  * while (current != null) {
34  * processDoc (current.getDoc());
35  * current = current.next();
36  * }
37  * }
38  * </PRE>
39  * <P>
40  * Of course, interface MultiDoc can be implemented in any way that fulfills
41  * the contract; it doesn't have to use a linked list in the implementation.
42  * <P>
43  * To get all the print data for a multidoc print job, a Print Service
44  * proxy could use either of two patterns:
45  * <OL TYPE=1>
46  * <LI>
47  * The <B>interleaved</B> pattern: Get the doc from the current multidoc. Get
48  * the print data representation object from the current doc. Get all the print
49  * data from the print data representation object. Get the next multidoc from
50  * the current multidoc, and repeat until there are no more. (The code example
51  * above uses the interleaved pattern.)
52  * <P>
53  * <LI>
54  * The <B>all-at-once</B> pattern: Get the doc from the current multidoc, and
55  * save the doc in a list. Get the next multidoc from the current multidoc, and
56  * repeat until there are no more. Then iterate over the list of saved docs. Get
57  * the print data representation object from the current doc. Get all the print
58  * data from the print data representation object. Go to the next doc in the
59  * list, and repeat until there are no more.
60  * </OL>
61  * Now, consider a printing client that is generating print data on the fly and
62  * does not have the resources to store more than one piece of print data at a
63  * time. If the print service proxy used the all-at-once pattern to get the
64  * print data, it would pose a problem for such a client; the client would have
65  * to keep all the docs' print data around until the print service proxy comes
66  * back and asks for them, which the client is not able to do. To work with such
67  * a client, the print service proxy must use the interleaved pattern.
68  * <P>
69  * To address this problem, and to simplify the design of clients providing
70 * multiple docs to a Print Job, every Print Service proxy that supports
71  * multidoc print jobs is required to access a MultiDoc object using the
72  * interleaved pattern. That is, given a MultiDoc object, the print service
73  * proxy will call {@link #getDoc() <CODE>getDoc()</CODE>} one or more times
74  * until it successfully obtains the current Doc object. The print service proxy
75  * will then obtain the current doc's print data, not proceeding until all the
76  * print data is obtained or an unrecoverable error occurs. If it is able to
77  * continue, the print service proxy will then call {@link #next()
78  * <CODE>next()</CODE>} one or more times until it successfully obtains either
79  * the next MultiDoc object or an indication that there are no more. An
80  * implementation of interface MultiDoc can assume the print service proxy will
81  * follow this interleaved pattern; for any other pattern of usage, the MultiDoc
82  * implementation's behavior is unspecified.
83  * <P>
84  * There is no restriction on the number of client threads that may be
85  * simultaneously accessing the same multidoc. Therefore, all implementations of
86  * interface MultiDoc must be designed to be multiple thread safe. In fact, a
87  * client thread could be adding docs to the end of the (conceptual) list while
88  * a Print Job thread is simultaneously obtaining docs from the beginning of the
89  * list; provided the multidoc object synchronizes the threads properly, the two
90  * threads will not interfere with each other
91  */
92
93 public interface MultiDoc {
94
95
96     /**
97      * Obtain the current doc object.
98      *
99      * @return Current doc object.
100      *
101      * @exception IOException
102      * Thrown if a error ocurred reading the document.
103      */
104     public Doc JavaDoc getDoc() throws IOException JavaDoc;
105
106     /**
107      * Go to the multidoc object that contains the next doc object in the
108      * sequence of doc objects.
109      *
110      * @return Multidoc object containing the next doc object, or null if
111      * there are no further doc objects.
112      *
113      * @exception IOException
114      * Thrown if an error occurred locating the next document
115      */
116     public MultiDoc JavaDoc next() throws IOException JavaDoc;
117
118 }
119
Popular Tags