Doc.java

/*
 * 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.
 */

packagejavax.print;

importjava.io.IOException;
importjava.io.InputStream;
importjava.io.Reader;

importjavax.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.
 */
publicinterfaceDoc {

/**
 * Determines the doc flavor in which this doc object will supply its piece
 * of print data.
 *
 * @return doc flavor
 */
publicDocFlavorgetDocFlavor();

/**
 * 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
 */
publicObjectgetPrintData() throwsIOException;

/**
 * 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
 */
publicDocAttributeSetgetAttributes();

/**
 * 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
 */
publicReadergetReaderForText() throwsIOException;

/**
 * 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
 */
publicInputStreamgetStreamForBytes() throwsIOException;
}