001 /*
002 * Copyright 2000-2001 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.print.attribute;
027
028 /**
029 * Interface PrintRequestAttributeSet specifies the interface for a set of
030 * print request attributes, i.e. printing attributes that implement interface
031 * {@link PrintRequestAttribute PrintRequestAttribute}.
032 * The client uses a PrintRequestAttributeSet to specify the settings to be
033 * applied to a whole print job and to all the docs in the print job.
034 * <P>
035 * PrintRequestAttributeSet is just an {@link AttributeSet AttributeSet} whose
036 * constructors and mutating operations guarantee an additional invariant,
037 * namely that all attribute values in the PrintRequestAttributeSet must be
038 * instances of interface {@link PrintRequestAttribute PrintRequestAttribute}.
039 * The {@link #add(Attribute) <CODE>add(Attribute)</CODE>}, and
040 * {@link #addAll(AttributeSet) <CODE>addAll(AttributeSet)</CODE>} operations
041 * are respecified below to guarantee this additional invariant.
042 * <P>
043 *
044 * @author Alan Kaminsky
045 */
046 public interface PrintRequestAttributeSet extends AttributeSet {
047
048 /**
049 * Adds the specified attribute value to this attribute set if it is not
050 * already present, first removing any existing value in the same
051 * attribute category as the specified attribute value (optional
052 * operation).
053 *
054 * @param attribute Attribute value to be added to this attribute set.
055 *
056 * @return <tt>true</tt> if this attribute set changed as a result of
057 * the call, i.e., the given attribute value was not already a
058 * member of this attribute set.
059 *
060 * @throws UnmodifiableSetException
061 * (unchecked exception) Thrown if this attribute set does not
062 * support the <CODE>add()</CODE> operation.
063 * @throws ClassCastException
064 * (unchecked exception) Thrown if the <CODE>attribute</CODE> is
065 * not an instance of interface
066 * {@link PrintRequestAttribute PrintRequestAttribute}.
067 * @throws NullPointerException
068 * (unchecked exception) Thrown if the <CODE>attribute</CODE> is null.
069 */
070 public boolean add(Attribute attribute);
071
072 /**
073 * Adds all of the elements in the specified set to this attribute.
074 * The outcome is the same as if the
075 * {@link #add(Attribute) <CODE>add(Attribute)</CODE>}
076 * operation had been applied to this attribute set successively with
077 * each element from the specified set. If none of the categories in the
078 * specified set are the same as any categories in this attribute set,
079 * the <tt>addAll()</tt> operation effectively modifies this attribute
080 * set so that its value is the <i>union</i> of the two sets.
081 * <P>
082 * The behavior of the <CODE>addAll()</CODE> operation is unspecified if
083 * the specified set is modified while the operation is in progress.
084 * <P>
085 * If the <CODE>addAll()</CODE> operation throws an exception, the effect
086 * on this attribute set's state is implementation dependent; elements
087 * from the specified set before the point of the exception may or
088 * may not have been added to this attribute set.
089 *
090 * @param attributes whose elements are to be added to this attribute
091 * set.
092 *
093 * @return <tt>true</tt> if this attribute set changed as a result of
094 * the call.
095 *
096 * @throws UnmodifiableSetException
097 * (Unchecked exception) Thrown if this attribute set does not
098 * support the <tt>addAll()</tt> method.
099 * @throws ClassCastException
100 * (Unchecked exception) Thrown if some element in the specified
101 * set is not an instance of interface {@link PrintRequestAttribute
102 * PrintRequestAttribute}.
103 * @throws NullPointerException
104 * (Unchecked exception) Thrown if the specified set is null.
105 *
106 * @see #add(Attribute)
107 */
108 public boolean addAll(AttributeSet attributes);
109
110 }
|