< prev index next >
src/java.desktop/share/classes/javax/print/attribute/AttributeSet.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
--- 1,7 ----
/*
! * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
*** 24,309 ****
*/
package javax.print.attribute;
/**
! * Interface AttributeSet specifies the interface for a set of printing
* attributes. A printing attribute is an object whose class implements
* interface {@link Attribute Attribute}.
! * <P>
! * An attribute set contains a group of <I>attribute values,</I>
! * where duplicate values are not allowed in the set.
! * Furthermore, each value in an attribute set is
! * a member of some <I>category,</I> and at most one value in any particular
! * category is allowed in the set. For an attribute set, the values are {@link
! * Attribute Attribute} objects, and the categories are {@link java.lang.Class
! * Class} objects. An attribute's category is the class (or interface) at the
! * root of the class hierarchy for that kind of attribute. Note that an
! * attribute object's category may be a superclass of the attribute object's
! * class rather than the attribute object's class itself. An attribute
! * object's
! * category is determined by calling the {@link Attribute#getCategory()
! * getCategory()} method defined in interface {@link Attribute
! * Attribute}.
! * <P>
! * The interfaces of an AttributeSet resemble those of the Java Collections
! * API's java.util.Map interface, but is more restrictive in the types
! * it will accept, and combines keys and values into an Attribute.
! * <P>
! * Attribute sets are used in several places in the Print Service API. In
! * each context, only certain kinds of attributes are allowed to appear in the
* attribute set, as determined by the tagging interfaces which the attribute
! * class implements -- {@link DocAttribute DocAttribute}, {@link
! * PrintRequestAttribute PrintRequestAttribute}, {@link PrintJobAttribute
! * PrintJobAttribute}, and {@link PrintServiceAttribute
! * PrintServiceAttribute}.
* There are four specializations of an attribute set that are restricted to
! * contain just one of the four kinds of attribute -- {@link DocAttributeSet
! * DocAttributeSet}, {@link PrintRequestAttributeSet
! * PrintRequestAttributeSet},
! * {@link PrintJobAttributeSet PrintJobAttributeSet}, and {@link
! * PrintServiceAttributeSet PrintServiceAttributeSet}, respectively. Note that
! * many attribute classes implement more than one tagging interface and so may
! * appear in more than one context.
! * <UL>
! * <LI>
! * A {@link DocAttributeSet DocAttributeSet}, containing {@link DocAttribute
! * DocAttribute}s, specifies the characteristics of an individual doc and the
! * print job settings to be applied to an individual doc.
! *
! * <LI>
! * A {@link PrintRequestAttributeSet PrintRequestAttributeSet}, containing
* {@link PrintRequestAttribute PrintRequestAttribute}s, specifies the
! * settings
! * to be applied to a whole print job and to all the docs in the print job.
! *
! * <LI>
! * A {@link PrintJobAttributeSet PrintJobAttributeSet}, containing {@link
! * PrintJobAttribute PrintJobAttribute}s, reports the status of a print job.
! *
! * <LI>
! * A {@link PrintServiceAttributeSet PrintServiceAttributeSet}, containing
* {@link PrintServiceAttribute PrintServiceAttribute}s, reports the status of
* a Print Service instance.
! * </UL>
! * <P>
* In some contexts, the client is only allowed to examine an attribute set's
* contents but not change them (the set is read-only). In other places, the
* client is allowed both to examine and to change an attribute set's contents
* (the set is read-write). For a read-only attribute set, calling a mutating
! * operation throws an UnmodifiableSetException.
! * <P>
* The Print Service API provides one implementation of interface
! * AttributeSet, class {@link HashAttributeSet HashAttributeSet}.
! * A client can use class {@link
! * HashAttributeSet HashAttributeSet} or provide its own implementation of
! * interface AttributeSet. The Print Service API also provides
! * implementations of interface AttributeSet's subinterfaces -- classes {@link
! * HashDocAttributeSet HashDocAttributeSet},
! * {@link HashPrintRequestAttributeSet
! * HashPrintRequestAttributeSet}, {@link HashPrintJobAttributeSet
! * HashPrintJobAttributeSet}, and {@link HashPrintServiceAttributeSet
! * HashPrintServiceAttributeSet}.
*
* @author Alan Kaminsky
*/
public interface AttributeSet {
-
/**
* Returns the attribute value which this attribute set contains in the
! * given attribute category. Returns {@code null} if this attribute set
! * does not contain any attribute value in the given attribute category.
*
! * @param category Attribute category whose associated attribute value
! * is to be returned. It must be a
! * {@link java.lang.Class Class}
! * that implements interface {@link Attribute
! * Attribute}.
! *
! * @return The attribute value in the given attribute category contained
! * in this attribute set, or {@code null} if this attribute set
! * does not contain any attribute value in the given attribute
! * category.
! *
! * @throws NullPointerException
! * (unchecked exception) Thrown if the {@code category} is null.
! * @throws ClassCastException
! * (unchecked exception) Thrown if the {@code category} is not a
! * {@link java.lang.Class Class} that implements interface {@link
! * Attribute Attribute}.
*/
public Attribute get(Class<?> category);
/**
! * Adds the specified attribute to this attribute set if it is not
! * already present, first removing any existing value in the same
! * attribute category as the specified attribute value.
! *
! * @param attribute Attribute value to be added to this attribute set.
*
* @return {@code true} if this attribute set changed as a result of the
! * call, i.e., the given attribute value was not already a member
! * of this attribute set.
! *
! * @throws NullPointerException
! * (unchecked exception) Thrown if the {@code attribute} is null.
! * @throws UnmodifiableSetException
! * (unchecked exception) Thrown if this attribute set does not support
! * the {@code add()} operation.
*/
public boolean add(Attribute attribute);
-
/**
* Removes any attribute for this category from this attribute set if
! * present. If {@code category} is null, then
! * {@code remove()} does nothing and returns {@code false}.
! *
! * @param category Attribute category to be removed from this
! * attribute set.
*
* @return {@code true} if this attribute set changed as a result of the
* call, i.e., the given attribute value had been a member of this
! * attribute set.
! *
! * @throws UnmodifiableSetException
! * (unchecked exception) Thrown if this attribute set does not support
! * the {@code remove()} operation.
*/
public boolean remove(Class<?> category);
/**
! * Removes the specified attribute from this attribute set if
! * present. If {@code attribute} is null, then
! * {@code remove()} does nothing and returns {@code false}.
! *
! * @param attribute Attribute value to be removed from this attribute set.
*
* @return {@code true} if this attribute set changed as a result of the
* call, i.e., the given attribute value had been a member of this
! * attribute set.
! *
! * @throws UnmodifiableSetException
! * (unchecked exception) Thrown if this attribute set does not support
! * the {@code remove()} operation.
*/
public boolean remove(Attribute attribute);
/**
! * Returns {@code true} if this attribute set contains an
! * attribute for the specified category.
! *
! * @param category whose presence in this attribute set is
! * to be tested.
*
! * @return {@code true} if this attribute set contains an attribute
! * value for the specified category.
*/
public boolean containsKey(Class<?> category);
/**
! * Returns {@code true} if this attribute set contains the given
! * attribute value.
! *
! * @param attribute Attribute value whose presence in this
! * attribute set is to be tested.
*
! * @return {@code true} if this attribute set contains the given
! * attribute value.
*/
public boolean containsValue(Attribute attribute);
/**
! * Adds all of the elements in the specified set to this attribute.
! * The outcome is the same as if the =
! * {@link #add(Attribute) add(Attribute)}
* operation had been applied to this attribute set successively with each
! * element from the specified set.
! * The behavior of the {@code addAll(AttributeSet)}
! * operation is unspecified if the specified set is modified while
! * the operation is in progress.
! * <P>
! * If the {@code addAll(AttributeSet)} operation throws an exception,
! * the effect on this attribute set's state is implementation dependent;
! * elements from the specified set before the point of the exception may
! * or may not have been added to this attribute set.
! *
! * @param attributes whose elements are to be added to this attribute
! * set.
*
* @return {@code true} if this attribute set changed as a result of the
! * call.
! *
! * @throws UnmodifiableSetException
! * (Unchecked exception) Thrown if this attribute set does not support
! * the {@code addAll(AttributeSet)} method.
! * @throws NullPointerException
! * (Unchecked exception) Thrown if some element in the specified
! * set is null.
! *
* @see #add(Attribute)
*/
public boolean addAll(AttributeSet attributes);
/**
! * Returns the number of attributes in this attribute set. If this
! * attribute set contains more than {@code Integer.MAX_VALUE} elements,
! * returns {@code Integer.MAX_VALUE}.
*
! * @return The number of attributes in this attribute set.
*/
public int size();
/**
* Returns an array of the attributes contained in this set.
! * @return the Attributes contained in this set as an array, zero length
! * if the AttributeSet is empty.
*/
public Attribute[] toArray();
-
/**
* Removes all attributes from this attribute set.
*
! * @throws UnmodifiableSetException
! * (unchecked exception) Thrown if this attribute set does not support
! * the {@code clear()} operation.
*/
public void clear();
/**
! * Returns true if this attribute set contains no attributes.
*
! * @return true if this attribute set contains no attributes.
*/
public boolean isEmpty();
/**
* Compares the specified object with this attribute set for equality.
! * Returns {@code true} if the given object is also an attribute set and
! * the two attribute sets contain the same attribute category-attribute
! * value mappings. This ensures that the
! * {@code equals()} method works properly across different
! * implementations of the AttributeSet interface.
! *
! * @param object to be compared for equality with this attribute set.
! *
! * @return {@code true} if the specified object is equal to this
! * attribute set.
*/
public boolean equals(Object object);
/**
* Returns the hash code value for this attribute set. The hash code of an
! * attribute set is defined to be the sum of the hash codes of each entry
! * in the AttributeSet.
! * This ensures that {@code t1.equals(t2)} implies that
! * {@code t1.hashCode()==t2.hashCode()} for any two attribute sets
* {@code t1} and {@code t2}, as required by the general contract of
! * {@link java.lang.Object#hashCode() Object.hashCode()}.
*
! * @return The hash code value for this attribute set.
*/
public int hashCode();
-
}
--- 24,265 ----
*/
package javax.print.attribute;
/**
! * Interface {@code AttributeSet} specifies the interface for a set of printing
* attributes. A printing attribute is an object whose class implements
* interface {@link Attribute Attribute}.
! * <p>
! * An attribute set contains a group of <i>attribute values,</i> where duplicate
! * values are not allowed in the set. Furthermore, each value in an attribute
! * set is a member of some <i>category,</i> and at most one value in any
! * particular category is allowed in the set. For an attribute set, the values
! * are {@link Attribute Attribute} objects, and the categories are
! * {@link Class Class} objects. An attribute's category is the class (or
! * interface) at the root of the class hierarchy for that kind of attribute.
! * Note that an attribute object's category may be a superclass of the attribute
! * object's class rather than the attribute object's class itself. An attribute
! * object's category is determined by calling the
! * {@link Attribute#getCategory() getCategory()} method defined in interface
! * {@link Attribute Attribute}.
! * <p>
! * The interfaces of an {@code AttributeSet} resemble those of the Java
! * Collections API's {@code java.util.Map} interface, but is more restrictive in
! * the types it will accept, and combines keys and values into an
! * {@code Attribute}.
! * <p>
! * Attribute sets are used in several places in the Print Service API. In each
! * context, only certain kinds of attributes are allowed to appear in the
* attribute set, as determined by the tagging interfaces which the attribute
! * class implements -- {@link DocAttribute DocAttribute},
! * {@link PrintRequestAttribute PrintRequestAttribute},
! * {@link PrintJobAttribute PrintJobAttribute}, and
! * {@link PrintServiceAttribute PrintServiceAttribute}.
* There are four specializations of an attribute set that are restricted to
! * contain just one of the four kinds of attribute --
! * {@link DocAttributeSet DocAttributeSet},
! * {@link PrintRequestAttributeSet PrintRequestAttributeSet},
! * {@link PrintJobAttributeSet PrintJobAttributeSet}, and
! * {@link PrintServiceAttributeSet PrintServiceAttributeSet}, respectively. Note
! * that many attribute classes implement more than one tagging interface and so
! * may appear in more than one context.
! * <ul>
! * <li>A {@link DocAttributeSet DocAttributeSet}, containing
! * {@link DocAttribute DocAttribute}s, specifies the characteristics of an
! * individual doc and the print job settings to be applied to an individual
! * doc.
! * <li>A {@link PrintRequestAttributeSet PrintRequestAttributeSet}, containing
* {@link PrintRequestAttribute PrintRequestAttribute}s, specifies the
! * settings to be applied to a whole print job and to all the docs in the
! * print job.
! * <li>A {@link PrintJobAttributeSet PrintJobAttributeSet}, containing
! * {@link PrintJobAttribute PrintJobAttribute}s, reports the status of a print
! * job.
! * <li>A {@link PrintServiceAttributeSet PrintServiceAttributeSet}, containing
* {@link PrintServiceAttribute PrintServiceAttribute}s, reports the status of
* a Print Service instance.
! * </ul>
* In some contexts, the client is only allowed to examine an attribute set's
* contents but not change them (the set is read-only). In other places, the
* client is allowed both to examine and to change an attribute set's contents
* (the set is read-write). For a read-only attribute set, calling a mutating
! * operation throws an {@code UnmodifiableSetException}.
! * <p>
* The Print Service API provides one implementation of interface
! * {@code AttributeSet}, class {@link HashAttributeSet HashAttributeSet}. A
! * client can use class {@link HashAttributeSet HashAttributeSet} or provide its
! * own implementation of interface {@code AttributeSet}. The Print Service API
! * also provides implementations of interface {@code AttributeSet}'s
! * subinterfaces -- classes
! * {@link HashDocAttributeSet HashDocAttributeSet},
! * {@link HashPrintRequestAttributeSet HashPrintRequestAttributeSet},
! * {@link HashPrintJobAttributeSet HashPrintJobAttributeSet}, and
! * {@link HashPrintServiceAttributeSet HashPrintServiceAttributeSet}.
*
* @author Alan Kaminsky
*/
public interface AttributeSet {
/**
* Returns the attribute value which this attribute set contains in the
! * given attribute category. Returns {@code null} if this attribute set does
! * not contain any attribute value in the given attribute category.
*
! * @param category attribute category whose associated attribute value is
! * to be returned. It must be a {@link Class Class} that implements
! * interface {@link Attribute Attribute}.
! * @return the attribute value in the given attribute category contained in
! * this attribute set, or {@code null} if this attribute set does
! * not contain any attribute value in the given attribute category
! * @throws NullPointerException if the {@code category} is {@code null}
! * @throws ClassCastException if the {@code category} is not a
! * {@link Class Class} that implements interface
! * {@link Attribute Attribute}
*/
public Attribute get(Class<?> category);
/**
! * Adds the specified attribute to this attribute set if it is not already
! * present, first removing any existing value in the same attribute category
! * as the specified attribute value.
*
+ * @param attribute attribute value to be added to this attribute set
* @return {@code true} if this attribute set changed as a result of the
! * call, i.e., the given attribute value was not already a member of
! * this attribute set
! * @throws NullPointerException if the {@code attribute} is {@code null}
! * @throws UnmodifiableSetException if this attribute set does not support
! * the {@code add()} operation
*/
public boolean add(Attribute attribute);
/**
* Removes any attribute for this category from this attribute set if
! * present. If {@code category} is {@code null}, then {@code remove()} does
! * nothing and returns {@code false}.
*
+ * @param category attribute category to be removed from this attribute set
* @return {@code true} if this attribute set changed as a result of the
* call, i.e., the given attribute value had been a member of this
! * attribute set
! * @throws UnmodifiableSetException if this attribute set does not support
! * the {@code remove()} operation
*/
public boolean remove(Class<?> category);
/**
! * Removes the specified attribute from this attribute set if present. If
! * {@code attribute} is {@code null}, then {@code remove()} does nothing and
! * returns {@code false}.
*
+ * @param attribute attribute value to be removed from this attribute set
* @return {@code true} if this attribute set changed as a result of the
* call, i.e., the given attribute value had been a member of this
! * attribute set
! * @throws UnmodifiableSetException if this attribute set does not support
! * the {@code remove()} operation
*/
public boolean remove(Attribute attribute);
/**
! * Returns {@code true} if this attribute set contains an attribute for the
! * specified category.
*
! * @param category whose presence in this attribute set is to be tested
! * @return {@code true} if this attribute set contains an attribute value
! * for the specified category
*/
public boolean containsKey(Class<?> category);
/**
! * Returns {@code true} if this attribute set contains the given attribute
! * value.
*
! * @param attribute attribute value whose presence in this attribute set is
! * to be tested
! * @return {@code true} if this attribute set contains the given attribute
! * value
*/
public boolean containsValue(Attribute attribute);
/**
! * Adds all of the elements in the specified set to this attribute. The
! * outcome is the same as if the = {@link #add(Attribute) add(Attribute)}
* operation had been applied to this attribute set successively with each
! * element from the specified set. The behavior of the
! * {@code addAll(AttributeSet)} operation is unspecified if the specified
! * set is modified while the operation is in progress.
! * <p>
! * If the {@code addAll(AttributeSet)} operation throws an exception, the
! * effect on this attribute set's state is implementation dependent;
! * elements from the specified set before the point of the exception may or
! * may not have been added to this attribute set.
*
+ * @param attributes whose elements are to be added to this attribute set
* @return {@code true} if this attribute set changed as a result of the
! * call
! * @throws UnmodifiableSetException if this attribute set does not support
! * the {@code addAll(AttributeSet)} method
! * @throws NullPointerException if some element in the specified set is
! * {@code null}
* @see #add(Attribute)
*/
public boolean addAll(AttributeSet attributes);
/**
! * Returns the number of attributes in this attribute set. If this attribute
! * set contains more than {@code Integer.MAX_VALUE} elements, returns
! * {@code Integer.MAX_VALUE}.
*
! * @return the number of attributes in this attribute set
*/
public int size();
/**
* Returns an array of the attributes contained in this set.
! *
! * @return the {@code Attributes} contained in this set as an array, zero
! * length if the {@code AttributeSet} is empty
*/
public Attribute[] toArray();
/**
* Removes all attributes from this attribute set.
*
! * @throws UnmodifiableSetException if this attribute set does not support
! * the {@code clear()} operation
*/
public void clear();
/**
! * Returns {@code true} if this attribute set contains no attributes.
*
! * @return {@code true} if this attribute set contains no attributes
*/
public boolean isEmpty();
/**
* Compares the specified object with this attribute set for equality.
! * Returns {@code true} if the given object is also an attribute set and the
! * two attribute sets contain the same attribute category-attribute value
! * mappings. This ensures that the {@code equals()} method works properly
! * across different implementations of the {@code AttributeSet} interface.
! *
! * @param object to be compared for equality with this attribute set
! * @return {@code true} if the specified object is equal to this attribute
! * set
*/
public boolean equals(Object object);
/**
* Returns the hash code value for this attribute set. The hash code of an
! * attribute set is defined to be the sum of the hash codes of each entry in
! * the {@code AttributeSet}. This ensures that {@code t1.equals(t2)} implies
! * that {@code t1.hashCode()==t2.hashCode()} for any two attribute sets
* {@code t1} and {@code t2}, as required by the general contract of
! * {@link Object#hashCode() Object.hashCode()}.
*
! * @return the hash code value for this attribute set
*/
public int hashCode();
}
< prev index next >