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