1 /*
2 * Copyright (c) 2000, 2017, 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 javax.print.attribute.Attribute;
29 import javax.print.attribute.DocAttribute;
30 import javax.print.attribute.EnumSyntax;
31 import javax.print.attribute.PrintJobAttribute;
32 import javax.print.attribute.PrintRequestAttribute;
33
34 /**
35 * Class {@code Finishings} is a printing attribute class, an enumeration, that
36 * identifies whether the printer applies a finishing operation of some kind of
37 * binding to each copy of each printed document in the job. For multidoc print
38 * jobs (jobs with multiple documents), the
39 * {@link MultipleDocumentHandling MultipleDocumentHandling} attribute
40 * determines what constitutes a "copy" for purposes of finishing.
41 * <p>
42 * Standard Finishings values are:
43 * <table class="borderless" style="width:100%;margin: 0px auto">
44 * <caption>Standard Finishings values</caption>
45 * <tr>
46 * <td style="width:10%">
47 * <td style="width:27%">{@link #NONE NONE}
48 * <td style="width:27%">{@link #STAPLE STAPLE}
49 * <td style="width:36%">{@link #EDGE_STITCH EDGE_STITCH}
50 * <tr>
51 * <td>
52 * <td>{@link #BIND BIND}
53 * <td>{@link #SADDLE_STITCH SADDLE_STITCH}
54 * <td>{@link #COVER COVER}
55 * <td>
56 * </table>
57 * <p>
58 * The following {@code Finishings} values are more specific; they indicate a
59 * corner or an edge as if the document were a portrait document:
60 * <table class="borderless" style="width:100%;margin: 0px auto">
61 * <caption>Specific Finishings values</caption>
62 * <tr>
63 * <td style="width:10%">
64 * <td style="width:27%">{@link #STAPLE_TOP_LEFT STAPLE_TOP_LEFT}
65 * <td style="width:27%">{@link #EDGE_STITCH_LEFT EDGE_STITCH_LEFT}
66 * <td style="width:27%">{@link #STAPLE_DUAL_LEFT STAPLE_DUAL_LEFT}
67 * <td style="width:9%">
68 * <tr>
69 * <td style="width:10%">
70 * <td style="width:27%">{@link #STAPLE_BOTTOM_LEFT STAPLE_BOTTOM_LEFT}
71 * <td style="width:27%">{@link #EDGE_STITCH_TOP EDGE_STITCH_TOP}
72 * <td style="width:27%">{@link #STAPLE_DUAL_TOP STAPLE_DUAL_TOP}
73 * <td style="width:9%">
74 * <tr>
75 * <td style="width:10%">
76 * <td style="width:27%">{@link #STAPLE_TOP_RIGHT STAPLE_TOP_RIGHT}
77 * <td style="width:27%">{@link #EDGE_STITCH_RIGHT EDGE_STITCH_RIGHT}
78 * <td style="width:27%">{@link #STAPLE_DUAL_RIGHT STAPLE_DUAL_RIGHT}
79 * <td style="width:9%">
80 * <tr>
81 * <td style="width:10%">
82 * <td style="width:27%">{@link #STAPLE_BOTTOM_RIGHT STAPLE_BOTTOM_RIGHT}
83 * <td style="width:27%">{@link #EDGE_STITCH_BOTTOM EDGE_STITCH_BOTTOM}
84 * <td style="width:27%">{@link #STAPLE_DUAL_BOTTOM STAPLE_DUAL_BOTTOM}
85 * <td style="width:9%">
86 * </table>
87 * <p>
88 * The STAPLE_<i>XXX</i> values are specified with respect to the document as if
89 * the document were a portrait document. If the document is actually a
90 * landscape or a reverse-landscape document, the client supplies the
91 * appropriate transformed value. For example, to position a staple in the upper
92 * left hand corner of a landscape document when held for reading, the client
93 * supplies the {@code STAPLE_BOTTOM_LEFT} value (since landscape is defined as
94 * a +90 degree rotation from portrait, i.e., anti-clockwise). On the other
95 * hand, to position a staple in the upper left hand corner of a
96 * reverse-landscape document when held for reading, the client supplies the
97 * {@code STAPLE_TOP_RIGHT} value (since reverse-landscape is defined as a -90
98 * degree rotation from portrait, i.e., clockwise).
99 * <p>
100 * The angle (vertical, horizontal, angled) of each staple with respect to the
101 * document depends on the implementation which may in turn depend on the value
102 * of the attribute.
103 * <p>
104 * The effect of a {@code Finishings} attribute on a multidoc print job (a job
105 * with multiple documents) depends on whether all the docs have the same
106 * binding specified or whether different docs have different bindings
107 * specified, and on the (perhaps defaulted) value of the
108 * {@link MultipleDocumentHandling MultipleDocumentHandling} attribute.
109 * <ul>
110 * <li>If all the docs have the same binding specified, then any value of
111 * {@link MultipleDocumentHandling MultipleDocumentHandling} makes sense, and
112 * the printer's processing depends on the
113 * {@link MultipleDocumentHandling MultipleDocumentHandling} value:
114 * <ul>
115 * <li>{@code SINGLE_DOCUMENT} -- All the input docs will be bound together
116 * as one output document with the specified binding.
117 * <li>{@code SINGLE_DOCUMENT_NEW_SHEET} -- All the input docs will be bound
118 * together as one output document with the specified binding, and the first
119 * impression of each input doc will always start on a new media sheet.
120 * <li>{@code SEPARATE_DOCUMENTS_UNCOLLATED_COPIES} -- Each input doc will
121 * be bound separately with the specified binding.
122 * <li>{@code SEPARATE_DOCUMENTS_COLLATED_COPIES} -- Each input doc will be
123 * bound separately with the specified binding.
124 * </ul>
125 * <li>If different docs have different bindings specified, then only two
126 * values of {@link MultipleDocumentHandling MultipleDocumentHandling} make
127 * sense, and the printer reports an error when the job is submitted if any
128 * other value is specified:
129 * <ul>
130 * <li>{@code SEPARATE_DOCUMENTS_UNCOLLATED_COPIES} -- Each input doc will
131 * be bound separately with its own specified binding.
132 * <li>{@code SEPARATE_DOCUMENTS_COLLATED_COPIES} -- Each input doc will be
133 * bound separately with its own specified binding.
134 * </ul>
135 * </ul>
136 * <p>
137 * <b>IPP Compatibility:</b> Class Finishings encapsulates some of the IPP enum
138 * values that can be included in an IPP "finishings" attribute, which is a set
139 * of enums. The category name returned by {@code getName()} is the IPP
140 * attribute name. The enumeration's integer value is the IPP enum value. The
141 * {@code toString()} method returns the IPP string representation of the
142 * attribute value. In IPP Finishings is a multi-value attribute, this API
143 * currently allows only one binding to be specified.
144 *
145 * @author Alan Kaminsky
146 */
147 public class Finishings extends EnumSyntax
148 implements DocAttribute, PrintRequestAttribute, PrintJobAttribute {
149
150 /**
151 * Use serialVersionUID from JDK 1.4 for interoperability.
152 */
153 private static final long serialVersionUID = -627840419548391754L;
154
155 /**
156 * Perform no binding.
157 */
158 public static final Finishings NONE = new Finishings(3);
159
160 /**
161 * Bind the document(s) with one or more staples. The exact number and
162 * placement of the staples is site-defined.
163 */
164 public static final Finishings STAPLE = new Finishings(4);
165
166 /**
167 * This value is specified when it is desired to select a non-printed (or
168 * pre-printed) cover for the document. This does not supplant the
169 * specification of a printed cover (on cover stock medium) by the document
170 * itself.
171 */
172 public static final Finishings COVER = new Finishings(6);
173
174 /**
175 * This value indicates that a binding is to be applied to the document; the
176 * type and placement of the binding is site-defined.
177 */
178 public static final Finishings BIND = new Finishings(7);
179
180 /**
181 * Bind the document(s) with one or more staples (wire stitches) along the
182 * middle fold. The exact number and placement of the staples and the middle
183 * fold is implementation- and/or site-defined.
184 */
185 public static final Finishings SADDLE_STITCH =
186 new Finishings(8);
187
188 /**
189 * Bind the document(s) with one or more staples (wire stitches) along one
190 * edge. The exact number and placement of the staples is implementation-
191 * and/or site- defined.
192 */
193 public static final Finishings EDGE_STITCH =
194 new Finishings(9);
195
196 /**
197 * Bind the document(s) with one or more staples in the top left corner.
198 */
199 public static final Finishings STAPLE_TOP_LEFT =
200 new Finishings(20);
201
202 /**
203 * Bind the document(s) with one or more staples in the bottom left corner.
204 */
205 public static final Finishings STAPLE_BOTTOM_LEFT =
206 new Finishings(21);
207
208 /**
209 * Bind the document(s) with one or more staples in the top right corner.
210 */
211 public static final Finishings STAPLE_TOP_RIGHT =
212 new Finishings(22);
213
214 /**
215 * Bind the document(s) with one or more staples in the bottom right corner.
216 */
217 public static final Finishings STAPLE_BOTTOM_RIGHT =
218 new Finishings(23);
219
220 /**
221 * Bind the document(s) with one or more staples (wire stitches) along the
222 * left edge. The exact number and placement of the staples is
223 * implementation- and/or site-defined.
224 */
225 public static final Finishings EDGE_STITCH_LEFT =
226 new Finishings(24);
227
228 /**
229 * Bind the document(s) with one or more staples (wire stitches) along the
230 * top edge. The exact number and placement of the staples is
231 * implementation- and/or site-defined.
232 */
233 public static final Finishings EDGE_STITCH_TOP =
234 new Finishings(25);
235
236 /**
237 * Bind the document(s) with one or more staples (wire stitches) along the
238 * right edge. The exact number and placement of the staples is
239 * implementation- and/or site-defined.
240 */
241 public static final Finishings EDGE_STITCH_RIGHT =
242 new Finishings(26);
243
244 /**
245 * Bind the document(s) with one or more staples (wire stitches) along the
246 * bottom edge. The exact number and placement of the staples is
247 * implementation- and/or site-defined.
248 */
249 public static final Finishings EDGE_STITCH_BOTTOM =
250 new Finishings(27);
251
252 /**
253 * Bind the document(s) with two staples (wire stitches) along the left edge
254 * assuming a portrait document (see above).
255 */
256 public static final Finishings STAPLE_DUAL_LEFT =
257 new Finishings(28);
258
259 /**
260 * Bind the document(s) with two staples (wire stitches) along the top edge
261 * assuming a portrait document (see above).
262 */
263 public static final Finishings STAPLE_DUAL_TOP =
264 new Finishings(29);
265
266 /**
267 * Bind the document(s) with two staples (wire stitches) along the right
268 * edge assuming a portrait document (see above).
269 */
270 public static final Finishings STAPLE_DUAL_RIGHT =
271 new Finishings(30);
272
273 /**
274 * Bind the document(s) with two staples (wire stitches) along the bottom
275 * edge assuming a portrait document (see above).
276 */
277 public static final Finishings STAPLE_DUAL_BOTTOM =
278 new Finishings(31);
279
280 /**
281 * Construct a new finishings binding enumeration value with the given
282 * integer value.
283 *
284 * @param value Integer value
285 */
286 protected Finishings(int value) {
287 super(value);
288 }
289
290 /**
291 * The string table for class {@code Finishings}.
292 */
293 private static final String[] myStringTable =
294 {"none",
295 "staple",
296 null,
297 "cover",
298 "bind",
299 "saddle-stitch",
300 "edge-stitch",
301 null, // The next ten enum values are reserved.
302 null,
303 null,
304 null,
305 null,
306 null,
307 null,
308 null,
309 null,
310 null,
311 "staple-top-left",
312 "staple-bottom-left",
313 "staple-top-right",
314 "staple-bottom-right",
315 "edge-stitch-left",
316 "edge-stitch-top",
317 "edge-stitch-right",
318 "edge-stitch-bottom",
319 "staple-dual-left",
320 "staple-dual-top",
321 "staple-dual-right",
322 "staple-dual-bottom"
323 };
324
325 /**
326 * The enumeration value table for class {@code Finishings}.
327 */
328 private static final Finishings[] myEnumValueTable =
329 {NONE,
330 STAPLE,
331 null,
332 COVER,
333 BIND,
334 SADDLE_STITCH,
335 EDGE_STITCH,
336 null, // The next ten enum values are reserved.
337 null,
338 null,
339 null,
340 null,
341 null,
342 null,
343 null,
344 null,
345 null,
346 STAPLE_TOP_LEFT,
347 STAPLE_BOTTOM_LEFT,
348 STAPLE_TOP_RIGHT,
349 STAPLE_BOTTOM_RIGHT,
350 EDGE_STITCH_LEFT,
351 EDGE_STITCH_TOP,
352 EDGE_STITCH_RIGHT,
353 EDGE_STITCH_BOTTOM,
354 STAPLE_DUAL_LEFT,
355 STAPLE_DUAL_TOP,
356 STAPLE_DUAL_RIGHT,
357 STAPLE_DUAL_BOTTOM
358 };
359
360 /**
361 * Returns the string table for class {@code Finishings}.
362 */
363 protected String[] getStringTable() {
364 return myStringTable.clone();
365 }
366
367 /**
368 * Returns the enumeration value table for class {@code Finishings}.
369 */
370 protected EnumSyntax[] getEnumValueTable() {
371 return (EnumSyntax[])myEnumValueTable.clone();
372 }
373
374 /**
375 * Returns the lowest integer value used by class {@code Finishings}.
376 */
377 protected int getOffset() {
378 return 3;
379 }
380
381 /**
382 * Get the printing attribute class which is to be used as the "category"
383 * for this printing attribute value.
384 * <p>
385 * For class {@code Finishings} and any vendor-defined subclasses, the
386 * category is class {@code Finishings} itself.
387 *
388 * @return printing attribute class (category), an instance of class
389 * {@link Class java.lang.Class}
390 */
391 public final Class<? extends Attribute> getCategory() {
392 return Finishings.class;
393 }
394
395 /**
396 * Get the name of the category of which this attribute value is an
397 * instance.
398 * <p>
399 * For class {@code Finishings} and any vendor-defined subclasses, the
400 * category name is {@code "finishings"}.
401 *
402 * @return attribute category name
403 */
404 public final String getName() {
405 return "finishings";
406 }
407 }