1 /*
   2  * Copyright (c) 2000, 2017, 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;
  27 
  28 /**
  29  * Interface {@code PrintRequestAttributeSet} specifies the interface for a set
  30  * of print request attributes, i.e. printing attributes that implement
  31  * interface {@link PrintRequestAttribute PrintRequestAttribute}. The client
  32  * uses a {@code PrintRequestAttributeSet} to specify the settings to be applied
  33  * to a whole print job and to all the docs in the print job.
  34  * <p>
  35  * {@code PrintRequestAttributeSet} is just an {@link AttributeSet AttributeSet}
  36  * whose constructors and mutating operations guarantee an additional invariant,
  37  * namely that all attribute values in the {@code PrintRequestAttributeSet} must
  38  * be instances of interface
  39  * {@link PrintRequestAttribute PrintRequestAttribute}. The
  40  * {@link #add(Attribute) add(Attribute)}, and
  41  * {@link #addAll(AttributeSet) addAll(AttributeSet)} operations are respecified
  42  * below to guarantee this additional invariant.
  43  *
  44  * @author Alan Kaminsky
  45  */
  46 public interface PrintRequestAttributeSet extends AttributeSet {
  47 
  48     /**
  49      * Adds the specified attribute value to this attribute set if it is not
  50      * already present, first removing any existing value in the same attribute
  51      * category as the specified attribute value (optional operation).
  52      *
  53      * @param  attribute attribute value to be added to this attribute set
  54      * @return {@code true} if this attribute set changed as a result of the
  55      *         call, i.e., the given attribute value was not already a member of
  56      *         this attribute set
  57      * @throws UnmodifiableSetException if this attribute set does not support
  58      *         the {@code add()} operation
  59      * @throws ClassCastException if the {@code attribute} is not an instance of
  60      *         interface {@link PrintRequestAttribute PrintRequestAttribute}
  61      * @throws NullPointerException if the {@code attribute} is {@code null}
  62      */
  63     public boolean add(Attribute attribute);
  64 
  65     /**
  66      * Adds all of the elements in the specified set to this attribute. The
  67      * outcome is the same as if the {@link #add(Attribute) add(Attribute)}
  68      * operation had been applied to this attribute set successively with each
  69      * element from the specified set. If none of the categories in the
  70      * specified set are the same as any categories in this attribute set, the
  71      * {@code addAll()} operation effectively modifies this attribute set so
  72      * that its value is the <i>union</i> of the two sets.
  73      * <p>
  74      * The behavior of the {@code addAll()} operation is unspecified if the
  75      * specified set is modified while the operation is in progress.
  76      * <p>
  77      * If the {@code addAll()} operation throws an exception, the effect on this
  78      * attribute set's state is implementation dependent; elements from the
  79      * specified set before the point of the exception may or may not have been
  80      * added to this attribute set.
  81      *
  82      * @param  attributes whose elements are to be added to this attribute set
  83      * @return {@code true} if this attribute set changed as a result of the
  84      *         call
  85      * @throws UnmodifiableSetException if this attribute set does not support
  86      *         the {@code addAll()} method
  87      * @throws ClassCastException if some element in the specified set is not an
  88      *         instance of interface
  89      *         {@link PrintRequestAttribute PrintRequestAttribute}
  90      * @throws NullPointerException if the specified set is {@code null}
  91      * @see #add(Attribute)
  92      */
  93     public boolean addAll(AttributeSet attributes);
  94 }