--- old/src/java.desktop/share/classes/javax/print/SimpleDoc.java 2017-08-11 15:11:51.000000000 -0700 +++ new/src/java.desktop/share/classes/javax/print/SimpleDoc.java 2017-08-11 15:11:51.000000000 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2001, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2001, 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 @@ -27,60 +27,76 @@ import java.io.ByteArrayInputStream; import java.io.CharArrayReader; -import java.io.StringReader; -import java.io.InputStream; import java.io.IOException; +import java.io.InputStream; import java.io.Reader; +import java.io.StringReader; + import javax.print.attribute.AttributeSetUtilities; import javax.print.attribute.DocAttributeSet; /** - * This class is an implementation of interface {@code Doc} that can - * be used in many common printing requests. - * It can handle all of the presently defined "pre-defined" doc flavors - * defined as static variables in the DocFlavor class. + * This class is an implementation of interface {@code Doc} that can be used in + * many common printing requests. It can handle all of the presently defined + * "pre-defined" doc flavors defined as static variables in the + * {@code DocFlavor} class. *

* In particular this class implements certain required semantics of the - * Doc specification as follows: + * {@code Doc} specification as follows: *

- * Clients who want to re-use the doc object in other jobs, - * or need a MultiDoc will not want to use this class. + * Clients who want to re-use the doc object in other jobs, or need a + * {@code MultiDoc} will not want to use this class. *

- * If the print data is a stream, or a print job requests data as a - * stream, then {@code SimpleDoc} does not monitor if the service - * properly closes the stream after data transfer completion or job - * termination. - * Clients may prefer to use provide their own implementation of doc that - * adds a listener to monitor job completion and to validate that - * resources such as streams are freed (ie closed). + * If the print data is a stream, or a print job requests data as a stream, then + * {@code SimpleDoc} does not monitor if the service properly closes the stream + * after data transfer completion or job termination. Clients may prefer to use + * provide their own implementation of doc that adds a listener to monitor job + * completion and to validate that resources such as streams are freed (ie + * closed). */ - public final class SimpleDoc implements Doc { + /** + * The doc flavor in which this doc will supply its piece of print data. + */ private DocFlavor flavor; + + /** + * The set of printing attributes for this doc. + */ private DocAttributeSet attributes; + + /** + * The print data. + */ private Object printData; + + /** + * The reader for extracting character print data from this doc. + */ private Reader reader; + + /** + * The input stream for extracting byte print data from this doc. + */ private InputStream inStream; /** - * Constructs a {@code SimpleDoc} with the specified - * print data, doc flavor and doc attribute set. - * @param printData the print data object - * @param flavor the {@code DocFlavor} object - * @param attributes a {@code DocAttributeSet}, which can - * be {@code null} - * @throws IllegalArgumentException if {@code flavor} or - * {@code printData} is {@code null}, or the - * {@code printData} does not correspond - * to the specified doc flavor--for example, the data is - * not of the type specified as the representation in the - * {@code DocFlavor}. + * Constructs a {@code SimpleDoc} with the specified print data, doc flavor + * and doc attribute set. + * + * @param printData the print data object + * @param flavor the {@code DocFlavor} object + * @param attributes a {@code DocAttributeSet}, which can be {@code null} + * @throws IllegalArgumentException if {@code flavor} or {@code printData} + * is {@code null}, or the {@code printData} does not correspond to + * the specified doc flavor--for example, the data is not of the + * type specified as the representation in the {@code DocFlavor} */ public SimpleDoc(Object printData, DocFlavor flavor, DocAttributeSet attributes) { @@ -110,11 +126,11 @@ this.printData = printData; } - /** - * 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() { return flavor; @@ -123,67 +139,60 @@ /** * Obtains the set of printing attributes for this doc object. If the * returned attribute set includes an instance of a particular attribute - * X, the printer must use that attribute value for this doc, - * overriding any value of attribute X in the job's attribute set. - * If the returned attribute set does not include an instance - * of a particular attribute X or if null is returned, the printer - * must consult the job's attribute set to obtain the value for - * attribute X, and if not found there, the printer must use an + * X, the printer must use that attribute value for this doc, + * overriding any value of attribute X in the job's attribute set. If + * the returned attribute set does not include an instance of a particular + * attribute X or if {@code null} is returned, the printer must + * consult the job's attribute set to obtain the value for attribute + * X, 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() { return attributes; } - /* + /** * 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 DocFlavor#getRepresentationClassName() getRepresentationClassName}, - * and the return value can be cast - * from class Object to that representation class. - * - * @return Print data representation object. + * 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. * - * @exception IOException if the representation class is a stream and - * there was an I/O error while constructing the stream. + * @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 { return printData; } /** - * 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: - *

+ * 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: + * * 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 a {@code 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. + * 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 if there was an I/O error while creating - * the reader. + * @return a {@code 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 { @@ -207,31 +216,25 @@ } /** - * 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; otherwise this method - * returns {@code null}: - * - * The 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 an {@code InputStream} 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. + * 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; otherwise this method returns {@code null}: + * + * The 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. * - * @exception IOException - * if there was an I/O error while creating the input stream. + * @return an {@code InputStream} 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 { @@ -250,5 +253,4 @@ } return inStream; } - }