1 /* 2 * Copyright (c) 2000, 2013, 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 * 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 * 78 * <LI> 79 * SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, the 80 * specified page ranges will be printed. 81 * 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 * 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 * 104 * @author David Mendenhall 105 * @author Alan Kaminsky 106 */ 107 public final class PageRanges extends SetOfIntegerSyntax 108 implements DocAttribute, PrintRequestAttribute, PrintJobAttribute { 109 110 private static final long serialVersionUID = 8639895197656148392L; 111 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 * Construct a new page ranges attribute with the given members in 139 * string form. 140 * See class {@link javax.print.attribute.SetOfIntegerSyntax 141 * SetOfIntegerSyntax} 142 * for explanation of the syntax. 143 * 144 * @param members Set members in string form. 145 * 146 * @exception NullPointerException 147 * (unchecked exception) Thrown if <CODE>members</CODE> is null or 148 * any element of <CODE>members</CODE> is null. 149 * @exception IllegalArgumentException 150 * (Unchecked exception) Thrown if <CODE>members</CODE> does not 151 * obey the proper syntax. Also 152 * thrown if the constructed set-of-integer is a 153 * zero-length array or if any 154 * member of the set is less than 1. 155 */ 156 public PageRanges(String members) { 157 super(members); 158 if (members == null) { 159 throw new NullPointerException("members is null"); 160 } 161 myPageRanges(); 162 } 163 164 private void myPageRanges() { 165 int[][] myMembers = getMembers(); 166 int n = myMembers.length; 167 if (n == 0) { 168 throw new IllegalArgumentException("members is zero-length"); 169 } 170 int i; 171 for (i = 0; i < n; ++ i) { 172 if (myMembers[i][0] < 1) { 173 throw new IllegalArgumentException("Page value < 1 specified"); 174 } 175 } 176 } 177 178 /** 179 * Construct a new page ranges attribute containing a single integer. That 180 * is, only the one page is to be printed. 181 * 182 * @param member Set member. 183 * 184 * @exception IllegalArgumentException 185 * (Unchecked exception) Thrown if <CODE>member</CODE> is less than 186 * 1. 187 */ 188 public PageRanges(int member) { 189 super (member); 190 if (member < 1) { 191 throw new IllegalArgumentException("Page value < 1 specified"); 192 } 193 } 194 195 /** 196 * Construct a new page ranges attribute containing a single range of 197 * integers. That is, only those pages in the one range are to be printed. 198 * 199 * @param lowerBound Lower bound of the range. 200 * @param upperBound Upper bound of the range. 201 * 202 * @exception IllegalArgumentException 203 * (Unchecked exception) Thrown if a null range is specified or if a 204 * non-null range is specified with <CODE>lowerBound</CODE> less than 205 * 1. 206 */ 207 public PageRanges(int lowerBound, int upperBound) { 208 super (lowerBound, upperBound); 209 if (lowerBound > upperBound) { 210 throw new IllegalArgumentException("Null range specified"); 211 } else if (lowerBound < 1) { 212 throw new IllegalArgumentException("Page value < 1 specified"); 213 } 214 } 215 216 /** 217 * Returns whether this page ranges attribute is equivalent to the passed 218 * in object. To be equivalent, all of the following conditions must be 219 * true: 220 * <OL TYPE=1> 221 * <LI> 222 * <CODE>object</CODE> is not null. 223 * <LI> 224 * <CODE>object</CODE> is an instance of class PageRanges. 225 * <LI> 226 * This page ranges attribute's members and <CODE>object</CODE>'s members 227 * are the same. 228 * </OL> 229 * 230 * @param object Object to compare to. 231 * 232 * @return True if <CODE>object</CODE> is equivalent to this page ranges 233 * attribute, false otherwise. 234 */ 235 public boolean equals(Object object) { 236 return (super.equals(object) && object instanceof PageRanges); 237 } 238 239 /** 240 * Get the printing attribute class which is to be used as the "category" 241 * for this printing attribute value. 242 * <P> 243 * For class PageRanges, the category is class PageRanges itself. 244 * 245 * @return Printing attribute class (category), an instance of class 246 * {@link java.lang.Class java.lang.Class}. 247 */ 248 public final Class<? extends Attribute> getCategory() { 249 return PageRanges.class; 250 } 251 252 /** 253 * Get the name of the category of which this attribute value is an 254 * instance. 255 * <P> 256 * For class PageRanges, the category name is <CODE>"page-ranges"</CODE>. 257 * 258 * @return Attribute category name. 259 */ 260 public final String getName() { 261 return "page-ranges"; 262 } 263 264 }