/*
 * @(#)PageRanges.java	1.7 03/01/23
 *
 * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.print.attribute.standard;

import javax.print.attribute.SetOfIntegerSyntax;
import javax.print.attribute.DocAttribute;
import javax.print.attribute.PrintRequestAttribute;
import javax.print.attribute.PrintJobAttribute;

/**
 * Class 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 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}}</CODE>. 
 * <P>
 * 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. 
 * <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>
 * 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. 
 * <P>
 * <LI>
 * 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. 
 * <P>
 * <LI>
 * SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, the 
 * specified page ranges will be printed. 
 * <P>
 * <LI>
 * SEPARATE_DOCUMENTS_COLLATED_COPIES -- For each separate input doc, the 
 * specified page ranges will be printed. 
 * </UL> 
 * <UL>
 * <LI>
 * SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, its own
 * specified page ranges will be printed.. 
 * <P>
 * <LI>
 * 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 
 * javax.print.attribute.SetOfIntegerSyntax SetOfIntegerSyntax} for an 
 * explanation of canonical array form. The category name returned by 
 * <CODE>getName()</CODE> gives the IPP attribute name. 
 * <P>
 *
 * @author  David Mendenhall
 * @author  Alan Kaminsky
 */
public final class PageRanges	extends SetOfIntegerSyntax
	implements DocAttribute, PrintRequestAttribute, PrintJobAttribute {

    
    /**
     * 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</CODE> is null or 
     *     any element of <CODE>members</CODE> is null. 
     * @exception  IllegalArgumentException
     *     (unchecked exception) Thrown if any element of 
     *   <CODE>members</CODE> is not a length-one or length-two array. Also 
     *     thrown if <CODE>members</CODE> 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 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</CODE> is null or 
     *     any element of <CODE>members</CODE> is null. 
     * @exception  IllegalArgumentException
     *     (Unchecked exception) Thrown if <CODE>members</CODE> 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. 
     */
    public PageRanges(String members) {
	super(members);
	if (members == null) {
	    throw new NullPointerException("members is null");
	}
	myPageRanges();
    }

    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.
     *
     * @exception  IllegalArgumentException
     *     (Unchecked exception) Thrown if <CODE>member</CODE> is less than 
     *     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.
     *
     * @exception  IllegalArgumentException
     *     (Unchecked exception) Thrown if a null range is specified or if a 
     *     non-null range is specified with <CODE>lowerBound</CODE> 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</CODE> is not null.
     * <LI>
     * <CODE>object</CODE> is an instance of class PageRanges.
     * <LI>
     * This page ranges attribute's members and <CODE>object</CODE>'s members 
     * are the same. 
     * </OL>
     *
     * @param  object  Object to compare to.
     *
     * @return  True if <CODE>object</CODE> is equivalent to this page ranges
     *          attribute, 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 PageRanges, the category is class PageRanges itself. 
     *
     * @return  Printing attribute class (category), an instance of class
     *          {@link java.lang.Class java.lang.Class}.
     */
    public final Class getCategory() {
	return PageRanges.class;
    }

    /**
     * Get the name of the category of which this attribute value is an 
     * instance. 
     * <P>
     * For class PageRanges, the category name is <CODE>"page-ranges"</CODE>. 
     *
     * @return  Attribute category name.
     */
    public final String getName() {
	return "page-ranges";
    }

}