Java tutorial
/* * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.print.attribute.standard; import javax.print.attribute.Attribute; import javax.print.attribute.DocAttribute; import javax.print.attribute.PrintJobAttribute; import javax.print.attribute.PrintRequestAttribute; import javax.print.attribute.SetOfIntegerSyntax; /** * 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 <i>print-stream</i> pages, not * application-numbered pages (for example, the page numbers found in the * headers and or footers for certain word processing applications). * <p> * 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 <code>"<i>n</i>-<i>m</i>"</code> is specified, the first page * to be printed will be page <i>n.</i> All subsequent pages of the document * will be printed through and including page <i>m.</i> * <p> * 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}}}. * <p> * 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. * <ul> * <li>If all the docs have the same page ranges specified, then any value of * {@link MultipleDocumentHandling MultipleDocumentHandling} makes sense, and * the printer's processing depends on the * {@link MultipleDocumentHandling MultipleDocumentHandling} value: * <ul> * <li>{@code SINGLE_DOCUMENT} -- All the input docs will be combined * together into one output document. The specified page ranges of that * output document will be printed. * <li>{@code SINGLE_DOCUMENT_NEW_SHEET} -- All the input docs will be * combined together into one output document, and the first impression of * each input doc will always start on a new media sheet. The specified page * ranges of that output document will be printed. * <li>{@code SEPARATE_DOCUMENTS_UNCOLLATED_COPIES} -- For each separate * input doc, the specified page ranges will be printed. * <li>{@code SEPARATE_DOCUMENTS_COLLATED_COPIES} -- For each separate input * doc, the specified page ranges will be printed. * </ul> * <ul> * <li>{@code SEPARATE_DOCUMENTS_UNCOLLATED_COPIES} -- For each separate * input doc, its own specified page ranges will be printed. * <li>{@code SEPARATE_DOCUMENTS_COLLATED_COPIES} -- For each separate input * doc, its own specified page ranges will be printed. * </ul> * </ul> * <p> * <b>IPP Compatibility:</b> 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. * * @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 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); if (members == null) { throw new NullPointerException("members is null"); } myPageRanges(); } /** * 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); if (members == null) { throw new NullPointerException("members is null"); } myPageRanges(); } /** * Validates the page ranges. */ private void myPageRanges() { int[][] myMembers = getMembers(); int n = myMembers.length; if (n == 0) { throw new IllegalArgumentException("members is zero-length"); } int i; for (i = 0; i < n; ++i) { if (myMembers[i][0] < 1) { throw new IllegalArgumentException("Page value < 1 specified"); } } } /** * Construct a new page ranges attribute containing a single integer. That * is, only the one page is to be printed. * * @param member set member * @throws IllegalArgumentException if {@code member < 1} */ public PageRanges(int member) { super(member); if (member < 1) { throw new IllegalArgumentException("Page value < 1 specified"); } } /** * 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 * @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); if (lowerBound > upperBound) { throw new IllegalArgumentException("Null range specified"); } else if (lowerBound < 1) { throw new IllegalArgumentException("Page value < 1 specified"); } } /** * Returns whether this page ranges attribute is equivalent to the passed in * object. To be equivalent, all of the following conditions must be true: * <ol type=1> * <li>{@code object} is not {@code null}. * <li>{@code object} is an instance of class {@code PageRanges}. * <li>This page ranges attribute's members and {@code object}'s members * are the same. * </ol> * * @param object {@code Object} to compare to * @return {@code true} if {@code object} is equivalent to this page ranges * attribute, {@code false} otherwise */ public boolean equals(Object object) { return (super.equals(object) && object instanceof PageRanges); } /** * Get the printing attribute class which is to be used as the "category" * for this printing attribute value. * <p> * For class {@code PageRanges}, the category is class * {@code PageRanges} itself. * * @return printing attribute class (category), an instance of class * {@link Class java.lang.Class} */ public final Class<? extends Attribute> getCategory() { return PageRanges.class; } /** * Get the name of the category of which this attribute value is an * instance. * <p> * For class {@code PageRanges}, the category name is {@code "page-ranges"}. * * @return attribute category name */ public final String getName() { return "page-ranges"; } }