+ * Class {@code PageRanges} is a printing attribute class, a set of integers, + * that identifies the range(s) of print-stream pages that the Printer object + * uses for each copy of each document which are to be printed. Nothing is + * printed for any pages identified that do not exist in the document(s). The + * attribute is associated with print-stream pages, not + * application-numbered pages (for example, the page numbers found in the + * headers and or footers for certain word processing applications). + *
* In most cases, the exact pages to be printed will be generated by a device
* driver and this attribute would not be required. However, when printing an
* archived document which has already been formatted, the end user may elect to
* print just a subset of the pages contained in the document. In this case, if
- * a page range of "n-m" is specified, the first page
- * to be printed will be page n. All subsequent pages of the document
- * will be printed through and including page m.
- *
- * If a PageRanges attribute is not specified for a print job, all pages of - * the document will be printed. In other words, the default value for the - * PageRanges attribute is always {@code {{1, Integer.MAX_VALUE}}}. - *
- * The effect of a PageRanges attribute on a multidoc print job (a job with - * multiple documents) depends on whether all the docs have the same page ranges - * specified or whether different docs have different page ranges specified, and - * on the (perhaps defaulted) value of the {@link MultipleDocumentHandling - * MultipleDocumentHandling} attribute. - *
"n-m" is specified, the first page
+ * to be printed will be page n. All subsequent pages of the document
+ * will be printed through and including page m.
+ * + * If a {@code PageRanges} attribute is not specified for a print job, all pages + * of the document will be printed. In other words, the default value for the + * {@code PageRanges} attribute is always {@code {{1, Integer.MAX_VALUE}}}. + *
+ * The effect of a {@code PageRanges} attribute on a multidoc print job (a job + * with multiple documents) depends on whether all the docs have the same page + * ranges specified or whether different docs have different page ranges + * specified, and on the (perhaps defaulted) value of the + * {@link MultipleDocumentHandling MultipleDocumentHandling} attribute. + *
+ * IPP Compatibility: The PageRanges attribute's canonical array form + * gives the lower and upper bound for each range of pages to be included in and + * IPP "page-ranges" attribute. See class + * {@link SetOfIntegerSyntax SetOfIntegerSyntax} for an explanation of canonical + * array form. The category name returned by {@code getName()} gives the IPP + * attribute name. * - *
- * IPP Compatibility: The PageRanges attribute's canonical array form - * gives the lower and upper bound for each range of pages to be included in - * and IPP "page-ranges" attribute. See class {@link - * javax.print.attribute.SetOfIntegerSyntax SetOfIntegerSyntax} for an - * explanation of canonical array form. The category name returned by - * {@code getName()} gives the IPP attribute name. - * - * @author David Mendenhall - * @author Alan Kaminsky + * @author David Mendenhall + * @author Alan Kaminsky */ public final class PageRanges extends SetOfIntegerSyntax implements DocAttribute, PrintRequestAttribute, PrintJobAttribute { + /** + * Use serialVersionUID from JDK 1.4 for interoperability. + */ private static final long serialVersionUID = 8639895197656148392L; - /** - * Construct a new page ranges attribute with the given members. The - * members are specified in "array form;" see class {@link - * javax.print.attribute.SetOfIntegerSyntax SetOfIntegerSyntax} for an - * explanation of array form. - * - * @param members Set members in array form. - * - * @exception NullPointerException - * (unchecked exception) Thrown if {@code members} is null or - * any element of {@code members} is null. - * @exception IllegalArgumentException - * (unchecked exception) Thrown if any element of - * {@code members} is not a length-one or length-two array. Also - * thrown if {@code members} is a zero-length array or if any - * member of the set is less than 1. + * Construct a new page ranges attribute with the given members. The members + * are specified in "array form;" see class + * {@link SetOfIntegerSyntax SetOfIntegerSyntax} for an explanation of array + * form. + * + * @param members set members in array form + * @throws NullPointerException if {@code members} is {@code null} or any + * element of {@code members} is {@code null} + * @throws IllegalArgumentException if any element of {@code members} is not + * a length-one or length-two array. Also if {@code members} is a + * zero-length array or if any member of the set is less than 1. */ public PageRanges(int[][] members) { super (members); @@ -134,24 +121,18 @@ } myPageRanges(); } + /** - * Construct a new page ranges attribute with the given members in - * string form. - * See class {@link javax.print.attribute.SetOfIntegerSyntax - * SetOfIntegerSyntax} - * for explanation of the syntax. - * - * @param members Set members in string form. - * - * @exception NullPointerException - * (unchecked exception) Thrown if {@code members} is null or - * any element of {@code members} is null. - * @exception IllegalArgumentException - * (Unchecked exception) Thrown if {@code members} does not - * obey the proper syntax. Also - * thrown if the constructed set-of-integer is a - * zero-length array or if any - * member of the set is less than 1. + * Construct a new page ranges attribute with the given members in string + * form. See class {@link SetOfIntegerSyntax SetOfIntegerSyntax} for + * explanation of the syntax. + * + * @param members set members in string form + * @throws NullPointerException if {@code members} is {@code null} or any + * element of {@code members} is {@code null} + * @throws IllegalArgumentException if {@code members} does not obey the + * proper syntax. Also if the constructed set-of-integer is a + * zero-length array or if any member of the set is less than 1. */ public PageRanges(String members) { super(members); @@ -161,6 +142,9 @@ myPageRanges(); } + /** + * Validates the page ranges. + */ private void myPageRanges() { int[][] myMembers = getMembers(); int n = myMembers.length; @@ -179,11 +163,8 @@ * Construct a new page ranges attribute containing a single integer. That * is, only the one page is to be printed. * - * @param member Set member. - * - * @exception IllegalArgumentException - * (Unchecked exception) Thrown if {@code member} is less than - * 1. + * @param member set member + * @throws IllegalArgumentException if {@code member < 1} */ public PageRanges(int member) { super (member); @@ -196,13 +177,11 @@ * Construct a new page ranges attribute containing a single range of * integers. That is, only those pages in the one range are to be printed. * - * @param lowerBound Lower bound of the range. - * @param upperBound Upper bound of the range. - * - * @exception IllegalArgumentException - * (Unchecked exception) Thrown if a null range is specified or if a - * non-null range is specified with {@code lowerBound} less than - * 1. + * @param lowerBound lower bound of the range + * @param upperBound upper bound of the range + * @throws IllegalArgumentException if a {@code null} range is specified or + * if a {@code non-null} range is specified with {@code lowerBound} + * less than 1 */ public PageRanges(int lowerBound, int upperBound) { super (lowerBound, upperBound); @@ -214,23 +193,18 @@ } /** - * Returns whether this page ranges attribute is equivalent to the passed - * in object. To be equivalent, all of the following conditions must be - * true: - *
- * For class PageRanges, the category is class PageRanges itself. + *
+ * For class {@code PageRanges}, the category is class + * {@code PageRanges} itself. * - * @return Printing attribute class (category), an instance of class - * {@link java.lang.Class java.lang.Class}. + * @return printing attribute class (category), an instance of class + * {@link Class java.lang.Class} */ public final Class getCategory() { return PageRanges.class; @@ -252,13 +227,12 @@ /** * Get the name of the category of which this attribute value is an * instance. - *
- * For class PageRanges, the category name is {@code "page-ranges"}. + *
+ * For class {@code PageRanges}, the category name is {@code "page-ranges"}. * - * @return Attribute category name. + * @return attribute category name */ public final String getName() { return "page-ranges"; } - }