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