1. /*
  2. * @(#)Doc.java 1.7 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.print;
  8. import java.io.InputStream;
  9. import java.io.IOException;
  10. import java.io.Reader;
  11. import java.io.UnsupportedEncodingException;
  12. import javax.print.attribute.AttributeSet;
  13. import javax.print.attribute.DocAttributeSet;
  14. /**
  15. * Interface Doc specifies the interface for an object that supplies one piece
  16. * of print data for a Print Job. "Doc" is a short, easy-to-pronounce term
  17. * that means "a piece of print data." The client passes to the Print Job an
  18. * object that implements interface Doc, and the Print Job calls methods on
  19. * that object to obtain the print data. The Doc interface lets a Print Job:
  20. * <UL>
  21. * <LI>
  22. * Determine the format, or "doc flavor" (class {@link DocFlavor DocFlavor}),
  23. * in which the print data is available. A doc flavor designates the print
  24. * data format (a MIME type) and the representation class of the object
  25. * from which the print data comes.
  26. * <P>
  27. * <LI>
  28. * Obtain the print data representation object, which is an instance of the
  29. * doc flavor's representation class. The Print Job can then obtain the actual
  30. * print data from the representation object.
  31. * <P>
  32. * <LI>
  33. * Obtain the printing attributes that specify additional characteristics of
  34. * the doc or that specify processing instructions to be applied to the doc.
  35. * Printing attributes are defined in package {@link javax.print.attribute
  36. * javax.print.attribute}. The doc returns its printing attributes stored in
  37. * an {@link javax.print.attribute.DocAttributeSet javax.print.attribute.DocAttributeSet}.
  38. * </UL>
  39. * <P>
  40. * Each method in an implementation of interface Doc is permitted always to
  41. * return the same object each time the method is called.
  42. * This has implications
  43. * for a Print Job or other caller of a doc object whose print data
  44. * representation object "consumes" the print data as the caller obtains the
  45. * print data, such as a print data representation object which is a stream.
  46. * Once the Print Job has called {@link #getPrintData()
  47. * <CODE>getPrintData()</CODE>} and obtained the stream, any further calls to
  48. * {@link #getPrintData() <CODE>getPrintData()</CODE>} will return the same
  49. * stream object upon which reading may already be in progress, <I>not</I> a new
  50. * stream object that will re-read the print data from the beginning. Specifying
  51. * a doc object to behave this way simplifies the implementation of doc objects,
  52. * and is justified on the grounds that a particular doc is intended to convey
  53. * print data only to one Print Job, not to several different Print Jobs. (To
  54. * convey the same print data to several different Print Jobs, you have to
  55. * create several different doc objects on top of the same print data source.)
  56. * <P>
  57. * Interface Doc affords considerable implementation flexibility. The print data
  58. * might already be in existence when the doc object is constructed. In this
  59. * case the objects returned by the doc's methods can be supplied to the doc's
  60. * constructor, be stored in the doc ahead of time, and simply be returned when
  61. * called for. Alternatively, the print data might not exist yet when the doc
  62. * object is constructed. In this case the doc object might provide a "lazy"
  63. * implementation that generates the print data representation object (and/or
  64. * the print data) only when the Print Job calls for it (when the Print Job
  65. * calls the {@link #getPrintData() <CODE>getPrintData()</CODE>} method).
  66. * <P>
  67. * There is no restriction on the number of client threads that may be
  68. * simultaneously accessing the same doc. Therefore, all implementations of
  69. * interface Doc must be designed to be multiple thread safe.
  70. * <p>
  71. * However there can only be one consumer of the print data obtained from a
  72. * Doc.
  73. * <p>
  74. * If print data is obtained from the client as a stream, by calling Doc's
  75. * <code>getReaderForText()</code> or <code>getStreamForBytes()</code>
  76. * methods, or because the print data source is already an InputStream or
  77. * Reader, then the print service should always close these streams for the
  78. * client on all job completion conditions. With the following caveat.
  79. * If the print data is itself a stream, the service will always close it.
  80. * If the print data is otherwise something that can be requested as a stream,
  81. * the service will only close the stream if it has obtained the stream before
  82. * terminating. That is, just because a print service might request data as
  83. * a stream does not mean that it will, with the implications that Doc
  84. * implementors which rely on the service to close them should create such
  85. * streams only in response to a request from the service.
  86. * <P>
  87. * <HR>
  88. */
  89. public interface Doc {
  90. /**
  91. * Determines the doc flavor in which this doc object will supply its
  92. * piece of print data.
  93. *
  94. * @return Doc flavor.
  95. */
  96. public DocFlavor getDocFlavor();
  97. /**
  98. * Obtains the print data representation object that contains this doc
  99. * object's piece of print data in the format corresponding to the
  100. * supported doc flavor.
  101. * The <CODE>getPrintData()</CODE> method returns an instance of
  102. * the representation class whose name is given by <CODE>{@link
  103. * #getDocFlavor() getDocFlavor()}.{@link
  104. * DocFlavor#getRepresentationClassName()
  105. * getRepresentationClassName()}</CODE>, and the return value can be cast
  106. * from class Object to that representation class.
  107. *
  108. * @return Print data representation object.
  109. *
  110. * @exception IOException
  111. * Thrown if the representation class is a stream and there was an I/O
  112. * error while constructing the stream.
  113. */
  114. public Object getPrintData() throws IOException;
  115. /**
  116. * Obtains the set of printing attributes for this doc object. If the
  117. * returned attribute set includes an instance of a particular attribute
  118. * <I>X,</I> the printer must use that attribute value for this doc,
  119. * overriding any value of attribute <I>X</I> in the job's attribute set.
  120. * If the returned attribute set does not include an instance
  121. * of a particular attribute <I>X</I> or if null is returned, the printer
  122. * must consult the job's attribute set to obtain the value for
  123. * attribute <I>X,</I> and if not found there, the printer must use an
  124. * implementation-dependent default value. The returned attribute set is
  125. * unmodifiable.
  126. *
  127. * @return Unmodifiable set of printing attributes for this doc, or null
  128. * to obtain all attribute values from the job's attribute
  129. * set.
  130. */
  131. public DocAttributeSet getAttributes();
  132. /**
  133. * Obtains a reader for extracting character print data from this doc.
  134. * The Doc implementation is required to support this method if the
  135. * DocFlavor has one of the following print data representation classes,
  136. * and return null otherwise:
  137. * <UL>
  138. * <LI> char[]
  139. * <LI> java.lang.String
  140. * <LI> java.io.Reader
  141. * </UL>
  142. * The doc's print data representation object is used to construct and
  143. * return a Reader for reading the print data as a stream of characters
  144. * from the print data representation object.
  145. * However, if the print data representation object is itself a Reader,
  146. * then the print data representation object is simply returned.
  147. * <P>
  148. * @return Reader for reading the print data characters from this doc.
  149. * If a reader cannot be provided because this doc does not meet
  150. * the criteria stated above, null is returned.
  151. *
  152. * @exception IOException
  153. * Thrown if there was an I/O error while creating the reader.
  154. */
  155. public Reader getReaderForText() throws IOException;
  156. /**
  157. * Obtains an input stream for extracting byte print data from this
  158. * doc. The Doc implementation is required to support this method if
  159. * the DocFlavor has one of the following print data representation
  160. * classes, and return null otherwise:
  161. * <UL>
  162. * <LI> byte[]
  163. * <LI> java.io.InputStream
  164. * </UL>
  165. * This doc's print data representation object is obtained, then an input
  166. * stream for reading the print data from the print data representation
  167. * object as a stream of bytes is created and returned. However, if the
  168. * print data representation object is itself an input stream, then the
  169. * print data representation object is simply returned.
  170. * <P>
  171. * @return Input stream for reading the print data bytes from this doc. If
  172. * an input stream cannot be provided because this doc does not
  173. * meet the criteria stated above, null is returned.
  174. *
  175. * @exception IOException
  176. * Thrown if there was an I/O error while creating the input stream.
  177. */
  178. public InputStream getStreamForBytes() throws IOException;
  179. }