View Javadoc
1   /*
2    * Copyright (c) 2000, 2013, 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   * getPrintData()} and obtained the stream, any further calls to
69   * {@link #getPrintData() getPrintData()} 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() getPrintData()} 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 }