55 * Default value fields are not provided.
56 *
57 * @author David Mendenhall
58 * @since 1.3
59 */
60 public final class JobAttributes implements Cloneable {
61 /**
62 * A type-safe enumeration of possible default selection states.
63 * @since 1.3
64 */
65 public static final class DefaultSelectionType extends AttributeValue {
66 private static final int I_ALL = 0;
67 private static final int I_RANGE = 1;
68 private static final int I_SELECTION = 2;
69
70 private static final String NAMES[] = {
71 "all", "range", "selection"
72 };
73
74 /**
75 * The <code>DefaultSelectionType</code> instance to use for
76 * specifying that all pages of the job should be printed.
77 */
78 public static final DefaultSelectionType ALL =
79 new DefaultSelectionType(I_ALL);
80 /**
81 * The <code>DefaultSelectionType</code> instance to use for
82 * specifying that a range of pages of the job should be printed.
83 */
84 public static final DefaultSelectionType RANGE =
85 new DefaultSelectionType(I_RANGE);
86 /**
87 * The <code>DefaultSelectionType</code> instance to use for
88 * specifying that the current selection should be printed.
89 */
90 public static final DefaultSelectionType SELECTION =
91 new DefaultSelectionType(I_SELECTION);
92
93 private DefaultSelectionType(int type) {
94 super(type, NAMES);
95 }
96 }
97
98 /**
99 * A type-safe enumeration of possible job destinations.
100 * @since 1.3
101 */
102 public static final class DestinationType extends AttributeValue {
103 private static final int I_FILE = 0;
104 private static final int I_PRINTER = 1;
105
106 private static final String NAMES[] = {
107 "file", "printer"
108 };
109
110 /**
111 * The <code>DestinationType</code> instance to use for
112 * specifying print to file.
113 */
114 public static final DestinationType FILE =
115 new DestinationType(I_FILE);
116 /**
117 * The <code>DestinationType</code> instance to use for
118 * specifying print to printer.
119 */
120 public static final DestinationType PRINTER =
121 new DestinationType(I_PRINTER);
122
123 private DestinationType(int type) {
124 super(type, NAMES);
125 }
126 }
127
128 /**
129 * A type-safe enumeration of possible dialogs to display to the user.
130 * @since 1.3
131 */
132 public static final class DialogType extends AttributeValue {
133 private static final int I_COMMON = 0;
134 private static final int I_NATIVE = 1;
135 private static final int I_NONE = 2;
136
137 private static final String NAMES[] = {
138 "common", "native", "none"
139 };
140
141 /**
142 * The <code>DialogType</code> instance to use for
143 * specifying the cross-platform, pure Java print dialog.
144 */
145 public static final DialogType COMMON = new DialogType(I_COMMON);
146 /**
147 * The <code>DialogType</code> instance to use for
148 * specifying the platform's native print dialog.
149 */
150 public static final DialogType NATIVE = new DialogType(I_NATIVE);
151 /**
152 * The <code>DialogType</code> instance to use for
153 * specifying no print dialog.
154 */
155 public static final DialogType NONE = new DialogType(I_NONE);
156
157 private DialogType(int type) {
158 super(type, NAMES);
159 }
160 }
161
162 /**
163 * A type-safe enumeration of possible multiple copy handling states.
164 * It is used to control how the sheets of multiple copies of a single
165 * document are collated.
166 * @since 1.3
167 */
168 public static final class MultipleDocumentHandlingType extends
169 AttributeValue {
170 private static final int I_SEPARATE_DOCUMENTS_COLLATED_COPIES = 0;
171 private static final int I_SEPARATE_DOCUMENTS_UNCOLLATED_COPIES = 1;
172
173 private static final String NAMES[] = {
174 "separate-documents-collated-copies",
175 "separate-documents-uncollated-copies"
176 };
177
178 /**
179 * The <code>MultipleDocumentHandlingType</code> instance to use for specifying
180 * that the job should be divided into separate, collated copies.
181 */
182 public static final MultipleDocumentHandlingType
183 SEPARATE_DOCUMENTS_COLLATED_COPIES =
184 new MultipleDocumentHandlingType(
185 I_SEPARATE_DOCUMENTS_COLLATED_COPIES);
186 /**
187 * The <code>MultipleDocumentHandlingType</code> instance to use for specifying
188 * that the job should be divided into separate, uncollated copies.
189 */
190 public static final MultipleDocumentHandlingType
191 SEPARATE_DOCUMENTS_UNCOLLATED_COPIES =
192 new MultipleDocumentHandlingType(
193 I_SEPARATE_DOCUMENTS_UNCOLLATED_COPIES);
194
195 private MultipleDocumentHandlingType(int type) {
196 super(type, NAMES);
197 }
198 }
199
200 /**
201 * A type-safe enumeration of possible multi-page impositions. These
202 * impositions are in compliance with IPP 1.1.
203 * @since 1.3
204 */
205 public static final class SidesType extends AttributeValue {
206 private static final int I_ONE_SIDED = 0;
207 private static final int I_TWO_SIDED_LONG_EDGE = 1;
208 private static final int I_TWO_SIDED_SHORT_EDGE = 2;
209
210 private static final String NAMES[] = {
211 "one-sided", "two-sided-long-edge", "two-sided-short-edge"
212 };
213
214 /**
215 * The <code>SidesType</code> instance to use for specifying that
216 * consecutive job pages should be printed upon the same side of
217 * consecutive media sheets.
218 */
219 public static final SidesType ONE_SIDED = new SidesType(I_ONE_SIDED);
220 /**
221 * The <code>SidesType</code> instance to use for specifying that
222 * consecutive job pages should be printed upon front and back sides
223 * of consecutive media sheets, such that the orientation of each pair
224 * of pages on the medium would be correct for the reader as if for
225 * binding on the long edge.
226 */
227 public static final SidesType TWO_SIDED_LONG_EDGE =
228 new SidesType(I_TWO_SIDED_LONG_EDGE);
229 /**
230 * The <code>SidesType</code> instance to use for specifying that
231 * consecutive job pages should be printed upon front and back sides
232 * of consecutive media sheets, such that the orientation of each pair
233 * of pages on the medium would be correct for the reader as if for
234 * binding on the short edge.
235 */
236 public static final SidesType TWO_SIDED_SHORT_EDGE =
237 new SidesType(I_TWO_SIDED_SHORT_EDGE);
238
239 private SidesType(int type) {
240 super(type, NAMES);
241 }
242 }
243
244 private int copies;
245 private DefaultSelectionType defaultSelection;
246 private DestinationType destination;
247 private DialogType dialog;
248 private String fileName;
249 private int fromPage;
250 private int maxPage;
251 private int minPage;
252 private MultipleDocumentHandlingType multipleDocumentHandling;
253 private int[][] pageRanges;
254 private int prFirst;
255 private int prLast;
256 private String printer;
257 private SidesType sides;
258 private int toPage;
259
260 /**
261 * Constructs a <code>JobAttributes</code> instance with default
262 * values for every attribute. The dialog defaults to
263 * <code>DialogType.NATIVE</code>. Min page defaults to
264 * <code>1</code>. Max page defaults to <code>Integer.MAX_VALUE</code>.
265 * Destination defaults to <code>DestinationType.PRINTER</code>.
266 * Selection defaults to <code>DefaultSelectionType.ALL</code>.
267 * Number of copies defaults to <code>1</code>. Multiple document handling defaults
268 * to <code>MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES</code>.
269 * Sides defaults to <code>SidesType.ONE_SIDED</code>. File name defaults
270 * to <code>null</code>.
271 */
272 public JobAttributes() {
273 setCopiesToDefault();
274 setDefaultSelection(DefaultSelectionType.ALL);
275 setDestination(DestinationType.PRINTER);
276 setDialog(DialogType.NATIVE);
277 setMaxPage(Integer.MAX_VALUE);
278 setMinPage(1);
279 setMultipleDocumentHandlingToDefault();
280 setSidesToDefault();
281 }
282
283 /**
284 * Constructs a <code>JobAttributes</code> instance which is a copy
285 * of the supplied <code>JobAttributes</code>.
286 *
287 * @param obj the <code>JobAttributes</code> to copy
288 */
289 public JobAttributes(JobAttributes obj) {
290 set(obj);
291 }
292
293 /**
294 * Constructs a <code>JobAttributes</code> instance with the
295 * specified values for every attribute.
296 *
297 * @param copies an integer greater than 0
298 * @param defaultSelection <code>DefaultSelectionType.ALL</code>,
299 * <code>DefaultSelectionType.RANGE</code>, or
300 * <code>DefaultSelectionType.SELECTION</code>
301 * @param destination <code>DestinationType.FILE</code> or
302 * <code>DestinationType.PRINTER</code>
303 * @param dialog <code>DialogType.COMMON</code>,
304 * <code>DialogType.NATIVE</code>, or
305 * <code>DialogType.NONE</code>
306 * @param fileName the possibly <code>null</code> file name
307 * @param maxPage an integer greater than zero and greater than or equal
308 * to <i>minPage</i>
309 * @param minPage an integer greater than zero and less than or equal
310 * to <i>maxPage</i>
311 * @param multipleDocumentHandling
312 * <code>MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_COLLATED_COPIES</code> or
313 * <code>MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES</code>
314 * @param pageRanges an array of integer arrays of two elements; an array
315 * is interpreted as a range spanning all pages including and
316 * between the specified pages; ranges must be in ascending
317 * order and must not overlap; specified page numbers cannot be
318 * less than <i>minPage</i> nor greater than <i>maxPage</i>;
319 * for example:
320 * <pre>
321 * (new int[][] { new int[] { 1, 3 }, new int[] { 5, 5 },
322 * new int[] { 15, 19 } }),
323 * </pre>
324 * specifies pages 1, 2, 3, 5, 15, 16, 17, 18, and 19. Note that
325 * (<code>new int[][] { new int[] { 1, 1 }, new int[] { 1, 2 } }</code>),
326 * is an invalid set of page ranges because the two ranges
327 * overlap
328 * @param printer the possibly <code>null</code> printer name
329 * @param sides <code>SidesType.ONE_SIDED</code>,
330 * <code>SidesType.TWO_SIDED_LONG_EDGE</code>, or
331 * <code>SidesType.TWO_SIDED_SHORT_EDGE</code>
332 * @throws IllegalArgumentException if one or more of the above
333 * conditions is violated
334 */
335 public JobAttributes(int copies, DefaultSelectionType defaultSelection,
336 DestinationType destination, DialogType dialog,
337 String fileName, int maxPage, int minPage,
338 MultipleDocumentHandlingType multipleDocumentHandling,
339 int[][] pageRanges, String printer, SidesType sides) {
340 setCopies(copies);
341 setDefaultSelection(defaultSelection);
342 setDestination(destination);
343 setDialog(dialog);
344 setFileName(fileName);
345 setMaxPage(maxPage);
346 setMinPage(minPage);
347 setMultipleDocumentHandling(multipleDocumentHandling);
348 setPageRanges(pageRanges);
349 setPrinter(printer);
350 setSides(sides);
351 }
352
353 /**
354 * Creates and returns a copy of this <code>JobAttributes</code>.
355 *
356 * @return the newly created copy; it is safe to cast this Object into
357 * a <code>JobAttributes</code>
358 */
359 public Object clone() {
360 try {
361 return super.clone();
362 } catch (CloneNotSupportedException e) {
363 // Since we implement Cloneable, this should never happen
364 throw new InternalError(e);
365 }
366 }
367
368 /**
369 * Sets all of the attributes of this <code>JobAttributes</code> to
370 * the same values as the attributes of obj.
371 *
372 * @param obj the <code>JobAttributes</code> to copy
373 */
374 public void set(JobAttributes obj) {
375 copies = obj.copies;
376 defaultSelection = obj.defaultSelection;
377 destination = obj.destination;
378 dialog = obj.dialog;
379 fileName = obj.fileName;
380 fromPage = obj.fromPage;
381 maxPage = obj.maxPage;
382 minPage = obj.minPage;
383 multipleDocumentHandling = obj.multipleDocumentHandling;
384 // okay because we never modify the contents of pageRanges
385 pageRanges = obj.pageRanges;
386 prFirst = obj.prFirst;
387 prLast = obj.prLast;
388 printer = obj.printer;
389 sides = obj.sides;
390 toPage = obj.toPage;
391 }
392
393 /**
394 * Returns the number of copies the application should render for jobs
395 * using these attributes. This attribute is updated to the value chosen
396 * by the user.
397 *
398 * @return an integer greater than 0.
399 */
400 public int getCopies() {
401 return copies;
402 }
403
404 /**
405 * Specifies the number of copies the application should render for jobs
406 * using these attributes. Not specifying this attribute is equivalent to
407 * specifying <code>1</code>.
408 *
409 * @param copies an integer greater than 0
410 * @throws IllegalArgumentException if <code>copies</code> is less than
411 * or equal to 0
412 */
413 public void setCopies(int copies) {
414 if (copies <= 0) {
415 throw new IllegalArgumentException("Invalid value for attribute "+
416 "copies");
417 }
418 this.copies = copies;
419 }
420
421 /**
422 * Sets the number of copies the application should render for jobs using
423 * these attributes to the default. The default number of copies is 1.
424 */
425 public void setCopiesToDefault() {
426 setCopies(1);
427 }
428
429 /**
430 * Specifies whether, for jobs using these attributes, the application
431 * should print all pages, the range specified by the return value of
432 * <code>getPageRanges</code>, or the current selection. This attribute
433 * is updated to the value chosen by the user.
434 *
435 * @return DefaultSelectionType.ALL, DefaultSelectionType.RANGE, or
436 * DefaultSelectionType.SELECTION
437 */
438 public DefaultSelectionType getDefaultSelection() {
439 return defaultSelection;
440 }
441
442 /**
443 * Specifies whether, for jobs using these attributes, the application
444 * should print all pages, the range specified by the return value of
445 * <code>getPageRanges</code>, or the current selection. Not specifying
446 * this attribute is equivalent to specifying DefaultSelectionType.ALL.
447 *
448 * @param defaultSelection DefaultSelectionType.ALL,
449 * DefaultSelectionType.RANGE, or DefaultSelectionType.SELECTION.
450 * @throws IllegalArgumentException if defaultSelection is <code>null</code>
451 */
452 public void setDefaultSelection(DefaultSelectionType defaultSelection) {
453 if (defaultSelection == null) {
454 throw new IllegalArgumentException("Invalid value for attribute "+
455 "defaultSelection");
456 }
457 this.defaultSelection = defaultSelection;
458 }
459
460 /**
461 * Specifies whether output will be to a printer or a file for jobs using
462 * these attributes. This attribute is updated to the value chosen by the
463 * user.
464 *
465 * @return DestinationType.FILE or DestinationType.PRINTER
466 */
467 public DestinationType getDestination() {
468 return destination;
469 }
470
478 */
479 public void setDestination(DestinationType destination) {
480 if (destination == null) {
481 throw new IllegalArgumentException("Invalid value for attribute "+
482 "destination");
483 }
484 this.destination = destination;
485 }
486
487 /**
488 * Returns whether, for jobs using these attributes, the user should see
489 * a print dialog in which to modify the print settings, and which type of
490 * print dialog should be displayed. DialogType.COMMON denotes a cross-
491 * platform, pure Java print dialog. DialogType.NATIVE denotes the
492 * platform's native print dialog. If a platform does not support a native
493 * print dialog, the pure Java print dialog is displayed instead.
494 * DialogType.NONE specifies no print dialog (i.e., background printing).
495 * This attribute cannot be modified by, and is not subject to any
496 * limitations of, the implementation or the target printer.
497 *
498 * @return <code>DialogType.COMMON</code>, <code>DialogType.NATIVE</code>, or
499 * <code>DialogType.NONE</code>
500 */
501 public DialogType getDialog() {
502 return dialog;
503 }
504
505 /**
506 * Specifies whether, for jobs using these attributes, the user should see
507 * a print dialog in which to modify the print settings, and which type of
508 * print dialog should be displayed. DialogType.COMMON denotes a cross-
509 * platform, pure Java print dialog. DialogType.NATIVE denotes the
510 * platform's native print dialog. If a platform does not support a native
511 * print dialog, the pure Java print dialog is displayed instead.
512 * DialogType.NONE specifies no print dialog (i.e., background printing).
513 * Not specifying this attribute is equivalent to specifying
514 * DialogType.NATIVE.
515 *
516 * @param dialog DialogType.COMMON, DialogType.NATIVE, or
517 * DialogType.NONE.
518 * @throws IllegalArgumentException if dialog is null.
519 */
520 public void setDialog(DialogType dialog) {
521 if (dialog == null) {
522 throw new IllegalArgumentException("Invalid value for attribute "+
523 "dialog");
524 }
525 this.dialog = dialog;
526 }
527
528 /**
529 * Specifies the file name for the output file for jobs using these
530 * attributes. This attribute is updated to the value chosen by the user.
531 *
532 * @return the possibly <code>null</code> file name
533 */
534 public String getFileName() {
535 return fileName;
536 }
537
538 /**
539 * Specifies the file name for the output file for jobs using these
540 * attributes. Default is platform-dependent and implementation-defined.
541 *
542 * @param fileName the possibly null file name.
543 */
544 public void setFileName(String fileName) {
545 this.fileName = fileName;
546 }
547
548 /**
549 * Returns, for jobs using these attributes, the first page to be
550 * printed, if a range of pages is to be printed. This attribute is
551 * updated to the value chosen by the user. An application should ignore
552 * this attribute on output, unless the return value of the <code>
553 * getDefaultSelection</code> method is DefaultSelectionType.RANGE. An
554 * application should honor the return value of <code>getPageRanges</code>
555 * over the return value of this method, if possible.
556 *
557 * @return an integer greater than zero and less than or equal to
558 * <i>toPage</i> and greater than or equal to <i>minPage</i> and
559 * less than or equal to <i>maxPage</i>.
560 */
561 public int getFromPage() {
562 if (fromPage != 0) {
563 return fromPage;
564 } else if (toPage != 0) {
565 return getMinPage();
566 } else if (pageRanges != null) {
567 return prFirst;
568 } else {
569 return getMinPage();
570 }
571 }
572
573 /**
574 * Specifies, for jobs using these attributes, the first page to be
595 }
596 this.fromPage = fromPage;
597 }
598
599 /**
600 * Specifies the maximum value the user can specify as the last page to
601 * be printed for jobs using these attributes. This attribute cannot be
602 * modified by, and is not subject to any limitations of, the
603 * implementation or the target printer.
604 *
605 * @return an integer greater than zero and greater than or equal
606 * to <i>minPage</i>.
607 */
608 public int getMaxPage() {
609 return maxPage;
610 }
611
612 /**
613 * Specifies the maximum value the user can specify as the last page to
614 * be printed for jobs using these attributes. Not specifying this
615 * attribute is equivalent to specifying <code>Integer.MAX_VALUE</code>.
616 *
617 * @param maxPage an integer greater than zero and greater than or equal
618 * to <i>minPage</i>
619 * @throws IllegalArgumentException if one or more of the above
620 * conditions is violated
621 */
622 public void setMaxPage(int maxPage) {
623 if (maxPage <= 0 || maxPage < minPage) {
624 throw new IllegalArgumentException("Invalid value for attribute "+
625 "maxPage");
626 }
627 this.maxPage = maxPage;
628 }
629
630 /**
631 * Specifies the minimum value the user can specify as the first page to
632 * be printed for jobs using these attributes. This attribute cannot be
633 * modified by, and is not subject to any limitations of, the
634 * implementation or the target printer.
635 *
636 * @return an integer greater than zero and less than or equal
637 * to <i>maxPage</i>.
638 */
639 public int getMinPage() {
640 return minPage;
641 }
642
643 /**
644 * Specifies the minimum value the user can specify as the first page to
645 * be printed for jobs using these attributes. Not specifying this
646 * attribute is equivalent to specifying <code>1</code>.
647 *
648 * @param minPage an integer greater than zero and less than or equal
649 * to <i>maxPage</i>.
650 * @throws IllegalArgumentException if one or more of the above
651 * conditions is violated.
652 */
653 public void setMinPage(int minPage) {
654 if (minPage <= 0 || minPage > maxPage) {
655 throw new IllegalArgumentException("Invalid value for attribute "+
656 "minPage");
657 }
658 this.minPage = minPage;
659 }
660
661 /**
662 * Specifies the handling of multiple copies, including collation, for
663 * jobs using these attributes. This attribute is updated to the value
664 * chosen by the user.
665 *
666 * @return
689 "multipleDocumentHandling");
690 }
691 this.multipleDocumentHandling = multipleDocumentHandling;
692 }
693
694 /**
695 * Sets the handling of multiple copies, including collation, for jobs
696 * using these attributes to the default. The default handling is
697 * MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES.
698 */
699 public void setMultipleDocumentHandlingToDefault() {
700 setMultipleDocumentHandling(
701 MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES);
702 }
703
704 /**
705 * Specifies, for jobs using these attributes, the ranges of pages to be
706 * printed, if a range of pages is to be printed. All range numbers are
707 * inclusive. This attribute is updated to the value chosen by the user.
708 * An application should ignore this attribute on output, unless the
709 * return value of the <code>getDefaultSelection</code> method is
710 * DefaultSelectionType.RANGE.
711 *
712 * @return an array of integer arrays of 2 elements. An array
713 * is interpreted as a range spanning all pages including and
714 * between the specified pages. Ranges must be in ascending
715 * order and must not overlap. Specified page numbers cannot be
716 * less than <i>minPage</i> nor greater than <i>maxPage</i>.
717 * For example:
718 * (new int[][] { new int[] { 1, 3 }, new int[] { 5, 5 },
719 * new int[] { 15, 19 } }),
720 * specifies pages 1, 2, 3, 5, 15, 16, 17, 18, and 19.
721 */
722 public int[][] getPageRanges() {
723 if (pageRanges != null) {
724 // Return a copy because otherwise client code could circumvent the
725 // the checks made in setPageRanges by modifying the returned
726 // array.
727 int[][] copy = new int[pageRanges.length][2];
728 for (int i = 0; i < pageRanges.length; i++) {
729 copy[i][0] = pageRanges[i][0];
871 if (sides == null) {
872 throw new IllegalArgumentException("Invalid value for attribute "+
873 "sides");
874 }
875 this.sides = sides;
876 }
877
878 /**
879 * Sets how consecutive pages should be imposed upon the sides of the
880 * print medium for jobs using these attributes to the default. The
881 * default imposition is SidesType.ONE_SIDED.
882 */
883 public void setSidesToDefault() {
884 setSides(SidesType.ONE_SIDED);
885 }
886
887 /**
888 * Returns, for jobs using these attributes, the last page (inclusive)
889 * to be printed, if a range of pages is to be printed. This attribute is
890 * updated to the value chosen by the user. An application should ignore
891 * this attribute on output, unless the return value of the <code>
892 * getDefaultSelection</code> method is DefaultSelectionType.RANGE. An
893 * application should honor the return value of <code>getPageRanges</code>
894 * over the return value of this method, if possible.
895 *
896 * @return an integer greater than zero and greater than or equal
897 * to <i>toPage</i> and greater than or equal to <i>minPage</i>
898 * and less than or equal to <i>maxPage</i>.
899 */
900 public int getToPage() {
901 if (toPage != 0) {
902 return toPage;
903 } else if (fromPage != 0) {
904 return fromPage;
905 } else if (pageRanges != null) {
906 return prLast;
907 } else {
908 return getMinPage();
909 }
910 }
911
912 /**
913 * Specifies, for jobs using these attributes, the last page (inclusive)
|
55 * Default value fields are not provided.
56 *
57 * @author David Mendenhall
58 * @since 1.3
59 */
60 public final class JobAttributes implements Cloneable {
61 /**
62 * A type-safe enumeration of possible default selection states.
63 * @since 1.3
64 */
65 public static final class DefaultSelectionType extends AttributeValue {
66 private static final int I_ALL = 0;
67 private static final int I_RANGE = 1;
68 private static final int I_SELECTION = 2;
69
70 private static final String NAMES[] = {
71 "all", "range", "selection"
72 };
73
74 /**
75 * The {@code DefaultSelectionType} instance to use for
76 * specifying that all pages of the job should be printed.
77 */
78 public static final DefaultSelectionType ALL =
79 new DefaultSelectionType(I_ALL);
80 /**
81 * The {@code DefaultSelectionType} instance to use for
82 * specifying that a range of pages of the job should be printed.
83 */
84 public static final DefaultSelectionType RANGE =
85 new DefaultSelectionType(I_RANGE);
86 /**
87 * The {@code DefaultSelectionType} instance to use for
88 * specifying that the current selection should be printed.
89 */
90 public static final DefaultSelectionType SELECTION =
91 new DefaultSelectionType(I_SELECTION);
92
93 private DefaultSelectionType(int type) {
94 super(type, NAMES);
95 }
96 }
97
98 /**
99 * A type-safe enumeration of possible job destinations.
100 * @since 1.3
101 */
102 public static final class DestinationType extends AttributeValue {
103 private static final int I_FILE = 0;
104 private static final int I_PRINTER = 1;
105
106 private static final String NAMES[] = {
107 "file", "printer"
108 };
109
110 /**
111 * The {@code DestinationType} instance to use for
112 * specifying print to file.
113 */
114 public static final DestinationType FILE =
115 new DestinationType(I_FILE);
116 /**
117 * The {@code DestinationType} instance to use for
118 * specifying print to printer.
119 */
120 public static final DestinationType PRINTER =
121 new DestinationType(I_PRINTER);
122
123 private DestinationType(int type) {
124 super(type, NAMES);
125 }
126 }
127
128 /**
129 * A type-safe enumeration of possible dialogs to display to the user.
130 * @since 1.3
131 */
132 public static final class DialogType extends AttributeValue {
133 private static final int I_COMMON = 0;
134 private static final int I_NATIVE = 1;
135 private static final int I_NONE = 2;
136
137 private static final String NAMES[] = {
138 "common", "native", "none"
139 };
140
141 /**
142 * The {@code DialogType} instance to use for
143 * specifying the cross-platform, pure Java print dialog.
144 */
145 public static final DialogType COMMON = new DialogType(I_COMMON);
146 /**
147 * The {@code DialogType} instance to use for
148 * specifying the platform's native print dialog.
149 */
150 public static final DialogType NATIVE = new DialogType(I_NATIVE);
151 /**
152 * The {@code DialogType} instance to use for
153 * specifying no print dialog.
154 */
155 public static final DialogType NONE = new DialogType(I_NONE);
156
157 private DialogType(int type) {
158 super(type, NAMES);
159 }
160 }
161
162 /**
163 * A type-safe enumeration of possible multiple copy handling states.
164 * It is used to control how the sheets of multiple copies of a single
165 * document are collated.
166 * @since 1.3
167 */
168 public static final class MultipleDocumentHandlingType extends
169 AttributeValue {
170 private static final int I_SEPARATE_DOCUMENTS_COLLATED_COPIES = 0;
171 private static final int I_SEPARATE_DOCUMENTS_UNCOLLATED_COPIES = 1;
172
173 private static final String NAMES[] = {
174 "separate-documents-collated-copies",
175 "separate-documents-uncollated-copies"
176 };
177
178 /**
179 * The {@code MultipleDocumentHandlingType} instance to use for specifying
180 * that the job should be divided into separate, collated copies.
181 */
182 public static final MultipleDocumentHandlingType
183 SEPARATE_DOCUMENTS_COLLATED_COPIES =
184 new MultipleDocumentHandlingType(
185 I_SEPARATE_DOCUMENTS_COLLATED_COPIES);
186 /**
187 * The {@code MultipleDocumentHandlingType} instance to use for specifying
188 * that the job should be divided into separate, uncollated copies.
189 */
190 public static final MultipleDocumentHandlingType
191 SEPARATE_DOCUMENTS_UNCOLLATED_COPIES =
192 new MultipleDocumentHandlingType(
193 I_SEPARATE_DOCUMENTS_UNCOLLATED_COPIES);
194
195 private MultipleDocumentHandlingType(int type) {
196 super(type, NAMES);
197 }
198 }
199
200 /**
201 * A type-safe enumeration of possible multi-page impositions. These
202 * impositions are in compliance with IPP 1.1.
203 * @since 1.3
204 */
205 public static final class SidesType extends AttributeValue {
206 private static final int I_ONE_SIDED = 0;
207 private static final int I_TWO_SIDED_LONG_EDGE = 1;
208 private static final int I_TWO_SIDED_SHORT_EDGE = 2;
209
210 private static final String NAMES[] = {
211 "one-sided", "two-sided-long-edge", "two-sided-short-edge"
212 };
213
214 /**
215 * The {@code SidesType} instance to use for specifying that
216 * consecutive job pages should be printed upon the same side of
217 * consecutive media sheets.
218 */
219 public static final SidesType ONE_SIDED = new SidesType(I_ONE_SIDED);
220 /**
221 * The {@code SidesType} instance to use for specifying that
222 * consecutive job pages should be printed upon front and back sides
223 * of consecutive media sheets, such that the orientation of each pair
224 * of pages on the medium would be correct for the reader as if for
225 * binding on the long edge.
226 */
227 public static final SidesType TWO_SIDED_LONG_EDGE =
228 new SidesType(I_TWO_SIDED_LONG_EDGE);
229 /**
230 * The {@code SidesType} instance to use for specifying that
231 * consecutive job pages should be printed upon front and back sides
232 * of consecutive media sheets, such that the orientation of each pair
233 * of pages on the medium would be correct for the reader as if for
234 * binding on the short edge.
235 */
236 public static final SidesType TWO_SIDED_SHORT_EDGE =
237 new SidesType(I_TWO_SIDED_SHORT_EDGE);
238
239 private SidesType(int type) {
240 super(type, NAMES);
241 }
242 }
243
244 private int copies;
245 private DefaultSelectionType defaultSelection;
246 private DestinationType destination;
247 private DialogType dialog;
248 private String fileName;
249 private int fromPage;
250 private int maxPage;
251 private int minPage;
252 private MultipleDocumentHandlingType multipleDocumentHandling;
253 private int[][] pageRanges;
254 private int prFirst;
255 private int prLast;
256 private String printer;
257 private SidesType sides;
258 private int toPage;
259
260 /**
261 * Constructs a {@code JobAttributes} instance with default
262 * values for every attribute. The dialog defaults to
263 * {@code DialogType.NATIVE}. Min page defaults to
264 * {@code 1}. Max page defaults to {@code Integer.MAX_VALUE}.
265 * Destination defaults to {@code DestinationType.PRINTER}.
266 * Selection defaults to {@code DefaultSelectionType.ALL}.
267 * Number of copies defaults to {@code 1}. Multiple document handling defaults
268 * to {@code MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES}.
269 * Sides defaults to {@code SidesType.ONE_SIDED}. File name defaults
270 * to {@code null}.
271 */
272 public JobAttributes() {
273 setCopiesToDefault();
274 setDefaultSelection(DefaultSelectionType.ALL);
275 setDestination(DestinationType.PRINTER);
276 setDialog(DialogType.NATIVE);
277 setMaxPage(Integer.MAX_VALUE);
278 setMinPage(1);
279 setMultipleDocumentHandlingToDefault();
280 setSidesToDefault();
281 }
282
283 /**
284 * Constructs a {@code JobAttributes} instance which is a copy
285 * of the supplied {@code JobAttributes}.
286 *
287 * @param obj the {@code JobAttributes} to copy
288 */
289 public JobAttributes(JobAttributes obj) {
290 set(obj);
291 }
292
293 /**
294 * Constructs a {@code JobAttributes} instance with the
295 * specified values for every attribute.
296 *
297 * @param copies an integer greater than 0
298 * @param defaultSelection {@code DefaultSelectionType.ALL},
299 * {@code DefaultSelectionType.RANGE}, or
300 * {@code DefaultSelectionType.SELECTION}
301 * @param destination {@code DestinationType.FILE} or
302 * {@code DestinationType.PRINTER}
303 * @param dialog {@code DialogType.COMMON},
304 * {@code DialogType.NATIVE}, or
305 * {@code DialogType.NONE}
306 * @param fileName the possibly {@code null} file name
307 * @param maxPage an integer greater than zero and greater than or equal
308 * to <i>minPage</i>
309 * @param minPage an integer greater than zero and less than or equal
310 * to <i>maxPage</i>
311 * @param multipleDocumentHandling
312 * {@code MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_COLLATED_COPIES} or
313 * {@code MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES}
314 * @param pageRanges an array of integer arrays of two elements; an array
315 * is interpreted as a range spanning all pages including and
316 * between the specified pages; ranges must be in ascending
317 * order and must not overlap; specified page numbers cannot be
318 * less than <i>minPage</i> nor greater than <i>maxPage</i>;
319 * for example:
320 * <pre>
321 * (new int[][] { new int[] { 1, 3 }, new int[] { 5, 5 },
322 * new int[] { 15, 19 } }),
323 * </pre>
324 * specifies pages 1, 2, 3, 5, 15, 16, 17, 18, and 19. Note that
325 * ({@code new int[][] { new int[] { 1, 1 }, new int[] { 1, 2 } }}),
326 * is an invalid set of page ranges because the two ranges
327 * overlap
328 * @param printer the possibly {@code null} printer name
329 * @param sides {@code SidesType.ONE_SIDED},
330 * {@code SidesType.TWO_SIDED_LONG_EDGE}, or
331 * {@code SidesType.TWO_SIDED_SHORT_EDGE}
332 * @throws IllegalArgumentException if one or more of the above
333 * conditions is violated
334 */
335 public JobAttributes(int copies, DefaultSelectionType defaultSelection,
336 DestinationType destination, DialogType dialog,
337 String fileName, int maxPage, int minPage,
338 MultipleDocumentHandlingType multipleDocumentHandling,
339 int[][] pageRanges, String printer, SidesType sides) {
340 setCopies(copies);
341 setDefaultSelection(defaultSelection);
342 setDestination(destination);
343 setDialog(dialog);
344 setFileName(fileName);
345 setMaxPage(maxPage);
346 setMinPage(minPage);
347 setMultipleDocumentHandling(multipleDocumentHandling);
348 setPageRanges(pageRanges);
349 setPrinter(printer);
350 setSides(sides);
351 }
352
353 /**
354 * Creates and returns a copy of this {@code JobAttributes}.
355 *
356 * @return the newly created copy; it is safe to cast this Object into
357 * a {@code JobAttributes}
358 */
359 public Object clone() {
360 try {
361 return super.clone();
362 } catch (CloneNotSupportedException e) {
363 // Since we implement Cloneable, this should never happen
364 throw new InternalError(e);
365 }
366 }
367
368 /**
369 * Sets all of the attributes of this {@code JobAttributes} to
370 * the same values as the attributes of obj.
371 *
372 * @param obj the {@code JobAttributes} to copy
373 */
374 public void set(JobAttributes obj) {
375 copies = obj.copies;
376 defaultSelection = obj.defaultSelection;
377 destination = obj.destination;
378 dialog = obj.dialog;
379 fileName = obj.fileName;
380 fromPage = obj.fromPage;
381 maxPage = obj.maxPage;
382 minPage = obj.minPage;
383 multipleDocumentHandling = obj.multipleDocumentHandling;
384 // okay because we never modify the contents of pageRanges
385 pageRanges = obj.pageRanges;
386 prFirst = obj.prFirst;
387 prLast = obj.prLast;
388 printer = obj.printer;
389 sides = obj.sides;
390 toPage = obj.toPage;
391 }
392
393 /**
394 * Returns the number of copies the application should render for jobs
395 * using these attributes. This attribute is updated to the value chosen
396 * by the user.
397 *
398 * @return an integer greater than 0.
399 */
400 public int getCopies() {
401 return copies;
402 }
403
404 /**
405 * Specifies the number of copies the application should render for jobs
406 * using these attributes. Not specifying this attribute is equivalent to
407 * specifying {@code 1}.
408 *
409 * @param copies an integer greater than 0
410 * @throws IllegalArgumentException if {@code copies} is less than
411 * or equal to 0
412 */
413 public void setCopies(int copies) {
414 if (copies <= 0) {
415 throw new IllegalArgumentException("Invalid value for attribute "+
416 "copies");
417 }
418 this.copies = copies;
419 }
420
421 /**
422 * Sets the number of copies the application should render for jobs using
423 * these attributes to the default. The default number of copies is 1.
424 */
425 public void setCopiesToDefault() {
426 setCopies(1);
427 }
428
429 /**
430 * Specifies whether, for jobs using these attributes, the application
431 * should print all pages, the range specified by the return value of
432 * {@code getPageRanges}, or the current selection. This attribute
433 * is updated to the value chosen by the user.
434 *
435 * @return DefaultSelectionType.ALL, DefaultSelectionType.RANGE, or
436 * DefaultSelectionType.SELECTION
437 */
438 public DefaultSelectionType getDefaultSelection() {
439 return defaultSelection;
440 }
441
442 /**
443 * Specifies whether, for jobs using these attributes, the application
444 * should print all pages, the range specified by the return value of
445 * {@code getPageRanges}, or the current selection. Not specifying
446 * this attribute is equivalent to specifying DefaultSelectionType.ALL.
447 *
448 * @param defaultSelection DefaultSelectionType.ALL,
449 * DefaultSelectionType.RANGE, or DefaultSelectionType.SELECTION.
450 * @throws IllegalArgumentException if defaultSelection is {@code null}
451 */
452 public void setDefaultSelection(DefaultSelectionType defaultSelection) {
453 if (defaultSelection == null) {
454 throw new IllegalArgumentException("Invalid value for attribute "+
455 "defaultSelection");
456 }
457 this.defaultSelection = defaultSelection;
458 }
459
460 /**
461 * Specifies whether output will be to a printer or a file for jobs using
462 * these attributes. This attribute is updated to the value chosen by the
463 * user.
464 *
465 * @return DestinationType.FILE or DestinationType.PRINTER
466 */
467 public DestinationType getDestination() {
468 return destination;
469 }
470
478 */
479 public void setDestination(DestinationType destination) {
480 if (destination == null) {
481 throw new IllegalArgumentException("Invalid value for attribute "+
482 "destination");
483 }
484 this.destination = destination;
485 }
486
487 /**
488 * Returns whether, for jobs using these attributes, the user should see
489 * a print dialog in which to modify the print settings, and which type of
490 * print dialog should be displayed. DialogType.COMMON denotes a cross-
491 * platform, pure Java print dialog. DialogType.NATIVE denotes the
492 * platform's native print dialog. If a platform does not support a native
493 * print dialog, the pure Java print dialog is displayed instead.
494 * DialogType.NONE specifies no print dialog (i.e., background printing).
495 * This attribute cannot be modified by, and is not subject to any
496 * limitations of, the implementation or the target printer.
497 *
498 * @return {@code DialogType.COMMON}, {@code DialogType.NATIVE}, or
499 * {@code DialogType.NONE}
500 */
501 public DialogType getDialog() {
502 return dialog;
503 }
504
505 /**
506 * Specifies whether, for jobs using these attributes, the user should see
507 * a print dialog in which to modify the print settings, and which type of
508 * print dialog should be displayed. DialogType.COMMON denotes a cross-
509 * platform, pure Java print dialog. DialogType.NATIVE denotes the
510 * platform's native print dialog. If a platform does not support a native
511 * print dialog, the pure Java print dialog is displayed instead.
512 * DialogType.NONE specifies no print dialog (i.e., background printing).
513 * Not specifying this attribute is equivalent to specifying
514 * DialogType.NATIVE.
515 *
516 * @param dialog DialogType.COMMON, DialogType.NATIVE, or
517 * DialogType.NONE.
518 * @throws IllegalArgumentException if dialog is null.
519 */
520 public void setDialog(DialogType dialog) {
521 if (dialog == null) {
522 throw new IllegalArgumentException("Invalid value for attribute "+
523 "dialog");
524 }
525 this.dialog = dialog;
526 }
527
528 /**
529 * Specifies the file name for the output file for jobs using these
530 * attributes. This attribute is updated to the value chosen by the user.
531 *
532 * @return the possibly {@code null} file name
533 */
534 public String getFileName() {
535 return fileName;
536 }
537
538 /**
539 * Specifies the file name for the output file for jobs using these
540 * attributes. Default is platform-dependent and implementation-defined.
541 *
542 * @param fileName the possibly null file name.
543 */
544 public void setFileName(String fileName) {
545 this.fileName = fileName;
546 }
547
548 /**
549 * Returns, for jobs using these attributes, the first page to be
550 * printed, if a range of pages is to be printed. This attribute is
551 * updated to the value chosen by the user. An application should ignore
552 * this attribute on output, unless the return value of the
553 * {@code getDefaultSelection} method is DefaultSelectionType.RANGE. An
554 * application should honor the return value of {@code getPageRanges}
555 * over the return value of this method, if possible.
556 *
557 * @return an integer greater than zero and less than or equal to
558 * <i>toPage</i> and greater than or equal to <i>minPage</i> and
559 * less than or equal to <i>maxPage</i>.
560 */
561 public int getFromPage() {
562 if (fromPage != 0) {
563 return fromPage;
564 } else if (toPage != 0) {
565 return getMinPage();
566 } else if (pageRanges != null) {
567 return prFirst;
568 } else {
569 return getMinPage();
570 }
571 }
572
573 /**
574 * Specifies, for jobs using these attributes, the first page to be
595 }
596 this.fromPage = fromPage;
597 }
598
599 /**
600 * Specifies the maximum value the user can specify as the last page to
601 * be printed for jobs using these attributes. This attribute cannot be
602 * modified by, and is not subject to any limitations of, the
603 * implementation or the target printer.
604 *
605 * @return an integer greater than zero and greater than or equal
606 * to <i>minPage</i>.
607 */
608 public int getMaxPage() {
609 return maxPage;
610 }
611
612 /**
613 * Specifies the maximum value the user can specify as the last page to
614 * be printed for jobs using these attributes. Not specifying this
615 * attribute is equivalent to specifying {@code Integer.MAX_VALUE}.
616 *
617 * @param maxPage an integer greater than zero and greater than or equal
618 * to <i>minPage</i>
619 * @throws IllegalArgumentException if one or more of the above
620 * conditions is violated
621 */
622 public void setMaxPage(int maxPage) {
623 if (maxPage <= 0 || maxPage < minPage) {
624 throw new IllegalArgumentException("Invalid value for attribute "+
625 "maxPage");
626 }
627 this.maxPage = maxPage;
628 }
629
630 /**
631 * Specifies the minimum value the user can specify as the first page to
632 * be printed for jobs using these attributes. This attribute cannot be
633 * modified by, and is not subject to any limitations of, the
634 * implementation or the target printer.
635 *
636 * @return an integer greater than zero and less than or equal
637 * to <i>maxPage</i>.
638 */
639 public int getMinPage() {
640 return minPage;
641 }
642
643 /**
644 * Specifies the minimum value the user can specify as the first page to
645 * be printed for jobs using these attributes. Not specifying this
646 * attribute is equivalent to specifying {@code 1}.
647 *
648 * @param minPage an integer greater than zero and less than or equal
649 * to <i>maxPage</i>.
650 * @throws IllegalArgumentException if one or more of the above
651 * conditions is violated.
652 */
653 public void setMinPage(int minPage) {
654 if (minPage <= 0 || minPage > maxPage) {
655 throw new IllegalArgumentException("Invalid value for attribute "+
656 "minPage");
657 }
658 this.minPage = minPage;
659 }
660
661 /**
662 * Specifies the handling of multiple copies, including collation, for
663 * jobs using these attributes. This attribute is updated to the value
664 * chosen by the user.
665 *
666 * @return
689 "multipleDocumentHandling");
690 }
691 this.multipleDocumentHandling = multipleDocumentHandling;
692 }
693
694 /**
695 * Sets the handling of multiple copies, including collation, for jobs
696 * using these attributes to the default. The default handling is
697 * MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES.
698 */
699 public void setMultipleDocumentHandlingToDefault() {
700 setMultipleDocumentHandling(
701 MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES);
702 }
703
704 /**
705 * Specifies, for jobs using these attributes, the ranges of pages to be
706 * printed, if a range of pages is to be printed. All range numbers are
707 * inclusive. This attribute is updated to the value chosen by the user.
708 * An application should ignore this attribute on output, unless the
709 * return value of the {@code getDefaultSelection} method is
710 * DefaultSelectionType.RANGE.
711 *
712 * @return an array of integer arrays of 2 elements. An array
713 * is interpreted as a range spanning all pages including and
714 * between the specified pages. Ranges must be in ascending
715 * order and must not overlap. Specified page numbers cannot be
716 * less than <i>minPage</i> nor greater than <i>maxPage</i>.
717 * For example:
718 * (new int[][] { new int[] { 1, 3 }, new int[] { 5, 5 },
719 * new int[] { 15, 19 } }),
720 * specifies pages 1, 2, 3, 5, 15, 16, 17, 18, and 19.
721 */
722 public int[][] getPageRanges() {
723 if (pageRanges != null) {
724 // Return a copy because otherwise client code could circumvent the
725 // the checks made in setPageRanges by modifying the returned
726 // array.
727 int[][] copy = new int[pageRanges.length][2];
728 for (int i = 0; i < pageRanges.length; i++) {
729 copy[i][0] = pageRanges[i][0];
871 if (sides == null) {
872 throw new IllegalArgumentException("Invalid value for attribute "+
873 "sides");
874 }
875 this.sides = sides;
876 }
877
878 /**
879 * Sets how consecutive pages should be imposed upon the sides of the
880 * print medium for jobs using these attributes to the default. The
881 * default imposition is SidesType.ONE_SIDED.
882 */
883 public void setSidesToDefault() {
884 setSides(SidesType.ONE_SIDED);
885 }
886
887 /**
888 * Returns, for jobs using these attributes, the last page (inclusive)
889 * to be printed, if a range of pages is to be printed. This attribute is
890 * updated to the value chosen by the user. An application should ignore
891 * this attribute on output, unless the return value of the
892 * {@code getDefaultSelection} method is DefaultSelectionType.RANGE. An
893 * application should honor the return value of {@code getPageRanges}
894 * over the return value of this method, if possible.
895 *
896 * @return an integer greater than zero and greater than or equal
897 * to <i>toPage</i> and greater than or equal to <i>minPage</i>
898 * and less than or equal to <i>maxPage</i>.
899 */
900 public int getToPage() {
901 if (toPage != 0) {
902 return toPage;
903 } else if (fromPage != 0) {
904 return fromPage;
905 } else if (pageRanges != null) {
906 return prLast;
907 } else {
908 return getMinPage();
909 }
910 }
911
912 /**
913 * Specifies, for jobs using these attributes, the last page (inclusive)
|