<html><head><title>javax.print.attribute package</title><!--Copyright (c) 2000, 2003, 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 itunder the terms of the GNU General Public License version 2 only, aspublished by the Free Software Foundation.  Oracle designates thisparticular file as subject to the "Classpath" exception as providedby Oracle in the LICENSE file that accompanied this code. This code is distributed in the hope that it will be useful, but WITHOUTANY WARRANTY; without even the implied warranty of MERCHANTABILITY orFITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public Licenseversion 2 for more details (a copy is included in the LICENSE file thataccompanied this code). You should have received a copy of the GNU General Public License version2 along with this work; if not, write to the Free Software Foundation,Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USAor visit www.oracle.com if you need additional information or have anyquestions.--></head><body bgcolor="white">Provides classes and interfacesthat describe the types of Java<sup><font size="-2">TM</font></sup> PrintService attributes and how they can be collected into attribute sets.<P><H3>What is an Attribute?</H3>When setting up a print job,a client specifies two things:<B>print data</B> and <B>processing instructions.</B>The print data is the actual content to be printed.The processing instructions tell the printer how to print the print data,such as: what media to use, how many copies to print, and whether to print on one or both sides of a sheet.  The client specifiesthese processing instructions with the attribute definitions of the Java Print Service API.<P>The print data and the processing instructionsare separate entities.  This means that:<ul><li>You can print the same print dataat different times using different processing instructions.<br>For example, you can print a slide presentationon US letter-sized white paper,double-sided, stapled, 20 copiesto make handouts for a talk;and you could print the same slide presentationon US letter-sized transparencies,single-sided, one copyto make the actual slides for the talk.<li>You can use the same processing instructionsat different times to print different data.For example, you could set your default processing instructions to: US letter-sized paper, double sided, stapled.Whenever you print a job, it prints with these settings,unless you explicitly override them.</ul><P> The processing instruction does not specify how the print job processes the request; each processing instruction is only a description of the results of a print job.  The print job determines the manner inwhich it achieves the results specified by the processing instructions.Representing processing instructions as descriptive itemsprovides more flexibility for implementing print jobs.<P><h4>Attribute Categories and Values</h4>Each printer has a set of capabilities, such as the ability to print ondifferent paper sizes or the ability to print more than one copy.  Each of the capabilities has a range of values.  For example, a printer's orientation capability might have this range of values: [landscape, portrait]. For each print request, the capability is set to one of these values.  The Java Print Service API uses the term <b>attribute category</b> to refer toa printer capability and the term <b>attribute value</b> to refer to the valueof the capability.<p>In the Java Print Service API, an attribute category is represented by a Java class implementing the <a href="Attribute.html">Attribute</a> interface.  Attribute values are instances of such a class or one of its subclasses.  For example, to specify the number of copies, an application constructs an instance of the <a href="standard/Copies.html">Copies</a> class with the number of desired copies and uses the <code>Copies</code> instance as part of the print request.  In this case, the <code>Copies</code> class represents the attribute category, and the <code>Copies</code> instance represents the attribute value. <h4><a name="role"></a>Attribute Roles</h4> When submitting a print job to a printer, the client provides theattributes describing the characteristics of the print data, such asthe document name, and how the print data should be printed, such asdouble-sided, five copies.  If a print job consists of multiplepieces of print data, different pieces might have different processinginstructions, such as 8 x 11 inch media for the first document, and11 x 17 inch media for another document.<p>Once the printer starts processing the print job,additional information about the job becomes available, which might include:the job state (such as <i>completed</i> or <i>queued</i>) andthe number of pages printed so far.  These pieces of information are alsoattributes.  Attributes can also describe the printer itself, such as:the printer name, the printer location, and the number of jobs queued. <p> The Java Print Service API defines these different kinds of attributes with five subinterfaces of <code>Attribute</code>: <ul><li><A HREF="DocAttribute.html">DocAttribute</A> specifies a characteristicof an individual document and the print job settings to be applied to anindividual document.<li><A HREF="PrintRequestAttribute.html">PrintRequestAttribute</A> specifies a setting applied to a whole print job and to all the documents in the print job. <li><A HREF="PrintJobAttribute.html">PrintJobAttribute</A> reports the statusof a print job.<li><A HREF="PrintServiceAttribute.html">PrintServiceAttribute</A> reports thestatus of a print service.<li><A HREF="SupportedValuesAttribute.html">SupportedValuesAttribute</A> givesthe supported values for another attribute.</ul>Each attribute classimplements one or more of these tagging subinterfacesto indicate where the attribute can be used in the API.If an attribute class implements multiple tagging subinterfaces,the attribute can be used in multiple contexts.  For example, the mediaattribute can apply to one document in a print job as a <code>DocAttribute</code>or to an entire print job as a <code>PrintRequestAttribute</code>.Certain low-level attributesare never used on their ownbut are always aggregated into higher-level attributes.These low-level attribute classes onlyimplement interface <A HREF="Attribute.html">Attribute</A>,not any of the tagging subinterfaces.<P>The Java Print Service API defines a group ofstandard attribute classes modeled upon the attributes inthe Internet Printing Protocol (IPP) version 1.1. Thestandard attribute classes are in the subpackagejavax.print.attribute.standard to keep the actualattribute classes conceptually separate from the genericapparatus defined in package javax.print.attribute.  <H3>Attribute Sets</H3>A client usually needs to provide more than one processing instruction when submitting a print job.  For example, the client might need tospecify a media size of A4 and a landscape orientation.  To send more than oneprocessing instruction, the client collects the attributes into an attribute set, which the Java Print Service API represents with the <a href="AttributeSet.html">AttributeSet</a> interface.<p>The <code>AttributeSet</code> interface is similar to the <a href="../../../java/util/Map.html">Map</a> interface: it provides a map of key to values, in which each key is unique and can contain no more than one value.  However, the <code>AttributeSet</code> interface is designed to specifically support the needs of the Java Print Service API.  An <code>AttributeSet</code> requires that:<OL TYPE=1><LI>Each key in an <code>AttributeSet</code> corresponds to a category, andthe value of the key can only be one of the attribute values that belongto the category represented by the key.  Thus, unlike a <code>Map</code>, an <code>AttributeSet</code> restricts the possible values of a key: an attribute category cannot be set to an attribute value that does not belong tothat category.<LI>No two attributes from the same category can exist in the same set.For example, an attribute collectionmust not contain both a "one-sided" attribute and a "two-sided" attributebecause these two attributes give the printer conflicting instructions.<LI>Only attributes implementing the <code>Attribute</code> interface canbe added to the set.</OL> <P>The javax.print.attribute package includes <A HREF="HashAttributeSet.html">HashAttributeSet</A>as a concrete implementation of the attribute set interface.<code>HashAttributeSet</code> provides an attribute set based on a hash map.You can use this implementation or provide your own implementationof interface <code>AttributeSet</code>.<p>The Java Print Service API provides four specializations of an attribute set that are restricted to contain just one of the four kinds of attributes, as discussed in the <a href="#role">Attribute Roles</a> section:<ul><li><A HREF="DocAttributeSet.html">DocAttributeSet</A><li><A HREF="PrintRequestAttributeSet.html">PrintRequestAttributeSet</A><li><A HREF="PrintJobAttributeSet.html">PrintJobAttributeSet</A><li><A HREF="PrintServiceAttributeSet.html">PrintServiceAttributeSet</A></ul>Notice that only four kinds of attribute sets are listed here, but there arefive kinds of attributes.  Interface <A HREF="SupportedValuesAttribute.html">SupportedValuesAttribute</A>denotes an attribute that gives the supported values for another attribute.Supported-values attributes are never aggregated into attribute sets,so there is no attribute set subinterface defined for them. <P>In some contexts, an attribute set is read-only, which means that the client is only allowed to examine an attribute set's contents but not change them. In other contexts, the attribute set is read-write,which means that the client is allowed both to examine and to change an attribute set's contents. For a read-only attribute set, calling a mutating operation throws an <code>UnmodifiableSetException</code>. <P>Package javax.print.attribute includesone concrete implementation of each of the attribute set subinterfaces:<ul><li><A HREF="HashDocAttributeSet.html">HashDocAttributeSet</A><li><A HREF="HashPrintRequestAttributeSet.html">HashPrintRequestAttributeSet</A>,<li><A HREF="HashPrintJobAttributeSet.html">HashPrintJobAttributeSet</A>,<li><A HREF="HashPrintServiceAttributeSet.html">HashPrintServiceAttributeSet</A>.</ul>All of these classes extend <A HREF="HashAttributeSet.html">HashAttributeSet</A>and enforce the restriction that the attribute set is only allowed to containthe corresponding kind of attribute.<P><H3>Attribute Class Design</H3>An attribute value is a small, atomic data item,such as an integer or an enumerated value.  The Java Print Service API does not use primitive data types, such as int, to represent attribute values for these reasons:<ul><li>Primitive data types are not type-safe.  For example, a compilershould not allow a "copies" attribute value to be used for a "sides" attribute. <li>Some attributes must be represented as a record of severalvalues.  One example is printer resolution, which requires two numbers, such as 600 and 300 representing 600 x 300 dpi.</ul>For type-safety and to represent all attributes uniformly, the Java Print Service API defines each attribute category as a class, such as class <code>Copies</code>, class <a href="standard/Sides.html">Sides</a>, and class <a href="standard/PrinterResolution.html">PrinterResolution</a>.  Each attribute class wraps one or more primitive data items containing the attribute's value.  Attribute set operations perform frequentcomparisons between attribute category objects when adding attributes,finding existing attributes in the same category, and lookingup an attribute given its category.  Because an attribute category is represented by a class, fast attribute-value comparisons can be performed with the <code>Class.equals</code> method.<p>Even though the Java Print Service API includes a large number ofdifferent attribute categories, there are only a few different typesof attribute values.  Most attributes can be represented by a smallnumber of data types, such as: integer values, integer ranges, text,or an enumeration of integer values.  The type of the attribute value thata category accepts is called the attribute's abstract syntax.  Toprovide consistency and reduce code duplication, the Java Print ServiceAPI defines abstract syntax classes to represent each abstract syntax, and these classes are used as the parent of standardattributes whenever possible.  The abstract syntax classes are:<ul><li><a href="EnumSyntax.html">EnumSyntax</a> provides a type-safe enumeration in which enumeratedvalues are represented as singleton objects.  Each enumeration singleton is an instance of the enumeration class that wraps a hiddenint value.<li><a href="IntegerSyntax.html">IntegerSyntax</a> is the abstract syntax for integer-valued attributes.<li><a href="TextSyntax.html">TextSyntax</a> is the abstract syntax for text-valued attributes, andincludes a locale giving the text string's natural language.<li><a href="SetOfIntegerSyntax.html">SetOfIntegerSyntax</a> is the abstract syntax for attributes representing a range or set of integers<li><a href="ResolutionSyntax.html">ResolutionSyntax</a> is the abstract syntax for attributes representing resolution values, such as 600x300 dpi.<li><a href="Size2DSyntax.html">Size2DSyntax</a> is the abstract syntax for attributes representing a two-dimensional size, such as a paper size of 8.5 x 11 inches.<li><a href="DateTimeSyntax.html">DateTimeSyntax</a> is the abstract syntax for attributes whose value is a date and time.<li><a href="URISyntax.html">URISyntax</a> is the abstract syntax for attributes whose value is a Uniform ResourceIndicator.</ul>The abstract syntax classes are independent of the attributes thatuse them.  In fact, applications that have nothing to do withprinting can use the abstract syntax classes.  Although most of thestandard attribute classes extend one of the abstract syntax classes, no attribute class is required to extend one of these classes.  The abstract syntax classes merely provide a convenient implementation thatcan be shared by many attribute classes.<p>Each attribute class implements the <code>Attribute</code> interface, eitherdirectly or indirectly, to mark it as a printing attribute.  Anattribute class that can appear in restricted attribute sets incertain contexts also implements one or more subinterfaces of <code>Attribute</code>.  Most attribute classes also extend the appropriate abstract syntax class to get the implementation.  Consider the <code>Sides</code> attribute class:<pre><blockquote>public class Sides  extends EnumSyntax  implements DocAttribute, PrintRequestAttribute, PrintJobAttribute  {  public final Object getCategory()    {    return Sides.class;    }  ...  }</blockquote>  </pre><p>Since every attribute class implements <code>Attribute</code>, every attributeclass must provide an implementation for the {@link javax.print.attribute.Attribute#getCategory() getCategory} method,which returns the attribute category.  In the case of <code>Sides</code>, the<code>getCategory</code> method returns <code>Sides.class</code>.  The <code>getCategory</code> method is final to ensure that any vendor-defined subclasses of a standard attribute class appear in the same category.  Every attribute object is immutable once constructed so that attribute object references can be passed around freely.  To get a different attribute value, construct a different attribute object.   <h3>Attribute Vendors</h3> The Java Print Service API is designed so that vendors can:<ul><li>define new vendor-specific values for any standard attribute defined in <a href="standard/package-summary.html">javax.print.attribute.standard</a>.<li>define new attribute categories representing the vendor printer'sproprietary capabilities not already supported by the standardattributes.</ul>To define a new value for an attribute, a client can construct instances of such attributes with arbitrary values at runtime.However, an enumerated attribute using an abstract syntax classof <code>EnumSyntax</code> specifies all the possible attribute values at compile time as singleton instances of the attribute class.  This means that new enumerated values cannot be constructed at run time.  To define new vendor-specific values for a standard enumerated attribute, the vendor must define a new attribute class specifying the new singleton instances.  To ensure that the new attribute values fall in the same category as the standard attribute values, the new attribute class must be a subclass of the standard attribute class.<p>To define a new attribute category, a vendor defines a new attributeclass.  This attribute class, like the standard attribute classes, implements <code>Attribute</code> or one of its subinterfaces and extends anabstract syntax class.  The vendor can either use an existing abstract syntax class or define a new one.  The new vendor-definedattribute can be used wherever an <code>Attribute</code> is used, such as in an<code>AttributeSet</code>. <h3>Using Attributes</h3> A typical printing application uses the <code>PrintRequestAttributeSet</code>because print-request attributes are the types of attributes thatclient usually specifies.  This example demonstrates creating an attributeset of print-request attributes and locating a printer that canprint the document according to the specified attributes:<p><pre><blockquote> FileInputStream psStream;try {   psstream = new FileInputStream("file.ps");} catch (FileNotFoundException ffne) {}if (psstream == null) {    return;}//Set the document type.  See the DocFlavor documentation for//more information.DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;Doc myDoc = new SimpleDoc(pstream, psInFormat, null);  PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();aset.add(new Copies(5));aset.add(MediaSize.A4);aset.add(Sides.DUPLEX); PrintService[] services = 		PrintServiceLookup.lookupPrintServices(psInFormat, aset);if (services.length > 0) {   DocPrintJob job = services[0].createPrintJob();   try {	job.print(myDoc, aset);   } catch (PrintException pe) {}}</blockquote></pre><P>Please note: In the javax.print APIs, a null reference parameter to methods is incorrect unless explicitly documented on the method as having a meaningfulinterpretation. Usage to the contrary is incorrect coding and may resultin a run time exception either immediately or at some later time.IllegalArgumentException and NullPointerException are examples oftypical and acceptable run time exceptions for such cases.<P>@since 1.4</body></html>