Java > Open Source Codes > javax > print > attribute > standard > PageRanges


1 /*
2  * @(#)PageRanges.java 1.10 04/05/05
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.print.attribute.standard;
9
10 import javax.print.attribute.Attribute ;
11 import javax.print.attribute.SetOfIntegerSyntax ;
12 import javax.print.attribute.DocAttribute ;
13 import javax.print.attribute.PrintRequestAttribute ;
14 import javax.print.attribute.PrintJobAttribute ;
15
16 /**
17  * Class PageRanges is a printing attribute class, a set of integers, that
18  * identifies the range(s) of print-stream pages that the Printer object uses
19  * for each copy of each document which are to be printed. Nothing is printed
20  * for any pages identified that do not exist in the document(s). The attribute
21  * is associated with <I>print-stream</I> pages, not application-numbered pages
22  * (for example, the page numbers found in the headers and or footers for
23  * certain word processing applications).
24  * <P>
25  * In most cases, the exact pages to be printed will be generated by a device
26  * driver and this attribute would not be required. However, when printing an
27  * archived document which has already been formatted, the end user may elect to
28  * print just a subset of the pages contained in the document. In this case, if
29  * a page range of <CODE>"<I>n</I>-<I>m</I>"</CODE> is specified, the first page
30  * to be printed will be page <I>n.</I> All subsequent pages of the document
31  * will be printed through and including page <I>m.</I>
32  * <P>
33  * If a PageRanges attribute is not specified for a print job, all pages of
34  * the document will be printed. In other words, the default value for the
35  * PageRanges attribute is always <CODE>{{1, Integer.MAX_VALUE}}</CODE>.
36  * <P>
37  * The effect of a PageRanges attribute on a multidoc print job (a job with
38  * multiple documents) depends on whether all the docs have the same page ranges
39  * specified or whether different docs have different page ranges specified, and
40  * on the (perhaps defaulted) value of the {@link MultipleDocumentHandling
41  * MultipleDocumentHandling} attribute.
42  * <UL>
43  * <LI>
44  * If all the docs have the same page ranges specified, then any value of {@link
45  * MultipleDocumentHandling MultipleDocumentHandling} makes sense, and the
46  * printer's processing depends on the {@link MultipleDocumentHandling
47  * MultipleDocumentHandling} value:
48  * <UL>
49  * <LI>
50  * SINGLE_DOCUMENT -- All the input docs will be combined together into one
51  * output document. The specified page ranges of that output document will be
52  * printed.
53  * <P>
54  * <LI>
55  * SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together
56  * into one output document, and the first impression of each input doc will
57  * always start on a new media sheet. The specified page ranges of that output
58  * document will be printed.
59  * <P>
60  * <LI>
61  * SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, the
62  * specified page ranges will be printed.
63  * <P>
64  * <LI>
65  * SEPARATE_DOCUMENTS_COLLATED_COPIES -- For each separate input doc, the
66  * specified page ranges will be printed.
67  * </UL>
68  * <UL>
69  * <LI>
70  * SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, its own
71  * specified page ranges will be printed..
72  * <P>
73  * <LI>
74  * SEPARATE_DOCUMENTS_COLLATED_COPIES -- For each separate input doc, its own
75  * specified page ranges will be printed..
76  * </UL>
77  * </UL>
78  * <P>
79  * <B>IPP Compatibility:</B> The PageRanges attribute's canonical array form
80  * gives the lower and upper bound for each range of pages to be included in
81  * and IPP "page-ranges" attribute. See class {@link
82  * javax.print.attribute.SetOfIntegerSyntax SetOfIntegerSyntax} for an
83  * explanation of canonical array form. The category name returned by
84  * <CODE>getName()</CODE> gives the IPP attribute name.
85  * <P>
86  *
87  * @author David Mendenhall
88  * @author Alan Kaminsky
89  */
90 public final class PageRanges extends SetOfIntegerSyntax
91     implements DocAttribute , PrintRequestAttribute , PrintJobAttribute {
92
93     private static final long serialVersionUID = 8639895197656148392L;
94
95     
96     /**
97      * Construct a new page ranges attribute with the given members. The
98      * members are specified in "array form;" see class {@link
99      * javax.print.attribute.SetOfIntegerSyntax SetOfIntegerSyntax} for an
100      * explanation of array form.
101      *
102      * @param members Set members in array form.
103      *
104      * @exception NullPointerException
105      * (unchecked exception) Thrown if <CODE>members</CODE> is null or
106      * any element of <CODE>members</CODE> is null.
107      * @exception IllegalArgumentException
108      * (unchecked exception) Thrown if any element of
109      * <CODE>members</CODE> is not a length-one or length-two array. Also
110      * thrown if <CODE>members</CODE> is a zero-length array or if any
111      * member of the set is less than 1.
112      */
113     public PageRanges(int[][] members) {
114     super (members);
115     if (members == null) {
116         throw new NullPointerException ("members is null");
117     }
118     myPageRanges();
119     }
120     /**
121      * Construct a new page ranges attribute with the given members in
122      * string form.
123      * See class {@link javax.print.attribute.SetOfIntegerSyntax
124      * SetOfIntegerSyntax}
125      * for explanation of the syntax.
126      *
127      * @param members Set members in string form.
128      *
129      * @exception NullPointerException
130      * (unchecked exception) Thrown if <CODE>members</CODE> is null or
131      * any element of <CODE>members</CODE> is null.
132      * @exception IllegalArgumentException
133      * (Unchecked exception) Thrown if <CODE>members</CODE> does not
134      * obey the proper syntax. Also
135      * thrown if the constructed set-of-integer is a
136      * zero-length array or if any
137      * member of the set is less than 1.
138      */
139     public PageRanges(String members) {
140     super(members);
141     if (members == null) {
142         throw new NullPointerException ("members is null");
143     }
144     myPageRanges();
145     }
146
147     private void myPageRanges() {
148     int[][] myMembers = getMembers();
149     int n = myMembers.length;
150     if (n == 0) {
151         throw new IllegalArgumentException ("members is zero-length");
152     }
153     int i;
154     for (i = 0; i < n; ++ i) {
155       if (myMembers[i][0] < 1) {
156         throw new IllegalArgumentException ("Page value < 1 specified");
157       }
158     }
159     }
160
161     /**
162      * Construct a new page ranges attribute containing a single integer. That
163      * is, only the one page is to be printed.
164      *
165      * @param member Set member.
166      *
167      * @exception IllegalArgumentException
168      * (Unchecked exception) Thrown if <CODE>member</CODE> is less than
169      * 1.
170      */
171     public PageRanges(int member) {
172     super (member);
173     if (member < 1) {
174         throw new IllegalArgumentException ("Page value < 1 specified");
175     }
176     }
177
178     /**
179      * Construct a new page ranges attribute containing a single range of
180      * integers. That is, only those pages in the one range are to be printed.
181      *
182      * @param lowerBound Lower bound of the range.
183      * @param upperBound Upper bound of the range.
184      *
185      * @exception IllegalArgumentException
186      * (Unchecked exception) Thrown if a null range is specified or if a
187      * non-null range is specified with <CODE>lowerBound</CODE> less than
188      * 1.
189      */
190     public PageRanges(int lowerBound, int upperBound) {
191     super (lowerBound, upperBound);
192     if (lowerBound > upperBound) {
193         throw new IllegalArgumentException ("Null range specified");
194     } else if (lowerBound < 1) {
195         throw new IllegalArgumentException ("Page value < 1 specified");
196     }
197     }
198
199     /**
200      * Returns whether this page ranges attribute is equivalent to the passed
201      * in object. To be equivalent, all of the following conditions must be
202      * true:
203      * <OL TYPE=1>
204      * <LI>
205      * <CODE>object</CODE> is not null.
206      * <LI>
207      * <CODE>object</CODE> is an instance of class PageRanges.
208      * <LI>
209      * This page ranges attribute's members and <CODE>object</CODE>'s members
210      * are the same.
211      * </OL>
212      *
213      * @param object Object to compare to.
214      *
215      * @return True if <CODE>object</CODE> is equivalent to this page ranges
216      * attribute, false otherwise.
217      */
218     public boolean equals(Object object) {
219     return (super.equals(object) && object instanceof PageRanges );
220     }
221
222     /**
223      * Get the printing attribute class which is to be used as the "category"
224      * for this printing attribute value.
225      * <P>
226      * For class PageRanges, the category is class PageRanges itself.
227      *
228      * @return Printing attribute class (category), an instance of class
229      * {@link java.lang.Class java.lang.Class}.
230      */
231     public final Class <? extends Attribute > getCategory() {
232     return PageRanges .class;
233     }
234
235     /**
236      * Get the name of the category of which this attribute value is an
237      * instance.
238      * <P>
239      * For class PageRanges, the category name is <CODE>"page-ranges"</CODE>.
240      *
241      * @return Attribute category name.
242      */
243     public final String getName() {
244     return "page-ranges";
245     }
246
247 }
248

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags