| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> |
| <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 it |
| under the terms of the GNU General Public License version 2 only, as |
| published by the Free Software Foundation. Oracle designates this |
| particular file as subject to the "Classpath" exception as provided |
| by Oracle in the LICENSE file that accompanied this code. |
| |
| This code is distributed in the hope that it will be useful, but WITHOUT |
| ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| version 2 for more details (a copy is included in the LICENSE file that |
| accompanied this code). |
| |
| You should have received a copy of the GNU General Public License version |
| 2 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 USA |
| or visit www.oracle.com if you need additional information or have any |
| questions. |
| --> |
| </head> |
| <body bgcolor="white"> |
| Provides classes and interfaces |
| that describe the types of Java<sup><font size="-2">TM</font></sup> Print |
| Service attributes and how they can be collected into attribute sets. |
| <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 specifies |
| these processing instructions with the attribute definitions of the Java |
| Print Service API. |
| <P> |
| The print data and the processing instructions |
| are separate entities. This means that: |
| <ul> |
| <li>You can print the same print data |
| at different times using different processing instructions. |
| <br> |
| For example, you can print a slide presentation |
| on US letter-sized white paper, |
| double-sided, stapled, 20 copies |
| to make handouts for a talk; |
| and you could print the same slide presentation |
| on US letter-sized transparencies, |
| single-sided, one copy |
| to make the actual slides for the talk. |
| <li>You can use the same processing instructions |
| at 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 in |
| which it achieves the results specified by the processing instructions. |
| Representing processing instructions as descriptive items |
| provides more flexibility for implementing print jobs. |
| <h4>Attribute Categories and Values</h4> |
| Each printer has a set of capabilities, such as the ability to print on |
| different 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 to |
| a printer capability and the term <b>attribute value</b> to refer to the value |
| of 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 the |
| attributes describing the characteristics of the print data, such as |
| the document name, and how the print data should be printed, such as |
| double-sided, five copies. If a print job consists of multiple |
| pieces of print data, different pieces might have different processing |
| instructions, such as 8 x 11 inch media for the first document, and |
| 11 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>) and |
| the number of pages printed so far. These pieces of information are also |
| attributes. 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 characteristic |
| of an individual document and the print job settings to be applied to an |
| individual 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 status |
| of a print job. |
| <li><A HREF="PrintServiceAttribute.html">PrintServiceAttribute</A> reports the |
| status of a print service. |
| <li><A HREF="SupportedValuesAttribute.html">SupportedValuesAttribute</A> gives |
| the supported values for another attribute. |
| </ul> |
| Each attribute class |
| implements one or more of these tagging subinterfaces |
| to 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 media |
| attribute 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 attributes |
| are never used on their own |
| but are always aggregated into higher-level attributes. |
| These low-level attribute classes only |
| implement interface <A HREF="Attribute.html">Attribute</A>, |
| not any of the tagging subinterfaces. |
| <P> |
| The Java Print Service API defines a group of |
| standard attribute classes modeled upon the attributes in |
| the Internet Printing Protocol (IPP) version 1.1. The |
| standard attribute classes are in the subpackage |
| javax.print.attribute.standard to keep the actual |
| attribute classes conceptually separate from the generic |
| apparatus 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 to |
| specify a media size of A4 and a landscape orientation. To send more than one |
| processing 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, and |
| the value of the key can only be one of the attribute values that belong |
| to 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 to |
| that category. |
| <LI>No two attributes from the same category can exist in the same set. |
| For example, an attribute collection |
| must not contain both a "one-sided" attribute and a "two-sided" attribute |
| because these two attributes give the printer conflicting instructions. |
| <LI>Only attributes implementing the <code>Attribute</code> interface can |
| be 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 implementation |
| of 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 are |
| five 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 includes |
| one 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 contain |
| the corresponding kind of attribute. |
| <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 compiler |
| should not allow a "copies" attribute value to |
| be used for a "sides" attribute. |
| <li>Some attributes must be represented as a record of several |
| values. 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 frequent |
| comparisons between attribute category objects when adding attributes, |
| finding existing attributes in the same category, and looking |
| up 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 of |
| different attribute categories, there are only a few different types |
| of attribute values. Most attributes can be represented by a small |
| number of data types, such as: integer values, integer ranges, text, |
| or an enumeration of integer values. The type of the attribute value that |
| a category accepts is called the attribute's abstract syntax. To |
| provide consistency and reduce code duplication, the Java Print Service |
| API defines abstract syntax classes to represent each |
| abstract syntax, and these classes are used as the parent of standard |
| attributes whenever possible. The abstract syntax classes are: |
| <ul> |
| <li><a href="EnumSyntax.html">EnumSyntax</a> |
| provides a type-safe enumeration in which enumerated |
| values are represented as singleton objects. Each enumeration |
| singleton is an instance of the enumeration class that wraps a hidden |
| int 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, and |
| includes 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 Resource |
| Indicator. |
| </ul> |
| The abstract syntax classes are independent of the attributes that |
| use them. In fact, applications that have nothing to do with |
| printing can use the abstract syntax classes. Although most of the |
| standard 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 that |
| can be shared by many attribute classes. |
| <p> |
| Each attribute class implements the <code>Attribute</code> interface, either |
| directly or indirectly, to mark it as a printing attribute. An |
| attribute class that can appear in restricted attribute sets in |
| certain 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: |
| <blockquote> |
| <pre> |
| public class Sides |
| extends EnumSyntax |
| implements DocAttribute, PrintRequestAttribute, PrintJobAttribute |
| { |
| public final Object getCategory() |
| { |
| return Sides.class; |
| } |
| ... |
| } |
| </pre> |
| </blockquote> |
| <p> |
| Since every attribute class implements <code>Attribute</code>, every attribute |
| class 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's |
| proprietary capabilities not already supported by the standard |
| attributes. |
| </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 class |
| of <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 attribute |
| class. This attribute class, like the standard attribute classes, |
| implements <code>Attribute</code> or one of its subinterfaces and extends an |
| abstract syntax class. The vendor can either use an existing |
| abstract syntax class or define a new one. The new vendor-defined |
| attribute 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 that |
| client usually specifies. This example demonstrates creating an attribute |
| set of print-request attributes and locating a printer that can |
| print the document according to the specified attributes: |
| <blockquote> |
| <pre> |
| |
| 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) {} |
| } |
| </pre> |
| </blockquote> |
| <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 meaningful |
| interpretation. Usage to the contrary is incorrect coding and may result |
| in a run time exception either immediately or at some later time. |
| IllegalArgumentException and NullPointerException are examples of |
| typical and acceptable run time exceptions for such cases. |
| <P> |
| @since 1.4 |
| </body> |
| </html> |