< prev index next >
src/java.desktop/share/classes/javax/print/Doc.java
Print this page
@@ -1,7 +1,7 @@
/*
- * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
+ * 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
@@ -23,183 +23,167 @@
* questions.
*/
package javax.print;
-import java.io.InputStream;
import java.io.IOException;
+import java.io.InputStream;
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
+ * 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 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.
- *
- * <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
- * 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
+ * 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 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"
+ * 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>
+ * <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.
+ * 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
- * Doc.
+ * {@code Doc}.
* <p>
- * If print data is obtained from the client as a stream, by calling Doc's
- * {@code getReaderForText()} or {@code getStreamForBytes()}
- * 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
+ * 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.
- * <HR>
*/
public interface Doc {
/**
- * Determines the doc flavor in which this doc object will supply its
- * piece of print data.
+ * Determines the doc flavor in which this doc object will supply its piece
+ * of print data.
*
- * @return Doc flavor.
+ * @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 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.
+ * 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 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
+ * <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 null
- * to obtain all attribute values from the job's attribute
- * set.
+ * @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 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>
+ * 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 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.
- *
- * @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.
+ * 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.
*
- * @exception IOException
- * Thrown if there was an I/O error while creating the reader.
+ * @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 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>
+ * 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, null is returned.
- *
- * @exception IOException
- * Thrown if there was an I/O error while creating the input stream.
+ * @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;
-
}
< prev index next >