1 /*
2  * Copyright (c) 2000, 2021, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 package javax.print.attribute.standard;
27 
28 import java.io.Serial;
29 
30 import javax.print.attribute.Attribute;
31 import javax.print.attribute.DocAttribute;
32 import javax.print.attribute.EnumSyntax;
33 import javax.print.attribute.PrintJobAttribute;
34 import javax.print.attribute.PrintRequestAttribute;
35 
36 /**
37  * Class {@code SheetCollate} is a printing attribute class, an enumeration,
38  * that specifies whether or not the media sheets of each copy of each printed
39  * document in a job are to be in sequence, when multiple copies of the document
40  * are specified by the {@link Copies Copies} attribute. When
41  * {@code SheetCollate} is {@code COLLATED}, each copy of each document is
42  * printed with the print-stream sheets in sequence. When {@code SheetCollate}
43  * is {@code UNCOLLATED}, each print-stream sheet is printed a number of times
44  * equal to the value of the {@link Copies Copies} attribute in succession. For
45  * example, suppose a document produces two media sheets as output,
46  * {@link Copies Copies} is 6, and {@code SheetCollate} is UNCOLLATED; in this
47  * case six copies of the first media sheet are printed followed by six copies
48  * of the second media sheet.
49  * <p>
50  * Whether the effect of sheet collation is achieved by placing copies of a
51  * document in multiple output bins or in the same output bin with
52  * implementation defined document separation is implementation dependent. Also
53  * whether it is achieved by making multiple passes over the job or by using an
54  * output sorter is implementation dependent.
55  * <p>
56  * If a printer does not support the {@code SheetCollate} attribute (meaning the
57  * client cannot specify any particular sheet collation), the printer must
58  * behave as though {@code SheetCollate} were always set to {@code COLLATED}.
59  * <p>
60  * The {@code SheetCollate} attribute interacts with the
61  * {@link MultipleDocumentHandling MultipleDocumentHandling} attribute. The
62  * {@link MultipleDocumentHandling MultipleDocumentHandling} attribute describes
63  * the collation of entire documents, and the {@code SheetCollate} attribute
64  * describes the semantics of collating individual pages within a document.
65  * <p>
66  * The effect of a {@code SheetCollate} attribute on a multidoc print job (a job
67  * with multiple documents) depends on whether all the docs have the same sheet
68  * collation specified or whether different docs have different sheet collations
69  * specified, and on the (perhaps defaulted) value of the
70  * {@link MultipleDocumentHandling MultipleDocumentHandling} attribute.
71  * <ul>
72  *   <li>If all the docs have the same sheet collation specified, then the
73  *   following combinations of {@code SheetCollate} and
74  *   {@link MultipleDocumentHandling MultipleDocumentHandling} are permitted,
75  *   and the printer reports an error when the job is submitted if any other
76  *   combination is specified:
77  *   <ul>
78  *     <li>SheetCollate = COLLATED, {@link MultipleDocumentHandling
79  *     MultipleDocumentHandling} = SINGLE_DOCUMENT -- All the input docs will be
80  *     combined into one output document. Multiple copies of the output document
81  *     will be produced with pages in collated order, i.e. pages 1, 2, 3, . . .,
82  *     1, 2, 3, . . .
83  *     <li>SheetCollate = COLLATED, {@link MultipleDocumentHandling
84  *     MultipleDocumentHandling} = SINGLE_DOCUMENT_NEW_SHEET -- All the input
85  *     docs will be combined into one output document, and the first impression
86  *     of each input doc will always start on a new media sheet. Multiple copies
87  *     of the output document will be produced with pages in collated order,
88  *     i.e. pages 1, 2, 3, . . ., 1, 2, 3, . . .
89  *     <li>SheetCollate = COLLATED, {@link MultipleDocumentHandling
90  *     MultipleDocumentHandling} = SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each
91  *     input doc will remain a separate output document. Multiple copies of each
92  *     output document (call them A, B, . . .) will be produced with each
93  *     document's pages in collated order, but the documents themselves in
94  *     uncollated order, i.e. pages A1, A2, A3, . . ., A1, A2, A3, . . ., B1,
95  *     B2, B3, . . ., B1, B2, B3, . . .
96  *     <li>SheetCollate = COLLATED, {@link MultipleDocumentHandling
97  *     MultipleDocumentHandling} = SEPARATE_DOCUMENTS_COLLATED_COPIES -- Each
98  *     input doc will remain a separate output document. Multiple copies of each
99  *     output document (call them A, B, . . .) will be produced with each
100  *     document's pages in collated order, with the documents themselves also in
101  *     collated order, i.e. pages A1, A2, A3, . . ., B1, B2, B3, . . ., A1, A2,
102  *     A3, . . ., B1, B2, B3, . . .
103  *     <li>SheetCollate = UNCOLLATED, {@link MultipleDocumentHandling
104  *     MultipleDocumentHandling} = SINGLE_DOCUMENT -- All the input docs will be
105  *     combined into one output document. Multiple copies of the output document
106  *     will be produced with pages in uncollated order, i.e. pages 1, 1, . . .,
107  *     2, 2, . . ., 3, 3, . . .
108  *     <li>SheetCollate = UNCOLLATED, {@link MultipleDocumentHandling
109  *     MultipleDocumentHandling} = SINGLE_DOCUMENT_NEW_SHEET -- All the input
110  *     docs will be combined into one output document, and the first impression
111  *     of each input doc will always start on a new media sheet. Multiple copies
112  *     of the output document will be produced with pages in uncollated order,
113  *     i.e. pages 1, 1, . . ., 2, 2, . . ., 3, 3, . . .
114  *     <li>SheetCollate = UNCOLLATED, {@link MultipleDocumentHandling
115  *     MultipleDocumentHandling} = SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each
116  *     input doc will remain a separate output document. Multiple copies of each
117  *     output document (call them A, B, . . .) will be produced with each
118  *     document's pages in uncollated order, with the documents themselves also
119  *     in uncollated order, i.e. pages A1, A1, . . ., A2, A2, . . ., A3, A3, . .
120  *     ., B1, B1, . . ., B2, B2, . . ., B3, B3, . . .
121  *   </ul>
122  *   <li>If different docs have different sheet collations specified, then only
123  *   one value of {@link MultipleDocumentHandling MultipleDocumentHandling} is
124  *   permitted, and the printer reports an error when the job is submitted if
125  *   any other value is specified:
126  *   <ul>
127  *     <li>{@link MultipleDocumentHandling MultipleDocumentHandling} =
128  *     SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each input doc will remain a
129  *     separate output document. Multiple copies of each output document (call
130  *     them A, B, . . .) will be produced with each document's pages in collated
131  *     or uncollated order as the corresponding input doc's SheetCollate
132  *     attribute specifies, and with the documents themselves in uncollated
133  *     order. If document A had SheetCollate = UNCOLLATED and document B had
134  *     SheetCollate = COLLATED, the following pages would be produced: A1, A1, .
135  *     . ., A2, A2, . . ., A3, A3, . . ., B1, B2, B3, . . ., B1, B2, B3, . . .
136  *   </ul>
137  * </ul>
138  * <p>
139  * <b>IPP Compatibility:</b> SheetCollate is not an IPP attribute at present.
140  *
141  * @author Alan Kaminsky
142  * @see MultipleDocumentHandling
143  */
144 public final class SheetCollate extends EnumSyntax
145     implements DocAttribute, PrintRequestAttribute, PrintJobAttribute {
146 
147     /**
148      * Use serialVersionUID from JDK 1.4 for interoperability.
149      */
150     @Serial
151     private static final long serialVersionUID = 7080587914259873003L;
152 
153     /**
154      * Sheets within a document appear in uncollated order when multiple copies
155      * are printed.
156      */
157     public static final SheetCollate UNCOLLATED = new SheetCollate(0);
158 
159     /**
160      * Sheets within a document appear in collated order when multiple copies
161      * are printed.
162      */
163     public static final SheetCollate COLLATED = new SheetCollate(1);
164 
165     /**
166      * Construct a new sheet collate enumeration value with the given integer
167      * value.
168      *
169      * @param  value Integer value
170      */
SheetCollate(int value)171     protected SheetCollate(int value) {
172         super (value);
173     }
174 
175     /**
176      * The string table for class {@code SheetCollate}.
177      */
178     private static final String[] myStringTable = {
179         "uncollated",
180         "collated"
181     };
182 
183     /**
184      * The enumeration value table for class {@code SheetCollate}.
185      */
186     private static final SheetCollate[] myEnumValueTable = {
187         UNCOLLATED,
188         COLLATED
189     };
190 
191     /**
192      * Returns the string table for class {@code SheetCollate}.
193      */
getStringTable()194     protected String[] getStringTable() {
195         return myStringTable;
196     }
197 
198     /**
199      * Returns the enumeration value table for class {@code SheetCollate}.
200      */
getEnumValueTable()201     protected EnumSyntax[] getEnumValueTable() {
202         return myEnumValueTable;
203     }
204 
205     /**
206      * Get the printing attribute class which is to be used as the "category"
207      * for this printing attribute value.
208      * <p>
209      * For class {@code SheetCollate}, the category is class
210      * {@code SheetCollate} itself.
211      *
212      * @return printing attribute class (category), an instance of class
213      *         {@link Class java.lang.Class}
214      */
getCategory()215     public final Class<? extends Attribute> getCategory() {
216         return SheetCollate.class;
217     }
218 
219     /**
220      * Get the name of the category of which this attribute value is an
221      * instance.
222      * <p>
223      * For class {@code SheetCollate}, the category name is
224      * {@code "sheet-collate"}.
225      *
226      * @return attribute category name
227      */
getName()228     public final String getName() {
229         return "sheet-collate";
230     }
231 }
232