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 }