2362N/ACopyright (c) 2000, 2003, Oracle and/or its affiliates. All rights reserved. 0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/AThis code is free software; you can redistribute it and/or modify it 0N/Aunder the terms of the GNU General Public License version 2 only, as 2362N/Apublished by the Free Software Foundation. Oracle designates this 0N/Aparticular file as subject to the "Classpath" exception as provided 2362N/Aby Oracle in the LICENSE file that accompanied this code. 0N/AThis code is distributed in the hope that it will be useful, but WITHOUT 0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/Aversion 2 for more details (a copy is included in the LICENSE file that 0N/Aaccompanied this code). 0N/AYou should have received a copy of the GNU General Public License version 0N/A2 along with this work; if not, write to the Free Software Foundation, 0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<
body bgcolor="white">
0N/AProvides classes and interfaces
0N/Athat describe the types of Java<
sup><
font size="-2">TM</
font></
sup> Print
0N/AService attributes and how they can be collected into attribute sets.
0N/A<
H3>What is an Attribute?</
H3>
0N/AWhen setting up a print job,
0N/Aa client specifies two things:
0N/A<
B>print data</
B> and <
B>processing instructions.</
B>
0N/AThe print data is the actual content to be printed.
0N/AThe processing instructions tell the printer how to print the print data,
0N/Asuch as: what media to use, how many copies to print, and
0N/Awhether to print on one or both sides of a sheet. The client specifies
0N/Athese processing instructions with the attribute definitions of the Java
0N/AThe print data and the processing instructions
0N/Aare separate entities. This means that:
0N/A<
li>You can print the same print data
0N/Aat different times using different processing instructions.
0N/AFor example, you can print a slide presentation
0N/Aon US letter-sized white paper,
0N/Adouble-sided, stapled, 20 copies
0N/Ato make handouts for a talk;
0N/Aand you could print the same slide presentation
0N/Aon US letter-sized transparencies,
0N/Asingle-sided, one copy
0N/Ato make the actual slides for the talk.
0N/A<
li>You can use the same processing instructions
0N/Aat different times to print different data.
0N/AFor example, you could set your default processing
0N/Ainstructions to: US letter-sized paper, double sided, stapled.
0N/AWhenever you print a job, it prints with these settings,
0N/Aunless you explicitly override them.
0N/AThe processing instruction does not specify how the print job
0N/Aprocesses the request; each processing instruction is only a description
0N/Aof the results of a print job. The print job determines the manner in
0N/Awhich it achieves the results specified by the processing instructions.
0N/ARepresenting processing instructions as descriptive items
0N/Aprovides more flexibility for implementing print jobs.
0N/A<
h4>Attribute Categories and Values</
h4>
0N/AEach printer has a set of capabilities, such as the ability to print on
0N/Adifferent paper sizes or the ability to print more than one copy. Each of
0N/Athe capabilities has a range of values. For example, a printer's orientation
0N/Acapability might have this range of values: [landscape, portrait].
0N/AFor each print request, the capability is set to one of these values. The
0N/AJava Print Service API uses the term <
b>attribute category</
b> to refer to
0N/Aa printer capability and the term <
b>attribute value</
b> to refer to the value
0N/AIn the Java Print Service API, an attribute category is represented by a Java
0N/AAttribute values are instances of such a class or
0N/Aone of its subclasses. For example, to specify the number of copies, an
0N/Aapplication constructs an instance of the
0N/Anumber of desired copies and uses the <
code>Copies</
code> instance as part of
0N/Athe print request. In this case, the <
code>Copies</
code> class represents the
0N/Aattribute category, and the <
code>Copies</
code> instance represents the
0N/A<
h4><
a name="role"></
a>Attribute Roles</
h4>
0N/AWhen submitting a print job to a printer, the client provides the
0N/Aattributes describing the characteristics of the print data, such as
0N/Athe document name, and how the print data should be printed, such as
0N/Adouble-sided, five copies. If a print job consists of multiple
0N/Apieces of print data, different pieces might have different processing
0N/Ainstructions, such as 8 x 11 inch media for the first document, and
0N/A11 x 17 inch media for another document.
0N/AOnce the printer starts processing the print job,
0N/Aadditional information about the job becomes available, which might include:
0N/Athe job state (such as <
i>completed</
i> or <
i>queued</
i>) and
0N/Athe number of pages printed so far. These pieces of information are also
0N/Aattributes. Attributes can also describe the printer itself, such as:
0N/Athe printer name, the printer location, and the number of jobs queued.
0N/AThe Java Print Service API defines these different kinds of attributes
0N/Awith five subinterfaces of <
code>Attribute</
code>:
0N/Aof an individual document and the print job settings to be applied to an
0N/Aa setting applied to a whole print job and to all the documents in
0N/Astatus of a print service.
0N/Athe supported values for another attribute.
0N/Aimplements one or more of these tagging subinterfaces
0N/Ato indicate where the attribute can be used in the API.
0N/AIf an attribute class implements multiple tagging subinterfaces,
0N/Athe attribute can be used in multiple contexts. For example, the media
0N/Aattribute can apply to one document in a print job as a <
code>DocAttribute</
code>
0N/Aor to an entire print job as a <
code>PrintRequestAttribute</
code>.
0N/ACertain low-level attributes
0N/Aare never used on their own
0N/Abut are always aggregated into higher-level attributes.
0N/AThese low-level attribute classes only
0N/Anot any of the tagging subinterfaces.
0N/AThe Java Print Service API defines a group of
0N/Astandard attribute classes modeled upon the attributes in
0N/Athe Internet Printing Protocol (IPP) version 1.1. The
0N/Astandard attribute classes are in the subpackage
0N/Aattribute classes conceptually separate from the generic
0N/A<
H3>Attribute Sets</
H3>
0N/AA client usually needs to provide more than one processing
0N/Ainstruction when submitting a print job. For example, the client might need to
0N/Aspecify a media size of A4 and a landscape orientation. To send more than one
0N/Aprocessing instruction, the client collects the attributes into an
0N/Aattribute set, which the Java Print Service API represents with the
0N/AThe <
code>AttributeSet</
code> interface is similar to the
0N/Akey to values, in which each key is unique and can contain no more than one
0N/Avalue. However, the <
code>AttributeSet</
code> interface is designed to
0N/Aspecifically support the needs of the Java Print Service API. An
0N/A<
code>AttributeSet</
code> requires that:
0N/A<
LI>Each key in an <
code>AttributeSet</
code> corresponds to a category, and
0N/Athe value of the key can only be one of the attribute values that belong
0N/Ato the category represented by the key. Thus, unlike a <
code>Map</
code>, an
0N/A<
code>AttributeSet</
code> restricts the possible values of a key: an
0N/Aattribute category cannot be set to an attribute value that does not belong to
0N/A<
LI>No two attributes from the same category can exist in the same set.
0N/AFor example, an attribute collection
0N/Amust not contain both a "one-sided" attribute and a "two-sided" attribute
0N/Abecause these two attributes give the printer conflicting instructions.
0N/A<
LI>Only attributes implementing the <
code>Attribute</
code> interface can
0N/Aas a concrete implementation of the attribute set interface.
0N/A<
code>HashAttributeSet</
code> provides an attribute set based on a hash map.
0N/AYou can use this implementation or provide your own implementation
0N/Aof interface <
code>AttributeSet</
code>.
0N/AThe Java Print Service API provides four specializations of an attribute set
0N/Athat are restricted to contain just one of the four kinds of attributes,
0N/Aas discussed in the <
a href="#role">Attribute Roles</
a> section:
0N/ANotice that only four kinds of attribute sets are listed here, but there are
0N/Afive kinds of attributes. Interface
0N/Adenotes an attribute that gives the supported values for another attribute.
0N/ASupported-values attributes are never aggregated into attribute sets,
0N/Aso there is no attribute set subinterface defined for them.
0N/AIn some contexts, an attribute set is read-only, which means that the
0N/Aclient is only allowed to examine an attribute set's
0N/Acontents but not change them. In other contexts, the attribute set is read-write,
0N/Awhich means that the client is allowed both to examine and to change an
0N/Aattribute set's contents. For a read-only attribute set, calling a mutating
0N/Aoperation throws an <
code>UnmodifiableSetException</
code>.
0N/Aone concrete implementation of each of the attribute set subinterfaces:
0N/Aand enforce the restriction that the attribute set is only allowed to contain
0N/Athe corresponding kind of attribute.
0N/A<
H3>Attribute Class Design</
H3>
0N/AAn attribute value is a small, atomic data item,
0N/Asuch as an integer or an enumerated value. The Java Print Service API
0N/Adoes not use primitive data types, such as int, to represent attribute
0N/Avalues for these reasons:
0N/A<
li>Primitive data types are not type-safe. For example, a compiler
0N/Ashould not allow a "copies" attribute value to
0N/Abe used for a "sides" attribute.
0N/A<
li>Some attributes must be represented as a record of several
0N/Avalues. One example is printer resolution, which requires two
0N/Anumbers, such as 600 and 300 representing 600 x 300 dpi.
0N/AFor type-safety and to represent all attributes uniformly, the Java
0N/APrint Service API defines each attribute category as a class, such as
0N/Aattribute class wraps one or more primitive data items containing the
0N/Aattribute's value. Attribute set operations perform frequent
0N/Acomparisons between attribute category objects when adding attributes,
0N/Afinding existing attributes in the same category, and looking
0N/Aup an attribute given its category. Because an attribute category is
0N/Arepresented by a class, fast attribute-value comparisons can be performed
0N/AEven though the Java Print Service API includes a large number of
0N/Adifferent attribute categories, there are only a few different types
0N/Aof attribute values. Most attributes can be represented by a small
0N/Anumber of data types, such as: integer values, integer ranges, text,
0N/Aor an enumeration of integer values. The type of the attribute value that
0N/Aa category accepts is called the attribute's abstract syntax. To
0N/Aprovide consistency and reduce code duplication, the Java Print Service
0N/AAPI defines abstract syntax classes to represent each
0N/Aabstract syntax, and these classes are used as the parent of standard
0N/Aattributes whenever possible. The abstract syntax classes are:
0N/Aprovides a type-safe enumeration in which enumerated
0N/Avalues are represented as singleton objects. Each enumeration
0N/Asingleton is an instance of the enumeration class that wraps a hidden
0N/A is the abstract syntax for integer-valued attributes.
0N/Athe abstract syntax for text-valued attributes, and
0N/Aincludes a locale giving the text string's natural language.
0N/A is the abstract syntax for attributes
0N/Arepresenting a range or set of integers
0N/A is the abstract syntax for attributes representing
0N/A resolution values, such as 600x300 dpi.
0N/A is the abstract syntax for attributes representing a
0N/Atwo-dimensional size, such as a paper size of 8.5 x 11 inches.
0N/A is the abstract syntax for attributes whose value is a date and time.
0N/Aabstract syntax for attributes whose value is a Uniform Resource
0N/AThe abstract syntax classes are independent of the attributes that
0N/Ause them. In fact, applications that have nothing to do with
0N/Aprinting can use the abstract syntax classes. Although most of the
0N/Astandard attribute classes extend one of the abstract syntax classes,
0N/Ano attribute class is required to extend one of these classes. The
0N/Aabstract syntax classes merely provide a convenient implementation that
0N/Acan be shared by many attribute classes.
0N/AEach attribute class implements the <
code>Attribute</
code> interface, either
0N/Adirectly or indirectly, to mark it as a printing attribute. An
0N/Aattribute class that can appear in restricted attribute sets in
0N/Acertain contexts also implements one or more subinterfaces of
0N/A<
code>Attribute</
code>. Most attribute classes also extend the appropriate
0N/Aabstract syntax class to get the implementation. Consider the
0N/A<
code>Sides</
code> attribute class:
0N/A implements DocAttribute, PrintRequestAttribute, PrintJobAttribute
0N/A public final Object getCategory()
0N/ASince every attribute class implements <
code>Attribute</
code>, every attribute
0N/Aclass must provide an implementation for the
0N/Awhich returns the attribute category. In the case of <
code>Sides</
code>, the
0N/A<
code>getCategory</
code> method is final to ensure that any vendor-defined
0N/Asubclasses of a standard attribute class appear in the same category.
0N/AEvery attribute object is immutable once constructed so that attribute object
0N/Areferences can be passed around freely. To get a different attribute
0N/Avalue, construct a different attribute object.
0N/A<
h3>Attribute Vendors</
h3>
0N/AThe Java Print Service API is designed so that vendors can:
0N/A<
li>define new vendor-specific values for any standard attribute
0N/A<
li>define new attribute categories representing the vendor printer's
0N/Aproprietary capabilities not already supported by the standard
0N/ATo define a new value for an attribute, a client can construct
0N/Ainstances of such attributes with arbitrary values at runtime.
0N/AHowever, an enumerated attribute using an abstract syntax class
0N/Aof <
code>EnumSyntax</
code> specifies all the possible attribute values
0N/Aat compile time as singleton instances of the attribute class. This
0N/Ameans that new enumerated values cannot be constructed at run time.
0N/ATo define new vendor-specific values for a standard enumerated
0N/Aattribute, the vendor must define a new attribute class specifying
0N/Athe new singleton instances. To ensure that the new attribute values
0N/Afall in the same category as the standard attribute values, the new
0N/Aattribute class must be a subclass of the standard attribute class.
0N/ATo define a new attribute category, a vendor defines a new attribute
0N/Aclass. This attribute class, like the standard attribute classes,
0N/Aimplements <
code>Attribute</
code> or one of its subinterfaces and extends an
0N/Aabstract syntax class. The vendor can either use an existing
0N/Aabstract syntax class or define a new one. The new vendor-defined
0N/Aattribute can be used wherever an <
code>Attribute</
code> is used, such as in an
0N/A<
code>AttributeSet</
code>.
0N/A<
h3>Using Attributes</
h3>
0N/AA typical printing application uses the <
code>PrintRequestAttributeSet</
code>
0N/Abecause print-request attributes are the types of attributes that
0N/Aclient usually specifies. This example demonstrates creating an attribute
0N/Aset of print-request attributes and locating a printer that can
0N/Aprint the document according to the specified attributes:
0N/AFileInputStream psStream;
0N/A} catch (FileNotFoundException ffne) {
0N/Aif (psstream == null) {
0N/A//Set the document type. See the DocFlavor documentation for
0N/ADoc myDoc = new SimpleDoc(pstream, psInFormat, null);
0N/APrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
0N/APrintService[] services =
0N/A DocPrintJob job = services[0].createPrintJob();
0N/A } catch (PrintException pe) {}
0N/APlease note: In the
javax.print APIs, a null reference parameter to methods
0N/Ais incorrect unless explicitly documented on the method as having a meaningful
0N/Ainterpretation. Usage to the contrary is incorrect coding and may result
0N/Ain a run time exception either immediately or at some later time.
0N/AIllegalArgumentException and NullPointerException are examples of
0N/Atypical and acceptable run time exceptions for such cases.