1. /*
  2. * @(#)MultipleDocumentHandling.java 1.9 04/05/05
  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.attribute.standard;
  8. import javax.print.attribute.Attribute;
  9. import javax.print.attribute.EnumSyntax;
  10. import javax.print.attribute.PrintRequestAttribute;
  11. import javax.print.attribute.PrintJobAttribute;
  12. /**
  13. * Class MultipleDocumentHandling is a printing attribute class, an enumeration,
  14. * that controls finishing operations and the placement of one or more
  15. * print-stream pages into impressions and onto media sheets. When the value of
  16. * the {@link Copies Copies} attribute exceeds 1, MultipleDocumentHandling also
  17. * controls the order in which the copies that result from processing the
  18. * documents are produced. This attribute is relevant only for a multidoc print
  19. * job consisting of two or more individual docs.
  20. * <P>
  21. * Briefly, MultipleDocumentHandling determines the relationship between the
  22. * multiple input (electronic) documents fed into a multidoc print job and the
  23. * output (physical) document or documents produced by the multidoc print job.
  24. * There are two possibilities:
  25. * <UL>
  26. * <LI>
  27. * The multiple input documents are combined into a single output document.
  28. * Finishing operations ({@link Finishings Finishings}),
  29. * are performed on this single output
  30. * document. The {@link Copies Copies} attribute tells how many copies of this
  31. * single output document to produce. The MultipleDocumentHandling values
  32. * SINGLE_DOCUMENT and SINGLE_DOCUMENT_NEW_SHEET specify two variations of
  33. * this possibility.
  34. * <P>
  35. * <LI>
  36. * The multiple input documents remain separate output documents. Finishing
  37. * operations ({@link Finishings Finishings}),
  38. * are performed on each output document
  39. * separately. The {@link Copies Copies} attribute tells how many copies of each
  40. * separate output document to produce. The MultipleDocumentHandling values
  41. * SEPARATE_DOCUMENTS_UNCOLLATED_COPIES and SEPARATE_DOCUMENTS_COLLATED_COPIES
  42. * specify two variations of this possibility.
  43. * </UL>
  44. * <P>
  45. * In the detailed explanations below, if "<CODE>a</CODE>" represents an
  46. * instance of document data, then the result of processing the data in
  47. * document "<CODE>a</CODE>" is a sequence of media sheets represented by
  48. * "<CODE>a(*)</CODE>".
  49. * <P>
  50. * The standard MultipleDocumentHandling values are:
  51. * <UL>
  52. * <LI>
  53. * <A NAME="sdfi">{@link #SINGLE_DOCUMENT
  54. * <B><CODE>SINGLE_DOCUMENT</CODE></B>}</A>. If a print job has multiple
  55. * documents -- say, the document data is called <CODE>a</CODE> and
  56. * <CODE>b</CODE> -- then the result of processing all the document data
  57. * (<CODE>a</CODE> and then <CODE>b</CODE>) must be treated as a single sequence
  58. * of media sheets for finishing operations; that is, finishing would be
  59. * performed on the concatenation of the sequences <CODE>a(*),b(*)</CODE>. The
  60. * printer must not force the data in each document instance to be formatted
  61. * onto a new print-stream page, nor to start a new impression on a new media
  62. * sheet. If more than one copy is made, the ordering of the sets of media
  63. * sheets resulting from processing the document data must be
  64. * <CODE>a(*),b(*),a(*),b(*),...</CODE>, and the printer object must force
  65. * each copy (<CODE>a(*),b(*)</CODE>) to start on a new media sheet.
  66. * <P>
  67. * <LI>
  68. * <A NAME="sducfi">{@link #SEPARATE_DOCUMENTS_UNCOLLATED_COPIES
  69. * <B><CODE>SEPARATE_DOCUMENTS_UNCOLLATED_COPIES</CODE></B>}</A>. If a print job
  70. * has multiple documents -- say, the document data is called <CODE>a</CODE> and
  71. * <CODE>b</CODE> -- then the result of processing the data in each document
  72. * instance must be treated as a single sequence of media sheets for finishing
  73. * operations; that is, the sets <CODE>a(*)</CODE> and <CODE>b(*)</CODE> would
  74. * each be finished separately. The printer must force each copy of the result
  75. * of processing the data in a single document to start on a new media sheet.
  76. * If more than one copy is made, the ordering of the sets of media sheets
  77. * resulting from processing the document data must be
  78. * <CODE>a(*),a(*),...,b(*),b(*)...</CODE>.
  79. * <P>
  80. * <LI>
  81. * <A NAME="sdccfi">{@link #SEPARATE_DOCUMENTS_COLLATED_COPIES
  82. * <B><CODE>SEPARATE_DOCUMENTS_COLLATED_COPIES</CODE></B>}</A>. If a print job
  83. * has multiple documents -- say, the document data is called <CODE>a</CODE> and
  84. * <CODE>b</CODE> -- then the result of processing the data in each document
  85. * instance must be treated as a single sequence of media sheets for finishing
  86. * operations; that is, the sets <CODE>a(*)</CODE> and <CODE>b(*)</CODE> would
  87. * each be finished separately. The printer must force each copy of the result
  88. * of processing the data in a single document to start on a new media sheet.
  89. * If more than one copy is made, the ordering of the sets of media sheets
  90. * resulting from processing the document data must be
  91. * <CODE>a(*),b(*),a(*),b(*),...</CODE>.
  92. * <P>
  93. * <LI>
  94. * <A NAME="sdnsfi">{@link #SINGLE_DOCUMENT_NEW_SHEET
  95. * <B><CODE>SINGLE_DOCUMENT_NEW_SHEET</CODE></B>}</A>. Same as SINGLE_DOCUMENT,
  96. * except that the printer must ensure that the first impression of each
  97. * document instance in the job is placed on a new media sheet. This value
  98. * allows multiple documents to be stapled together with a single staple where
  99. * each document starts on a new sheet.
  100. * </UL>
  101. * <P>
  102. * SINGLE_DOCUMENT is the same as SEPARATE_DOCUMENTS_COLLATED_COPIES with
  103. * respect to ordering of print-stream pages, but not media sheet generation,
  104. * since SINGLE_DOCUMENT will put the first page of the next document on the
  105. * back side of a sheet if an odd number of pages have been produced so far
  106. * for the job, while SEPARATE_DOCUMENTS_COLLATED_COPIES always forces the
  107. * next document or document copy on to a new sheet.
  108. * <P>
  109. * In addition, if a {@link Finishings Finishings} attribute of
  110. * {@link Finishings#STAPLE <CODE>STAPLE</CODE>} is specified, then:
  111. * <UL>
  112. * <LI>
  113. * With SINGLE_DOCUMENT, documents <CODE>a</CODE> and <CODE>b</CODE> are
  114. * stapled together as a single document with no regard to new sheets.
  115. * <P>
  116. * <LI>
  117. * With SINGLE_DOCUMENT_NEW_SHEET, documents <CODE>a</CODE> and <CODE>b</CODE>
  118. * are stapled together as a single document, but document <CODE>b</CODE>
  119. * starts on a new sheet.
  120. * <P>
  121. * <LI>
  122. * With SEPARATE_DOCUMENTS_UNCOLLATED_COPIES and
  123. * SEPARATE_DOCUMENTS_COLLATED_COPIES, documents <CODE>a</CODE> and
  124. * <CODE>b</CODE> are stapled separately.
  125. * </UL>
  126. * <P>
  127. * <I>Note:</I> None of these values provide means to produce uncollated
  128. * sheets within a document, i.e., where multiple copies of sheet <I>n</I>
  129. * are produced before sheet <I>n</I>+1 of the same document.
  130. * To specify that, see the {@link SheetCollate SheetCollate} attribute.
  131. * <P>
  132. * <B>IPP Compatibility:</B> The category name returned by
  133. * <CODE>getName()</CODE> is the IPP attribute name. The enumeration's
  134. * integer value is the IPP enum value. The <code>toString()</code> method
  135. * returns the IPP string representation of the attribute value.
  136. * <P>
  137. *
  138. * @see Copies
  139. * @see Finishings
  140. * @see NumberUp
  141. * @see PageRanges
  142. * @see SheetCollate
  143. * @see Sides
  144. *
  145. * @author David Mendenhall
  146. * @author Alan Kaminsky
  147. */
  148. public class MultipleDocumentHandling extends EnumSyntax
  149. implements PrintRequestAttribute, PrintJobAttribute {
  150. private static final long serialVersionUID = 8098326460746413466L;
  151. /**
  152. * Single document -- see above for <A HREF="#sdfi">further
  153. * information</A>.
  154. */
  155. public static final MultipleDocumentHandling
  156. SINGLE_DOCUMENT = new MultipleDocumentHandling (0);
  157. /**
  158. * Separate documents uncollated copies -- see above for
  159. * <A HREF="#sducfi">further information</A>.
  160. */
  161. public static final MultipleDocumentHandling
  162. SEPARATE_DOCUMENTS_UNCOLLATED_COPIES = new MultipleDocumentHandling (1);
  163. /**
  164. * Separate documents collated copies -- see above for
  165. * <A HREF="#sdccfi">further information</A>.
  166. */
  167. public static final MultipleDocumentHandling
  168. SEPARATE_DOCUMENTS_COLLATED_COPIES = new MultipleDocumentHandling (2);
  169. /**
  170. * Single document new sheet -- see above for
  171. * <A HREF="#sdnsfi">further information</A>.
  172. */
  173. public static final MultipleDocumentHandling
  174. SINGLE_DOCUMENT_NEW_SHEET = new MultipleDocumentHandling (3);
  175. /**
  176. * Construct a new multiple document handling enumeration value with the
  177. * given integer value.
  178. *
  179. * @param value Integer value.
  180. */
  181. protected MultipleDocumentHandling(int value) {
  182. super (value);
  183. }
  184. private static final String[] myStringTable = {
  185. "single-document",
  186. "separate-documents-uncollated-copies",
  187. "separate-documents-collated-copies",
  188. "single-document-new-sheet"
  189. };
  190. private static final MultipleDocumentHandling[] myEnumValueTable = {
  191. SINGLE_DOCUMENT,
  192. SEPARATE_DOCUMENTS_UNCOLLATED_COPIES,
  193. SEPARATE_DOCUMENTS_COLLATED_COPIES,
  194. SINGLE_DOCUMENT_NEW_SHEET
  195. };
  196. /**
  197. * Returns the string table for class MultipleDocumentHandling.
  198. */
  199. protected String[] getStringTable() {
  200. return (String[])myStringTable.clone();
  201. }
  202. /**
  203. * Returns the enumeration value table for class MultipleDocumentHandling.
  204. */
  205. protected EnumSyntax[] getEnumValueTable() {
  206. return (EnumSyntax[])myEnumValueTable.clone();
  207. }
  208. /**
  209. * Get the printing attribute class which is to be used as the "category"
  210. * for this printing attribute value.
  211. * <P>
  212. * For class MultipleDocumentHandling and any vendor-defined subclasses,
  213. * the category is class MultipleDocumentHandling itself.
  214. *
  215. * @return Printing attribute class (category), an instance of class
  216. * {@link java.lang.Class java.lang.Class}.
  217. */
  218. public final Class<? extends Attribute> getCategory() {
  219. return MultipleDocumentHandling.class;
  220. }
  221. /**
  222. * Get the name of the category of which this attribute value is an
  223. * instance.
  224. * <P>
  225. * For class MultipleDocumentHandling and any vendor-defined subclasses,
  226. * the category name is <CODE>"multiple-document-handling"</CODE>.
  227. *
  228. * @return Attribute category name.
  229. */
  230. public final String getName() {
  231. return "multiple-document-handling";
  232. }
  233. }