001 /*
002 * Copyright 2000-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.print.attribute.standard;
027
028 import javax.print.attribute.Attribute;
029 import javax.print.attribute.SetOfIntegerSyntax;
030 import javax.print.attribute.DocAttribute;
031 import javax.print.attribute.PrintRequestAttribute;
032 import javax.print.attribute.PrintJobAttribute;
033
034 /**
035 * Class PageRanges is a printing attribute class, a set of integers, that
036 * identifies the range(s) of print-stream pages that the Printer object uses
037 * for each copy of each document which are to be printed. Nothing is printed
038 * for any pages identified that do not exist in the document(s). The attribute
039 * is associated with <I>print-stream</I> pages, not application-numbered pages
040 * (for example, the page numbers found in the headers and or footers for
041 * certain word processing applications).
042 * <P>
043 * In most cases, the exact pages to be printed will be generated by a device
044 * driver and this attribute would not be required. However, when printing an
045 * archived document which has already been formatted, the end user may elect to
046 * print just a subset of the pages contained in the document. In this case, if
047 * a page range of <CODE>"<I>n</I>-<I>m</I>"</CODE> is specified, the first page
048 * to be printed will be page <I>n.</I> All subsequent pages of the document
049 * will be printed through and including page <I>m.</I>
050 * <P>
051 * If a PageRanges attribute is not specified for a print job, all pages of
052 * the document will be printed. In other words, the default value for the
053 * PageRanges attribute is always <CODE>{{1, Integer.MAX_VALUE}}</CODE>.
054 * <P>
055 * The effect of a PageRanges attribute on a multidoc print job (a job with
056 * multiple documents) depends on whether all the docs have the same page ranges
057 * specified or whether different docs have different page ranges specified, and
058 * on the (perhaps defaulted) value of the {@link MultipleDocumentHandling
059 * MultipleDocumentHandling} attribute.
060 * <UL>
061 * <LI>
062 * If all the docs have the same page ranges specified, then any value of {@link
063 * MultipleDocumentHandling MultipleDocumentHandling} makes sense, and the
064 * printer's processing depends on the {@link MultipleDocumentHandling
065 * MultipleDocumentHandling} value:
066 * <UL>
067 * <LI>
068 * SINGLE_DOCUMENT -- All the input docs will be combined together into one
069 * output document. The specified page ranges of that output document will be
070 * printed.
071 * <P>
072 * <LI>
073 * SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together
074 * into one output document, and the first impression of each input doc will
075 * always start on a new media sheet. The specified page ranges of that output
076 * document will be printed.
077 * <P>
078 * <LI>
079 * SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, the
080 * specified page ranges will be printed.
081 * <P>
082 * <LI>
083 * SEPARATE_DOCUMENTS_COLLATED_COPIES -- For each separate input doc, the
084 * specified page ranges will be printed.
085 * </UL>
086 * <UL>
087 * <LI>
088 * SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, its own
089 * specified page ranges will be printed..
090 * <P>
091 * <LI>
092 * SEPARATE_DOCUMENTS_COLLATED_COPIES -- For each separate input doc, its own
093 * specified page ranges will be printed..
094 * </UL>
095 * </UL>
096 * <P>
097 * <B>IPP Compatibility:</B> The PageRanges attribute's canonical array form
098 * gives the lower and upper bound for each range of pages to be included in
099 * 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 implements
109 DocAttribute, PrintRequestAttribute, PrintJobAttribute {
110
111 private static final long serialVersionUID = 8639895197656148392L;
112
113 /**
114 * Construct a new page ranges attribute with the given members. The
115 * members are specified in "array form;" see class {@link
116 * javax.print.attribute.SetOfIntegerSyntax SetOfIntegerSyntax} for an
117 * explanation of array form.
118 *
119 * @param members Set members in array form.
120 *
121 * @exception NullPointerException
122 * (unchecked exception) Thrown if <CODE>members</CODE> is null or
123 * any element of <CODE>members</CODE> is null.
124 * @exception IllegalArgumentException
125 * (unchecked exception) Thrown if any element of
126 * <CODE>members</CODE> is not a length-one or length-two array. Also
127 * thrown if <CODE>members</CODE> is a zero-length array or if any
128 * member of the set is less than 1.
129 */
130 public PageRanges(int[][] members) {
131 super (members);
132 if (members == null) {
133 throw new NullPointerException("members is null");
134 }
135 myPageRanges();
136 }
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(
175 "Page value < 1 specified");
176 }
177 }
178 }
179
180 /**
181 * Construct a new page ranges attribute containing a single integer. That
182 * is, only the one page is to be printed.
183 *
184 * @param member Set member.
185 *
186 * @exception IllegalArgumentException
187 * (Unchecked exception) Thrown if <CODE>member</CODE> is less than
188 * 1.
189 */
190 public PageRanges(int member) {
191 super (member);
192 if (member < 1) {
193 throw new IllegalArgumentException(
194 "Page value < 1 specified");
195 }
196 }
197
198 /**
199 * Construct a new page ranges attribute containing a single range of
200 * integers. That is, only those pages in the one range are to be printed.
201 *
202 * @param lowerBound Lower bound of the range.
203 * @param upperBound Upper bound of the range.
204 *
205 * @exception IllegalArgumentException
206 * (Unchecked exception) Thrown if a null range is specified or if a
207 * non-null range is specified with <CODE>lowerBound</CODE> less than
208 * 1.
209 */
210 public PageRanges(int lowerBound, int upperBound) {
211 super (lowerBound, upperBound);
212 if (lowerBound > upperBound) {
213 throw new IllegalArgumentException("Null range specified");
214 } else if (lowerBound < 1) {
215 throw new IllegalArgumentException(
216 "Page value < 1 specified");
217 }
218 }
219
220 /**
221 * Returns whether this page ranges attribute is equivalent to the passed
222 * in object. To be equivalent, all of the following conditions must be
223 * true:
224 * <OL TYPE=1>
225 * <LI>
226 * <CODE>object</CODE> is not null.
227 * <LI>
228 * <CODE>object</CODE> is an instance of class PageRanges.
229 * <LI>
230 * This page ranges attribute's members and <CODE>object</CODE>'s members
231 * are the same.
232 * </OL>
233 *
234 * @param object Object to compare to.
235 *
236 * @return True if <CODE>object</CODE> is equivalent to this page ranges
237 * attribute, false otherwise.
238 */
239 public boolean equals(Object object) {
240 return (super .equals(object) && object instanceof PageRanges);
241 }
242
243 /**
244 * Get the printing attribute class which is to be used as the "category"
245 * for this printing attribute value.
246 * <P>
247 * For class PageRanges, the category is class PageRanges itself.
248 *
249 * @return Printing attribute class (category), an instance of class
250 * {@link java.lang.Class java.lang.Class}.
251 */
252 public final Class<? extends Attribute> getCategory() {
253 return PageRanges.class;
254 }
255
256 /**
257 * Get the name of the category of which this attribute value is an
258 * instance.
259 * <P>
260 * For class PageRanges, the category name is <CODE>"page-ranges"</CODE>.
261 *
262 * @return Attribute category name.
263 */
264 public final String getName() {
265 return "page-ranges";
266 }
267
268 }
|