Java tutorial
/* * Copyright (c) 2000, 2017, 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.IOException; import java.io.InputStream; import java.io.Reader; import javax.print.attribute.DocAttributeSet; /** * Interface {@code 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 {@code Doc}, and the Print Job calls methods * on that object to obtain the print data. The {@code 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. * <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. * <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}. The doc returns its printing attributes * stored in an {@link DocAttributeSet javax.print.attribute.DocAttributeSet}. * </ul> * Each method in an implementation of interface {@code 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() getPrintData()} and * obtained the stream, any further calls to {@link #getPrintData() * getPrintData()} 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 {@code 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() getPrintData()} 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 {@code Doc} must be designed to be multiple thread safe. * <p> * However there can only be one consumer of the print data obtained from a * {@code Doc}. * <p> * If print data is obtained from the client as a stream, by calling * {@code Doc}'s {@code getReaderForText()} or {@code getStreamForBytes()} * methods, or because the print data source is already an {@code InputStream} * or {@code 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 {@code Doc} * implementors which rely on the service to close them should create such * streams only in response to a request from the service. */ 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()} method returns an instance of the * representation class whose name is given by{@link #getDocFlavor() * getDocFlavor()}.{@link DocFlavor#getRepresentationClassName() * getRepresentationClassName()}, and the return value can be cast from * class {@code Object} to that representation class. * * @return print data representation object * @throws IOException 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 {@code 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 * {@code 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 * {@code Doc} implementation is required to support this method if the * {@code DocFlavor} has one of the following print data representation * classes, and return {@code 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 {@code 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 {@code Reader}, then the * print data representation object is simply returned. * * @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, {@code null} is returned. * @throws IOException 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 * {@code Doc} implementation is required to support this method if the * {@code DocFlavor} has one of the following print data representation * classes, and return {@code 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. * * @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, {@code null} is returned. * @throws IOException if there was an I/O error while creating the input * stream */ public InputStream getStreamForBytes() throws IOException; }