1 /*
2 * Copyright 2000-2001 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.print;
27
28 import java.io.InputStream;
29 import java.io.IOException;
30 import java.io.Reader;
31 import java.io.UnsupportedEncodingException;
32
33 import javax.print.attribute.AttributeSet;
34 import javax.print.attribute.DocAttributeSet;
35
36
37 /**
38 * Interface Doc specifies the interface for an object that supplies one piece
39 * of print data for a Print Job. "Doc" is a short, easy-to-pronounce term
40 * that means "a piece of print data." The client passes to the Print Job an
41 * object that implements interface Doc, and the Print Job calls methods on
42 * that object to obtain the print data. The Doc interface lets a Print Job:
43 * <UL>
44 * <LI>
45 * Determine the format, or "doc flavor" (class {@link DocFlavor DocFlavor}),
46 * in which the print data is available. A doc flavor designates the print
47 * data format (a MIME type) and the representation class of the object
48 * from which the print data comes.
49 * <P>
50 * <LI>
51 * Obtain the print data representation object, which is an instance of the
52 * doc flavor's representation class. The Print Job can then obtain the actual
53 * print data from the representation object.
54 * <P>
55 * <LI>
56 * Obtain the printing attributes that specify additional characteristics of
57 * the doc or that specify processing instructions to be applied to the doc.
58 * Printing attributes are defined in package {@link javax.print.attribute
59 * javax.print.attribute}. The doc returns its printing attributes stored in
60 * an {@link javax.print.attribute.DocAttributeSet javax.print.attribute.DocAttributeSet}.
61 * </UL>
62 * <P>
63 * Each method in an implementation of interface Doc is permitted always to
64 * return the same object each time the method is called.
65 * This has implications
66 * for a Print Job or other caller of a doc object whose print data
67 * representation object "consumes" the print data as the caller obtains the
68 * print data, such as a print data representation object which is a stream.
69 * Once the Print Job has called {@link #getPrintData()
70 * <CODE>getPrintData()</CODE>} and obtained the stream, any further calls to
71 * {@link #getPrintData() <CODE>getPrintData()</CODE>} will return the same
72 * stream object upon which reading may already be in progress, <I>not</I> a new
73 * stream object that will re-read the print data from the beginning. Specifying
74 * a doc object to behave this way simplifies the implementation of doc objects,
75 * and is justified on the grounds that a particular doc is intended to convey
76 * print data only to one Print Job, not to several different Print Jobs. (To
77 * convey the same print data to several different Print Jobs, you have to
78 * create several different doc objects on top of the same print data source.)
79 * <P>
80 * Interface Doc affords considerable implementation flexibility. The print data
81 * might already be in existence when the doc object is constructed. In this
82 * case the objects returned by the doc's methods can be supplied to the doc's
83 * constructor, be stored in the doc ahead of time, and simply be returned when
84 * called for. Alternatively, the print data might not exist yet when the doc
85 * object is constructed. In this case the doc object might provide a "lazy"
86 * implementation that generates the print data representation object (and/or
87 * the print data) only when the Print Job calls for it (when the Print Job
88 * calls the {@link #getPrintData() <CODE>getPrintData()</CODE>} method).
89 * <P>
90 * There is no restriction on the number of client threads that may be
91 * simultaneously accessing the same doc. Therefore, all implementations of
92 * interface Doc must be designed to be multiple thread safe.
93 * <p>
94 * However there can only be one consumer of the print data obtained from a
95 * Doc.
96 * <p>
97 * If print data is obtained from the client as a stream, by calling Doc's
98 * <code>getReaderForText()</code> or <code>getStreamForBytes()</code>
99 * methods, or because the print data source is already an InputStream or
100 * Reader, then the print service should always close these streams for the
101 * client on all job completion conditions. With the following caveat.
102 * If the print data is itself a stream, the service will always close it.
103 * If the print data is otherwise something that can be requested as a stream,
104 * the service will only close the stream if it has obtained the stream before
105 * terminating. That is, just because a print service might request data as
106 * a stream does not mean that it will, with the implications that Doc
107 * implementors which rely on the service to close them should create such
108 * streams only in response to a request from the service.
109 * <P>
110 * <HR>
111 */
112 public interface Doc {
113
114 /**
115 * Determines the doc flavor in which this doc object will supply its
116 * piece of print data.
117 *
118 * @return Doc flavor.
119 */
120 public DocFlavor getDocFlavor();
121
122 /**
123 * Obtains the print data representation object that contains this doc
124 * object's piece of print data in the format corresponding to the
125 * supported doc flavor.
126 * The <CODE>getPrintData()</CODE> method returns an instance of
127 * the representation class whose name is given by <CODE>{@link
128 * #getDocFlavor() getDocFlavor()}.{@link
129 * DocFlavor#getRepresentationClassName()
130 * getRepresentationClassName()}</CODE>, and the return value can be cast
131 * from class Object to that representation class.
132 *
133 * @return Print data representation object.
134 *
135 * @exception IOException
136 * Thrown if the representation class is a stream and there was an I/O
137 * error while constructing the stream.
138 */
139 public Object getPrintData() throws IOException;
140
141 /**
142 * Obtains the set of printing attributes for this doc object. If the
143 * returned attribute set includes an instance of a particular attribute
144 * <I>X,</I> the printer must use that attribute value for this doc,
145 * overriding any value of attribute <I>X</I> in the job's attribute set.
146 * If the returned attribute set does not include an instance
147 * of a particular attribute <I>X</I> or if null is returned, the printer
148 * must consult the job's attribute set to obtain the value for
149 * attribute <I>X,</I> and if not found there, the printer must use an
150 * implementation-dependent default value. The returned attribute set is
151 * unmodifiable.
152 *
153 * @return Unmodifiable set of printing attributes for this doc, or null
154 * to obtain all attribute values from the job's attribute
155 * set.
156 */
157 public DocAttributeSet getAttributes();
158
159 /**
160 * Obtains a reader for extracting character print data from this doc.
161 * The Doc implementation is required to support this method if the
162 * DocFlavor has one of the following print data representation classes,
163 * and return null otherwise:
164 * <UL>
165 * <LI> char[]
166 * <LI> java.lang.String
167 * <LI> java.io.Reader
168 * </UL>
169 * The doc's print data representation object is used to construct and
170 * return a Reader for reading the print data as a stream of characters
171 * from the print data representation object.
172 * However, if the print data representation object is itself a Reader,
173 * then the print data representation object is simply returned.
174 * <P>
175 * @return Reader for reading the print data characters from this doc.
176 * If a reader cannot be provided because this doc does not meet
177 * the criteria stated above, null is returned.
178 *
179 * @exception IOException
180 * Thrown if there was an I/O error while creating the reader.
181 */
182 public Reader getReaderForText() throws IOException;
183
184 /**
185 * Obtains an input stream for extracting byte print data from this
186 * doc. The Doc implementation is required to support this method if
187 * the DocFlavor has one of the following print data representation
188 * classes, and return null otherwise:
189 * <UL>
190 * <LI> byte[]
191 * <LI> java.io.InputStream
192 * </UL>
193 * This doc's print data representation object is obtained, then an input
194 * stream for reading the print data from the print data representation
195 * object as a stream of bytes is created and returned. However, if the
196 * print data representation object is itself an input stream, then the
197 * print data representation object is simply returned.
198 * <P>
199 * @return Input stream for reading the print data bytes from this doc. If
200 * an input stream cannot be provided because this doc does not
201 * meet the criteria stated above, null is returned.
202 *
203 * @exception IOException
204 * Thrown if there was an I/O error while creating the input stream.
205 */
206 public InputStream getStreamForBytes() throws IOException;
207
208 }
Save This Page