1 /* 2 * Copyright (c) 2000, 2014, 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 * 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 * 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()} or {@code getStreamForBytes()} 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 * <HR> 108 */ 109 public interface Doc { 110 111 /** 112 * Determines the doc flavor in which this doc object will supply its 113 * piece of print data. 114 * 115 * @return Doc flavor. 116 */ 117 public DocFlavor getDocFlavor(); 118 119 /** 120 * Obtains the print data representation object that contains this doc 121 * object's piece of print data in the format corresponding to the 122 * supported doc flavor. 123 * The {@code getPrintData()} method returns an instance of 124 * the representation class whose name is given by {@link 125 * #getDocFlavor() getDocFlavor()}.{@link 126 * DocFlavor#getRepresentationClassName() 127 * getRepresentationClassName()}, and the return value can be cast 128 * from class Object to that representation class. 129 * 130 * @return Print data representation object. 131 * 132 * @exception IOException 133 * Thrown if the representation class is a stream and there was an I/O 134 * error while constructing the stream. 135 */ 136 public Object getPrintData() throws IOException; 137 138 /** 139 * Obtains the set of printing attributes for this doc object. If the 140 * returned attribute set includes an instance of a particular attribute 141 * <I>X,</I> the printer must use that attribute value for this doc, 142 * overriding any value of attribute <I>X</I> in the job's attribute set. 143 * If the returned attribute set does not include an instance 144 * of a particular attribute <I>X</I> or if null is returned, the printer 145 * must consult the job's attribute set to obtain the value for 146 * attribute <I>X,</I> and if not found there, the printer must use an 147 * implementation-dependent default value. The returned attribute set is 148 * unmodifiable. 149 * 150 * @return Unmodifiable set of printing attributes for this doc, or null 151 * to obtain all attribute values from the job's attribute 152 * set. 153 */ 154 public DocAttributeSet getAttributes(); 155 156 /** 157 * Obtains a reader for extracting character print data from this doc. 158 * The Doc implementation is required to support this method if the 159 * DocFlavor has one of the following print data representation classes, 160 * and return null otherwise: 161 * <UL> 162 * <LI> char[] 163 * <LI> java.lang.String 164 * <LI> java.io.Reader 165 * </UL> 166 * The doc's print data representation object is used to construct and 167 * return a Reader for reading the print data as a stream of characters 168 * from the print data representation object. 169 * However, if the print data representation object is itself a Reader, 170 * then the print data representation object is simply returned. 171 * 172 * @return Reader for reading the print data characters from this doc. 173 * If a reader cannot be provided because this doc does not meet 174 * the criteria stated above, null is returned. 175 * 176 * @exception IOException 177 * Thrown if there was an I/O error while creating the reader. 178 */ 179 public Reader getReaderForText() throws IOException; 180 181 /** 182 * Obtains an input stream for extracting byte print data from this 183 * doc. The Doc implementation is required to support this method if 184 * the DocFlavor has one of the following print data representation 185 * classes, and return null otherwise: 186 * <UL> 187 * <LI> byte[] 188 * <LI> java.io.InputStream 189 * </UL> 190 * This doc's print data representation object is obtained, then an input 191 * stream for reading the print data from the print data representation 192 * object as a stream of bytes is created and returned. However, if the 193 * print data representation object is itself an input stream, then the 194 * print data representation object is simply returned. 195 * 196 * @return Input stream for reading the print data bytes from this doc. If 197 * an input stream cannot be provided because this doc does not 198 * meet the criteria stated above, null is returned. 199 * 200 * @exception IOException 201 * Thrown if there was an I/O error while creating the input stream. 202 */ 203 public InputStream getStreamForBytes() throws IOException; 204 205 } | 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 26 package javax.print; 27 28 import java.io.IOException; 29 import java.io.InputStream; 30 import java.io.Reader; 31 32 import 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 */ 101 public 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 } |