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