1 /*
2 * Copyright (c) 2000, 2004, 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.SetOfIntegerSyntax;
30 import javax.print.attribute.DocAttribute;
31 import javax.print.attribute.PrintRequestAttribute;
32 import javax.print.attribute.PrintJobAttribute;
33
34 /**
35 * Class PageRanges is a printing attribute class, a set of integers, that
36 * identifies the range(s) of print-stream pages that the Printer object uses
37 * for each copy of each document which are to be printed. Nothing is printed
38 * for any pages identified that do not exist in the document(s). The attribute
39 * is associated with <I>print-stream</I> pages, not application-numbered pages
40 * (for example, the page numbers found in the headers and or footers for
41 * certain word processing applications).
42 * <P>
43 * In most cases, the exact pages to be printed will be generated by a device
44 * driver and this attribute would not be required. However, when printing an
45 * archived document which has already been formatted, the end user may elect to
46 * print just a subset of the pages contained in the document. In this case, if
47 * a page range of <CODE>"<I>n</I>-<I>m</I>"</CODE> is specified, the first page
48 * to be printed will be page <I>n.</I> All subsequent pages of the document
49 * will be printed through and including page <I>m.</I>
50 * <P>
51 * If a PageRanges attribute is not specified for a print job, all pages of
52 * the document will be printed. In other words, the default value for the
53 * PageRanges attribute is always <CODE>{{1, Integer.MAX_VALUE}}</CODE>.
54 * <P>
55 * The effect of a PageRanges attribute on a multidoc print job (a job with
56 * multiple documents) depends on whether all the docs have the same page ranges
57 * specified or whether different docs have different page ranges specified, and
58 * on the (perhaps defaulted) value of the {@link MultipleDocumentHandling
59 * MultipleDocumentHandling} attribute.
60 * <UL>
61 * <LI>
62 * If all the docs have the same page ranges specified, then any value of {@link
63 * MultipleDocumentHandling MultipleDocumentHandling} makes sense, and the
64 * printer's processing depends on the {@link MultipleDocumentHandling
65 * MultipleDocumentHandling} value:
66 * <UL>
67 * <LI>
68 * SINGLE_DOCUMENT -- All the input docs will be combined together into one
69 * output document. The specified page ranges of that output document will be
70 * printed.
71 * <P>
72 * <LI>
73 * SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together
74 * into one output document, and the first impression of each input doc will
75 * always start on a new media sheet. The specified page ranges of that output
76 * document will be printed.
77 * <P>
78 * <LI>
79 * SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, the
80 * specified page ranges will be printed.
81 * <P>
82 * <LI>
83 * SEPARATE_DOCUMENTS_COLLATED_COPIES -- For each separate input doc, the
84 * specified page ranges will be printed.
85 * </UL>
86 * <UL>
87 * <LI>
88 * SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, its own
89 * specified page ranges will be printed..
90 * <P>
91 * <LI>
92 * SEPARATE_DOCUMENTS_COLLATED_COPIES -- For each separate input doc, its own
93 * specified page ranges will be printed..
94 * </UL>
95 * </UL>
96 * <P>
97 * <B>IPP Compatibility:</B> The PageRanges attribute's canonical array form
98 * gives the lower and upper bound for each range of pages to be included in
99 * and IPP "page-ranges" attribute. See class {@link
100 * javax.print.attribute.SetOfIntegerSyntax SetOfIntegerSyntax} for an
101 * explanation of canonical array form. The category name returned by
102 * <CODE>getName()</CODE> gives the IPP attribute name.
103 * <P>
104 *
105 * @author David Mendenhall
106 * @author Alan Kaminsky
107 */
108 public final class PageRanges extends SetOfIntegerSyntax
109 implements DocAttribute, PrintRequestAttribute, PrintJobAttribute {
110
111 private static final long serialVersionUID = 8639895197656148392L;
112
113
114 /**
115 * Construct a new page ranges attribute with the given members. The
116 * members are specified in "array form;" see class {@link
117 * javax.print.attribute.SetOfIntegerSyntax SetOfIntegerSyntax} for an
118 * explanation of array form.
119 *
120 * @param members Set members in array form.
121 *
122 * @exception NullPointerException
123 * (unchecked exception) Thrown if <CODE>members</CODE> is null or
124 * any element of <CODE>members</CODE> is null.
125 * @exception IllegalArgumentException
126 * (unchecked exception) Thrown if any element of
127 * <CODE>members</CODE> is not a length-one or length-two array. Also
128 * thrown if <CODE>members</CODE> is a zero-length array or if any
129 * member of the set is less than 1.
130 */
131 public PageRanges(int[][] members) {
132 super (members);
133 if (members == null) {
134 throw new NullPointerException("members is null");
135 }
136 myPageRanges();
137 }
138 /**
139 * Construct a new page ranges attribute with the given members in
140 * string form.
141 * See class {@link javax.print.attribute.SetOfIntegerSyntax
142 * SetOfIntegerSyntax}
143 * for explanation of the syntax.
144 *
145 * @param members Set members in string form.
146 *
147 * @exception NullPointerException
148 * (unchecked exception) Thrown if <CODE>members</CODE> is null or
149 * any element of <CODE>members</CODE> is null.
150 * @exception IllegalArgumentException
151 * (Unchecked exception) Thrown if <CODE>members</CODE> does not
152 * obey the proper syntax. Also
153 * thrown if the constructed set-of-integer is a
154 * zero-length array or if any
155 * member of the set is less than 1.
156 */
157 public PageRanges(String members) {
158 super(members);
159 if (members == null) {
160 throw new NullPointerException("members is null");
161 }
162 myPageRanges();
163 }
164
165 private void myPageRanges() {
166 int[][] myMembers = getMembers();
167 int n = myMembers.length;
168 if (n == 0) {
169 throw new IllegalArgumentException("members is zero-length");
170 }
171 int i;
172 for (i = 0; i < n; ++ i) {
173 if (myMembers[i][0] < 1) {
174 throw new IllegalArgumentException("Page value < 1 specified");
175 }
176 }
177 }
178
179 /**
180 * Construct a new page ranges attribute containing a single integer. That
181 * is, only the one page is to be printed.
182 *
183 * @param member Set member.
184 *
185 * @exception IllegalArgumentException
186 * (Unchecked exception) Thrown if <CODE>member</CODE> is less than
187 * 1.
188 */
189 public PageRanges(int member) {
190 super (member);
191 if (member < 1) {
192 throw new IllegalArgumentException("Page value < 1 specified");
193 }
194 }
195
196 /**
197 * Construct a new page ranges attribute containing a single range of
198 * integers. That is, only those pages in the one range are to be printed.
199 *
200 * @param lowerBound Lower bound of the range.
201 * @param upperBound Upper bound of the range.
202 *
203 * @exception IllegalArgumentException
204 * (Unchecked exception) Thrown if a null range is specified or if a
205 * non-null range is specified with <CODE>lowerBound</CODE> less than
206 * 1.
207 */
208 public PageRanges(int lowerBound, int upperBound) {
209 super (lowerBound, upperBound);
210 if (lowerBound > upperBound) {
211 throw new IllegalArgumentException("Null range specified");
212 } else if (lowerBound < 1) {
213 throw new IllegalArgumentException("Page value < 1 specified");
214 }
215 }
216
217 /**
218 * Returns whether this page ranges attribute is equivalent to the passed
219 * in object. To be equivalent, all of the following conditions must be
220 * true:
221 * <OL TYPE=1>
222 * <LI>
223 * <CODE>object</CODE> is not null.
224 * <LI>
225 * <CODE>object</CODE> is an instance of class PageRanges.
226 * <LI>
227 * This page ranges attribute's members and <CODE>object</CODE>'s members
228 * are the same.
229 * </OL>
230 *
231 * @param object Object to compare to.
232 *
233 * @return True if <CODE>object</CODE> is equivalent to this page ranges
234 * attribute, false otherwise.
235 */
236 public boolean equals(Object object) {
237 return (super.equals(object) && object instanceof PageRanges);
238 }
239
240 /**
241 * Get the printing attribute class which is to be used as the "category"
242 * for this printing attribute value.
243 * <P>
244 * For class PageRanges, the category is class PageRanges itself.
245 *
246 * @return Printing attribute class (category), an instance of class
247 * {@link java.lang.Class java.lang.Class}.
248 */
249 public final Class<? extends Attribute> getCategory() {
250 return PageRanges.class;
251 }
252
253 /**
254 * Get the name of the category of which this attribute value is an
255 * instance.
256 * <P>
257 * For class PageRanges, the category name is <CODE>"page-ranges"</CODE>.
258 *
259 * @return Attribute category name.
260 */
261 public final String getName() {
262 return "page-ranges";
263 }
264
265 }