2362N/A * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * Interface Doc specifies the interface for an object that supplies one piece 0N/A * of print data for a Print Job. "Doc" is a short, easy-to-pronounce term 0N/A * that means "a piece of print data." The client passes to the Print Job an 0N/A * object that implements interface Doc, and the Print Job calls methods on 0N/A * that object to obtain the print data. The Doc interface lets a Print Job: 0N/A * Determine the format, or "doc flavor" (class {@link DocFlavor DocFlavor}), 0N/A * in which the print data is available. A doc flavor designates the print 0N/A * data format (a MIME type) and the representation class of the object 0N/A * from which the print data comes. 0N/A * Obtain the print data representation object, which is an instance of the 0N/A * doc flavor's representation class. The Print Job can then obtain the actual 0N/A * print data from the representation object. 0N/A * Obtain the printing attributes that specify additional characteristics of 0N/A * the doc or that specify processing instructions to be applied to the doc. 0N/A * Printing attributes are defined in package {@link javax.print.attribute 0N/A * javax.print.attribute}. The doc returns its printing attributes stored in 0N/A * an {@link javax.print.attribute.DocAttributeSet javax.print.attribute.DocAttributeSet}. 0N/A * Each method in an implementation of interface Doc is permitted always to 0N/A * return the same object each time the method is called. 0N/A * This has implications 0N/A * for a Print Job or other caller of a doc object whose print data 0N/A * representation object "consumes" the print data as the caller obtains the 0N/A * print data, such as a print data representation object which is a stream. 0N/A * Once the Print Job has called {@link #getPrintData() 0N/A * <CODE>getPrintData()</CODE>} and obtained the stream, any further calls to 0N/A * {@link #getPrintData() <CODE>getPrintData()</CODE>} will return the same 0N/A * stream object upon which reading may already be in progress, <I>not</I> a new 0N/A * stream object that will re-read the print data from the beginning. Specifying 0N/A * a doc object to behave this way simplifies the implementation of doc objects, 0N/A * and is justified on the grounds that a particular doc is intended to convey 0N/A * print data only to one Print Job, not to several different Print Jobs. (To 0N/A * convey the same print data to several different Print Jobs, you have to 0N/A * create several different doc objects on top of the same print data source.) 0N/A * Interface Doc affords considerable implementation flexibility. The print data 0N/A * might already be in existence when the doc object is constructed. In this 0N/A * case the objects returned by the doc's methods can be supplied to the doc's 0N/A * constructor, be stored in the doc ahead of time, and simply be returned when 0N/A * called for. Alternatively, the print data might not exist yet when the doc 0N/A * object is constructed. In this case the doc object might provide a "lazy" 0N/A * implementation that generates the print data representation object (and/or 0N/A * the print data) only when the Print Job calls for it (when the Print Job 0N/A * calls the {@link #getPrintData() <CODE>getPrintData()</CODE>} method). 0N/A * There is no restriction on the number of client threads that may be 0N/A * simultaneously accessing the same doc. Therefore, all implementations of 0N/A * interface Doc must be designed to be multiple thread safe. 0N/A * However there can only be one consumer of the print data obtained from a 0N/A * If print data is obtained from the client as a stream, by calling Doc's 0N/A * <code>getReaderForText()</code> or <code>getStreamForBytes()</code> 0N/A * methods, or because the print data source is already an InputStream or 0N/A * Reader, then the print service should always close these streams for the 0N/A * client on all job completion conditions. With the following caveat. 0N/A * If the print data is itself a stream, the service will always close it. 0N/A * If the print data is otherwise something that can be requested as a stream, 0N/A * the service will only close the stream if it has obtained the stream before 0N/A * terminating. That is, just because a print service might request data as 0N/A * a stream does not mean that it will, with the implications that Doc 0N/A * implementors which rely on the service to close them should create such 0N/A * streams only in response to a request from the service. 0N/A * Determines the doc flavor in which this doc object will supply its 0N/A * piece of print data. 0N/A * @return Doc flavor. 0N/A * Obtains the print data representation object that contains this doc 0N/A * object's piece of print data in the format corresponding to the 0N/A * supported doc flavor. 0N/A * The <CODE>getPrintData()</CODE> method returns an instance of 0N/A * the representation class whose name is given by <CODE>{@link 0N/A * #getDocFlavor() getDocFlavor()}.{@link 0N/A * DocFlavor#getRepresentationClassName() 0N/A * getRepresentationClassName()}</CODE>, and the return value can be cast 0N/A * from class Object to that representation class. 0N/A * @return Print data representation object. 0N/A * @exception IOException 0N/A * Thrown if the representation class is a stream and there was an I/O 0N/A * error while constructing the stream. 0N/A * Obtains the set of printing attributes for this doc object. If the 0N/A * returned attribute set includes an instance of a particular attribute 0N/A * <I>X,</I> the printer must use that attribute value for this doc, 0N/A * overriding any value of attribute <I>X</I> in the job's attribute set. 0N/A * If the returned attribute set does not include an instance 0N/A * of a particular attribute <I>X</I> or if null is returned, the printer 0N/A * must consult the job's attribute set to obtain the value for 0N/A * attribute <I>X,</I> and if not found there, the printer must use an 0N/A * implementation-dependent default value. The returned attribute set is 0N/A * @return Unmodifiable set of printing attributes for this doc, or null 0N/A * to obtain all attribute values from the job's attribute 0N/A * Obtains a reader for extracting character print data from this doc. 0N/A * The Doc implementation is required to support this method if the 0N/A * DocFlavor has one of the following print data representation classes, 0N/A * and return null otherwise: 0N/A * <LI> java.lang.String 0N/A * <LI> java.io.Reader 0N/A * The doc's print data representation object is used to construct and 0N/A * return a Reader for reading the print data as a stream of characters 0N/A * from the print data representation object. 0N/A * However, if the print data representation object is itself a Reader, 0N/A * then the print data representation object is simply returned. 0N/A * @return Reader for reading the print data characters from this doc. 0N/A * If a reader cannot be provided because this doc does not meet 0N/A * the criteria stated above, null is returned. 0N/A * @exception IOException 0N/A * Thrown if there was an I/O error while creating the reader. 0N/A * Obtains an input stream for extracting byte print data from this 0N/A * doc. The Doc implementation is required to support this method if 0N/A * the DocFlavor has one of the following print data representation 0N/A * classes, and return null otherwise: 0N/A * <LI> java.io.InputStream 0N/A * This doc's print data representation object is obtained, then an input 0N/A * stream for reading the print data from the print data representation 0N/A * object as a stream of bytes is created and returned. However, if the 0N/A * print data representation object is itself an input stream, then the 0N/A * print data representation object is simply returned. 0N/A * @return Input stream for reading the print data bytes from this doc. If 0N/A * an input stream cannot be provided because this doc does not 0N/A * meet the criteria stated above, null is returned. 0N/A * @exception IOException 0N/A * Thrown if there was an I/O error while creating the input stream.