< prev index next >
src/java.desktop/share/classes/javax/print/SimpleDoc.java
Print this page
@@ -1,7 +1,7 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
@@ -25,64 +25,80 @@
package javax.print;
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.
* <p>
* In particular this class implements certain required semantics of the
- * Doc specification as follows:
+ * {@code Doc} specification as follows:
* <ul>
* <li>constructs a stream for the service if requested and appropriate.
* <li>ensures the same object is returned for each call on a method.
- * <li>ensures multiple threads can access the Doc
+ * <li>ensures multiple threads can access the {@code Doc}
* <li>performs some validation of that the data matches the doc flavor.
* </ul>
- * 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.
* <p>
- * 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.
+ * 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}.
+ * @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) {
if (flavor == null || printData == null) {
@@ -109,83 +125,76 @@
}
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;
}
/**
* 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() {
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.
- *
- * @exception IOException 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 {
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:
- * <UL>
- * <LI> {@code char[]}
- * <LI> {@code java.lang.String}
- * <LI> {@code 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>{@code char[]}
+ * <li>{@code java.lang.String}
+ * <li>{@code 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 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.
- *
- * @exception IOException if there was an I/O error while creating
- * the reader.
+ * 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.
+ * @throws IOException if there was an I/O error while creating the reader
*/
public Reader getReaderForText() throws IOException {
if (printData instanceof Reader) {
return (Reader)printData;
@@ -205,35 +214,29 @@
}
return reader;
}
/**
- * 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}:
- * <UL>
- * <LI> {@code byte[]}
- * <LI> {@code java.io.InputStream}
- * </UL>
- * 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.
- *
- * @exception IOException
- * if there was an I/O error while creating the input stream.
+ * 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}:
+ * <ul>
+ * <li>{@code byte[]}
+ * <li>{@code java.io.InputStream}
+ * </ul>
+ * 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.
+ * @throws IOException if there was an I/O error while creating the input
+ * stream
*/
public InputStream getStreamForBytes() throws IOException {
if (printData instanceof InputStream) {
return (InputStream)printData;
@@ -248,7 +251,6 @@
inStream = new ByteArrayInputStream((byte[])printData);
}
}
return inStream;
}
-
}
< prev index next >