| J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | <html> |
| 2 | <head> |
| 3 | <title>javax.print.attribute.standard package</title> |
| 4 | <!-- |
| 5 | Copyright 2000-2003 Sun Microsystems, Inc. All Rights Reserved. |
| 6 | DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| 7 | |
| 8 | This code is free software; you can redistribute it and/or modify it |
| 9 | under the terms of the GNU General Public License version 2 only, as |
| 10 | published by the Free Software Foundation. Sun designates this |
| 11 | particular file as subject to the "Classpath" exception as provided |
| 12 | by Sun in the LICENSE file that accompanied this code. |
| 13 | |
| 14 | This code is distributed in the hope that it will be useful, but WITHOUT |
| 15 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 16 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| 17 | version 2 for more details (a copy is included in the LICENSE file that |
| 18 | accompanied this code). |
| 19 | |
| 20 | You should have received a copy of the GNU General Public License version |
| 21 | 2 along with this work; if not, write to the Free Software Foundation, |
| 22 | Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| 23 | |
| 24 | Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 25 | CA 95054 USA or visit www.sun.com if you need additional information or |
| 26 | have any questions. |
| 27 | --> |
| 28 | </head> |
| 29 | <body bgcolor="white"> |
| 30 | Package javax.print.attribute.standard |
| 31 | contains classes for specific printing attributes. |
| 32 | The parent package, |
| 33 | <A HREF="../package-summary.html"> |
| 34 | javax.print.attribute</A>, |
| 35 | provides classes and interfaces that describe the types of Java |
| 36 | Print Service attributes and how they can be collected into attribute |
| 37 | sets. |
| 38 | <P> |
| 39 | An attribute represents a printing feature |
| 40 | that a print service can provide. |
| 41 | For each attribute, |
| 42 | a print service either does or does not support the attribute. |
| 43 | For each possible value of a supported attribute, |
| 44 | a print service either does or does not support the value. |
| 45 | <P> |
| 46 | The API requires every print service |
| 47 | to support certain attributes; |
| 48 | other attributes are optional |
| 49 | and the service can choose whether or not to support them. |
| 50 | Each attribute has a set of values that it accepts. The API |
| 51 | requires every print service to support certain values for |
| 52 | certain attributes; |
| 53 | other attribute values are optional |
| 54 | and the service can choose whether or not to support them. |
| 55 | These support requirements are recorded in the documentation |
| 56 | for each attribute class. |
| 57 | <P> |
| 58 | Package javax.print.attribute.standard |
| 59 | contains standard printing attributes |
| 60 | and standard printing attribute values |
| 61 | that are widely used in the printing domain. |
| 62 | A print service vendor |
| 63 | can provide new vendor-specific printing attributes |
| 64 | in addition to the standard ones. |
| 65 | A vendor can also provide |
| 66 | vendor-specific extensions (subclasses) |
| 67 | of the standard printing attributes -- |
| 68 | for example, |
| 69 | to provide additional vendor-specific values |
| 70 | for an existing standard attribute. |
| 71 | Of course, |
| 72 | if a vendor wants clients |
| 73 | to be able to use any added or extended attributes, |
| 74 | the vendor must publish the new attribute classes. |
| 75 | <P> |
| 76 | Many of the standard attribute classes extend one of |
| 77 | the abstract syntax classes of the javax.print.attribute package. |
| 78 | These abstract syntax classes each represent a |
| 79 | different type. The <a href="../EnumSyntax.html"> |
| 80 | EnumSyntax</a> class, for example, represents a type-safe |
| 81 | enumeration. The abstract syntax class provides a wrapper for the attribute |
| 82 | value. |
| 83 | <p> |
| 84 | If an attribute class extends <code>EnumSyntax</code>, and the value of the |
| 85 | attribute is an IPP-compatible value, the attribute's <code>toString</code> |
| 86 | method returns the IPP string representation of the attribute value, such as |
| 87 | "processing-stopped" for the |
| 88 | <a href="JobState.html">JobState</a> attribute. However, because the |
| 89 | <code>EnumSyntax</code> class is extensible, vendors can define their own |
| 90 | attribute values. If an attribute uses the <code>EnumSyntax</code> class |
| 91 | and is set to one of these vendor-defined values then the <code>toString</code> |
| 92 | method will not return the IPP string representation of the value. |
| 93 | <p> |
| 94 | A printing client application |
| 95 | will typically not need to use |
| 96 | all the printing attribute classes |
| 97 | in package javax.print.attribute.standard, |
| 98 | just the ones that pertain to the application. |
| 99 | <P> |
| 100 | The attribute classes in package javax.print.attribute.standard |
| 101 | are based on the Internet Printing Protocol (IPP) attributes |
| 102 | as defined in the Internet RFC document, |
| 103 | <I>RFC 2911 Internet Printing Protocol/1.1: Model and Semantics</I> |
| 104 | dated September 2000. |
| 105 | See <a HREF="http://www.ietf.org/rfc/rfc2911.txt">RFC 2911</a> |
| 106 | for more information. |
| 107 | The descriptive text for each attribute class |
| 108 | was taken largely from the above documents. |
| 109 | The above authors' contribution to the API |
| 110 | is gratefully acknowledged. |
| 111 | |
| 112 | <H3>Attribute Organization</H3> |
| 113 | There are five kinds of printing attributes: |
| 114 | doc attributes, |
| 115 | print request attributes, |
| 116 | print job attributes, |
| 117 | print service attributes, |
| 118 | and supported-values attributes. |
| 119 | |
| 120 | <H4>Doc Attributes</H4> |
| 121 | Doc attributes specify the characteristics of an individual doc |
| 122 | and the print job settings to be applied to an individual doc. |
| 123 | A doc attribute class implements interface |
| 124 | <A HREF="../DocAttribute.html">DocAttribute</A>. |
| 125 | A doc attribute can appear in a |
| 126 | <a href="../DocAttributeSet.html"> |
| 127 | DocAttributeSet</a>. |
| 128 | |
| 129 | <H4>Print Request Attributes</H4> |
| 130 | Print request attributes |
| 131 | specify the settings to be applied to a whole print job |
| 132 | and to all the docs in the print job. |
| 133 | A print request attribute class implements interface |
| 134 | <A HREF="../PrintRequestAttribute.html"> |
| 135 | PrintRequestAttribute</A>. |
| 136 | A print request attribute can appear in a |
| 137 | <a href="../PrintRequestAttributeSet.html"> |
| 138 | PrintRequestAttributeSet</a>. |
| 139 | |
| 140 | <P> |
| 141 | Some attributes are doc attributes |
| 142 | but not print request attributes |
| 143 | and may only be specified at the doc level. |
| 144 | Some attributes are print request attributes |
| 145 | but not doc attributes |
| 146 | and may only be specified at the Print Request level. |
| 147 | Some attributes are both doc attributes |
| 148 | and print request attributes |
| 149 | and may be specified either at the doc level |
| 150 | or at the Print Request level. |
| 151 | <P> |
| 152 | When specified at the doc level, |
| 153 | an attribute applies just to that one doc. |
| 154 | When specified at the Print Request level, |
| 155 | an attribute applies to the whole job, |
| 156 | including all the docs in the job. |
| 157 | However, an attribute specified at the doc level |
| 158 | overrides an attribute in the same category |
| 159 | specified at the Print Request level. |
| 160 | |
| 161 | <H4>Print Job Attributes</H4> |
| 162 | Print job attributes report the status of a Print Job. |
| 163 | A print job attribute class implements interface |
| 164 | <A HREF="../PrintJobAttribute.html">PrintJobAttribute</A>. |
| 165 | A print job attribute |
| 166 | can appear in a <A HREF="../PrintJobAttributeSet.html"> |
| 167 | PrintJobAttributeSet</A>. |
| 168 | <P> |
| 169 | Some attributes are both print request attributes |
| 170 | and print job attributes; |
| 171 | a client may include such attributes in a Print Request |
| 172 | to specify characteristics for the ensuing Print Job, |
| 173 | and those attributes then also appear |
| 174 | in the Print Job's attribute set. |
| 175 | Some attributes are print job attributes |
| 176 | but not print request attributes; |
| 177 | the print service itself |
| 178 | adds these attributes to the Print Job's attribute set. |
| 179 | |
| 180 | <H4>Print Service Attributes</H4> |
| 181 | Print service attributes report the status |
| 182 | of a print service. |
| 183 | A print service attribute class implements interface |
| 184 | <A HREF="../PrintServiceAttribute.html"> |
| 185 | PrintServiceAttribute</A>. |
| 186 | A print service attribute |
| 187 | can appear in a <A HREF="../PrintServiceAttributeSet.html"> |
| 188 | PrintServiceAttributeSet</A>. |
| 189 | |
| 190 | <H4>Supported-Values Attributes</H4> |
| 191 | A supported-value attribute |
| 192 | indicates the legal values for another attribute |
| 193 | that a print service supports. |
| 194 | A supported-values attribute class implements interface |
| 195 | <A HREF="../SupportedValuesAttribute.html"> |
| 196 | SupportedValuesAttribute</A>. |
| 197 | However, supported-values attributes |
| 198 | never appear in attribute sets, |
| 199 | so there is no restricted <A HREF="../AttributeSet.html"> |
| 200 | AttributeSet</A> |
| 201 | subinterface for them. |
| 202 | <P> |
| 203 | |
| 204 | <H4>Attribute Table</H4> |
| 205 | The table below lists all the printing attributes. |
| 206 | The table shows the tagging interfaces |
| 207 | each attribute class implements |
| 208 | in addition to interface <A HREF="../Attribute.html"> |
| 209 | Attribute</A>, |
| 210 | thus indicating how each attribute is used in the API. |
| 211 | For each doc attribute and print request attribute, |
| 212 | the column marked "SupportedValuesAttribute" |
| 213 | lists the supported-values attribute class, if any, |
| 214 | with which a print service |
| 215 | indicates the supported values for that attribute category. |
| 216 | <P> |
| 217 | <TABLE BORDER=1 CELLPADDING=2 CELLSPACING=1 SUMMARY="Lists all printing attributes as described in above text"> |
| 218 | <TR BGCOLOR="#E5E5E5"> |
| 219 | <TH VALIGN="bottom">Attribute Class</TH> |
| 220 | <TH VALIGN="bottom">Doc<BR>Attribute</TH> |
| 221 | <TH VALIGN="bottom">Print<BR>Request<BR>Attribute</TH> |
| 222 | <TH VALIGN="bottom">Print<BR>Job<BR>Attribute</TH> |
| 223 | <TH VALIGN="bottom">Print<BR>Service<BR>Attribute</TH> |
| 224 | <TH VALIGN="bottom">SupportedValuesAttribute</TH> |
| 225 | </TR> |
| 226 | <TR><TD><A HREF="Compression.html">Compression</A></TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD></TR> |
| 227 | <TR><TD><A HREF="DocumentName.html">DocumentName</A></TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD></TR> |
| 228 | <TR><TD><A HREF="Chromaticity.html">Chromaticity</A></TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 229 | <TR><TD><A HREF="Copies.html">Copies</A></TD><TD> </TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD><A HREF="CopiesSupported.html">CopiesSupported</A></TD></TR> |
| 230 | <TR><TD><A HREF="Finishings.html">Finishings</A></TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 231 | <TR><TD><A HREF="JobHoldUntil.html">JobHoldUntil</A></TD><TD> </TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 232 | <TR><TD><A HREF="JobImpressions.html">JobImpressions</A></TD><TD> </TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD><A HREF="JobImpressionsSupported.html">JobImpressionsSupported</A></TD></TR> |
| 233 | <TR><TD><A HREF="JobKOctets.html">JobKOctets</A></TD><TD> </TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD><A HREF="JobKOctetsSupported.html">JobKOctetsSupported</A></TD></TR> |
| 234 | <TR><TD><A HREF="JobMediaSheets.html">JobMediaSheets</A></TD><TD> </TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD><A HREF="JobMediaSheetsSupported.html">JobMediaSheetsSupported</A></TD></TR> |
| 235 | <TR><TD><A HREF="JobName.html">JobName</A></TD><TD> </TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 236 | <TR><TD><A HREF="JobPriority.html">JobPriority</A></TD><TD> </TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD><A HREF="JobPrioritySupported.html">JobPrioritySupported</A></TD></TR> |
| 237 | <TR><TD><A HREF="JobSheets.html">JobSheets</A></TD><TD> </TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 238 | <TR><TD><A HREF="Media.html">Media</A></TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 239 | <TR><TD><A HREF="MediaSize.html">MediaSize</A></TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD></TR> |
| 240 | <TR><TD><A HREF="MultipleDocumentHandling.html">MultipleDocumentHandling</A></TD><TD> </TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 241 | <TR><TD><A HREF="NumberUp.html">NumberUp</A></TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD><A HREF="NumberUpSupported.html">NumberUpSupported</A></TD></TR> |
| 242 | <TR><TD><A HREF="OrientationRequested.html">OrientationRequested</A></TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 243 | <TR><TD><A HREF="PageRanges.html">PageRanges</A></TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 244 | <TR><TD><A HREF="PresentationDirection.html">PresentationDirection</A></TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 245 | <TR><TD><A HREF="PrinterResolution.html">PrinterResolution</A></TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 246 | <TR><TD><A HREF="PrintQuality.html">PrintQuality</A></TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 247 | <TR><TD><A HREF="RequestingUserName.html">RequestingUserName</A></TD><TD> </TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 248 | <TR><TD><A HREF="SheetCollate.html">SheetCollate</A></TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 249 | <TR><TD><A HREF="Sides.html">Sides</A></TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 250 | <TR><TD><A HREF="DateTimeAtCompleted.html">DateTimeAtCompleted</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 251 | <TR><TD><A HREF="DateTimeAtCreation.html">DateTimeAtCreation</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 252 | <TR><TD><A HREF="DateTimeAtProcessing.html">DateTimeAtProcessing</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 253 | <TR><TD><A HREF="JobImpressionsCompleted.html">JobImpressionsCompleted</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 254 | <TR><TD><A HREF="JobKOctetsProcessed.html">JobKOctetsProcessed</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 255 | <TR><TD><A HREF="JobMediaSheetsCompleted.html">JobMediaSheetsCompleted</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 256 | <TR><TD><A HREF="JobMessageFromOperator.html">JobMessageFromOperator</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 257 | <TR><TD><A HREF="JobOriginatingUserName.html">JobOriginatingUserName</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 258 | <TR><TD><A HREF="JobState.html">JobState</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 259 | <TR><TD><A HREF="JobStateReasons.html">JobStateReasons</A><BR>Contains zero or more --</TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 260 | <TR><TD>-- <A HREF="JobStateReason.html">JobStateReason</A></TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD></TR> |
| 261 | <TR><TD><A HREF="NumberOfDocuments.html">NumberOfDocuments</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 262 | <TR><TD><A HREF="NumberOfInterveningJobs.html">NumberOfInterveningJobs</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 263 | <TR><TD><A HREF="OutputDeviceAssigned.html">OutputDeviceAssigned</A></TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD><TD> </TD></TR> |
| 264 | <TR><TD><A HREF="ColorSupported.html">ColorSupported</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 265 | <TR><TD><A HREF="PagesPerMinute.html">PagesPerMinute</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 266 | <TR><TD><A HREF="PagesPerMinuteColor.html">PagesPerMinuteColor</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 267 | <TR><TD><A HREF="PDLOverrideSupported.html">PDLOverrideSupported</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 268 | <TR><TD><A HREF="PrinterIsAcceptingJobs.html">PrinterIsAcceptingJobs</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 269 | <TR><TD><A HREF="PrinterInfo.html">PrinterInfo</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 270 | <TR><TD><A HREF="PrinterLocation.html">PrinterLocation</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 271 | <TR><TD><A HREF="PrinterMessageFromOperator.html">PrinterMessageFromOperator</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 272 | <TR><TD><A HREF="PrinterMakeAndModel.html">PrinterMakeAndModel</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 273 | <TR><TD><A HREF="PrinterMoreInfo.html">PrinterMoreInfo</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 274 | <TR><TD><A HREF="PrinterMoreInfoManufacturer.html">PrinterMoreInfoManufacturer</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 275 | <TR><TD><A HREF="PrinterName.html">PrinterName</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 276 | <TR><TD><A HREF="PrinterState.html">PrinterState</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 277 | <TR><TD><A HREF="PrinterStateReasons.html">PrinterStateReasons</A><BR>Contains zero or more --</TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 278 | <TR><TD>-- <A HREF="PrinterStateReason.html">PrinterStateReason</A></TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD></TR> |
| 279 | <TR><TD>-- <A HREF="Severity.html">Severity</A></TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD></TR> |
| 280 | <TR><TD><A HREF="QueuedJobCount.html">QueuedJobCount</A></TD><TD> </TD><TD> </TD><TD> </TD><TD ALIGN="center">X</TD><TD> </TD></TR> |
| 281 | <TR><TD><A HREF="ReferenceUriSchemesSupported.html">ReferenceUriSchemesSupported</A></TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD><TD> </TD></TR> |
| 282 | </TABLE> |
| 283 | <P> |
| 284 | Please note: In the javax.print APIs, a null reference parameter to methods |
| 285 | is incorrect unless explicitly documented on the method as having a meaningful |
| 286 | interpretation. Usage to the contrary is incorrect coding and may result |
| 287 | in a run time exception either immediately or at some later time. |
| 288 | IllegalArgumentException and NullPointerException are examples of |
| 289 | typical and acceptable run time exceptions for such cases. |
| 290 | <P> |
| 291 | @since 1.4 |
| 292 | </body> |
| 293 | </html> |