View Javadoc
1   /*
2    * Copyright (c) 2000, 2004, 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   * <P>
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   * <P>
78   * <LI>
79   * SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, the
80   * specified page ranges will be printed.
81   * <P>
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   * <P>
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  * <P>
104  *
105  * @author  David Mendenhall
106  * @author  Alan Kaminsky
107  */
108 public final class PageRanges   extends SetOfIntegerSyntax
109         implements DocAttribute, PrintRequestAttribute, PrintJobAttribute {
110 
111     private static final long serialVersionUID = 8639895197656148392L;
112 
113 
114     /**
115      * Construct a new page ranges attribute with the given members. The
116      * members are specified in "array form;" see class {@link
117      * javax.print.attribute.SetOfIntegerSyntax SetOfIntegerSyntax} for an
118      * explanation of array form.
119      *
120      * @param  members  Set members in array form.
121      *
122      * @exception  NullPointerException
123      *     (unchecked exception) Thrown if <CODE>members</CODE> is null or
124      *     any element of <CODE>members</CODE> is null.
125      * @exception  IllegalArgumentException
126      *     (unchecked exception) Thrown if any element of
127      *   <CODE>members</CODE> is not a length-one or length-two array. Also
128      *     thrown if <CODE>members</CODE> is a zero-length array or if any
129      *     member of the set is less than 1.
130      */
131     public PageRanges(int[][] members) {
132         super (members);
133         if (members == null) {
134             throw new NullPointerException("members is null");
135         }
136         myPageRanges();
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("Page value < 1 specified");
175           }
176         }
177     }
178 
179     /**
180      * Construct a new page ranges attribute containing a single integer. That
181      * is, only the one page is to be printed.
182      *
183      * @param  member  Set member.
184      *
185      * @exception  IllegalArgumentException
186      *     (Unchecked exception) Thrown if <CODE>member</CODE> is less than
187      *     1.
188      */
189     public PageRanges(int member) {
190         super (member);
191         if (member < 1) {
192             throw new IllegalArgumentException("Page value < 1 specified");
193         }
194     }
195 
196     /**
197      * Construct a new page ranges attribute containing a single range of
198      * integers. That is, only those pages in the one range are to be printed.
199      *
200      * @param  lowerBound  Lower bound of the range.
201      * @param  upperBound  Upper bound of the range.
202      *
203      * @exception  IllegalArgumentException
204      *     (Unchecked exception) Thrown if a null range is specified or if a
205      *     non-null range is specified with <CODE>lowerBound</CODE> less than
206      *     1.
207      */
208     public PageRanges(int lowerBound, int upperBound) {
209         super (lowerBound, upperBound);
210         if (lowerBound > upperBound) {
211             throw new IllegalArgumentException("Null range specified");
212         } else if (lowerBound < 1) {
213             throw new IllegalArgumentException("Page value < 1 specified");
214         }
215     }
216 
217     /**
218      * Returns whether this page ranges attribute is equivalent to the passed
219      * in object. To be equivalent, all of the following conditions must be
220      * true:
221      * <OL TYPE=1>
222      * <LI>
223      * <CODE>object</CODE> is not null.
224      * <LI>
225      * <CODE>object</CODE> is an instance of class PageRanges.
226      * <LI>
227      * This page ranges attribute's members and <CODE>object</CODE>'s members
228      * are the same.
229      * </OL>
230      *
231      * @param  object  Object to compare to.
232      *
233      * @return  True if <CODE>object</CODE> is equivalent to this page ranges
234      *          attribute, false otherwise.
235      */
236     public boolean equals(Object object) {
237         return (super.equals(object) && object instanceof PageRanges);
238     }
239 
240     /**
241      * Get the printing attribute class which is to be used as the "category"
242      * for this printing attribute value.
243      * <P>
244      * For class PageRanges, the category is class PageRanges itself.
245      *
246      * @return  Printing attribute class (category), an instance of class
247      *          {@link java.lang.Class java.lang.Class}.
248      */
249     public final Class<? extends Attribute> getCategory() {
250         return PageRanges.class;
251     }
252 
253     /**
254      * Get the name of the category of which this attribute value is an
255      * instance.
256      * <P>
257      * For class PageRanges, the category name is <CODE>"page-ranges"</CODE>.
258      *
259      * @return  Attribute category name.
260      */
261     public final String getName() {
262         return "page-ranges";
263     }
264 
265 }