1 /*
   2  * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /**
  27  * Provides classes and interfaces that describe the types of Java™ Print
  28  * Service attributes and how they can be collected into attribute sets.
  29  *
  30  * <h2>What is an Attribute?</h2>
  31  * When setting up a print job, a client specifies two things: <b>print data</b>
  32  * and <b>processing instructions.</b> The print data is the actual content to
  33  * be printed. The processing instructions tell the printer how to print the
  34  * print data, such as: what media to use, how many copies to print, and whether
  35  * to print on one or both sides of a sheet. The client specifies these
  36  * processing instructions with the attribute definitions of the Java Print
  37  * Service API.
  38  * <p>
  39  * The print data and the processing instructions are separate entities. This
  40  * means that:
  41  * <ul>
  42  *   <li>You can print the same print data at different times using different
  43  *   processing instructions.
  44  *   <br>
  45  *   For example, you can print a slide presentation on US letter-sized white
  46  *   paper, double-sided, stapled, 20 copies to make handouts for a talk; and
  47  *   you could print the same slide presentation on US letter-sized
  48  *   transparencies, single-sided, one copy to make the actual slides for the
  49  *   talk.
  50  *   <li>You can use the same processing instructions at different times to
  51  *   print different data. For example, you could set your default processing
  52  *   instructions to: US letter-sized paper, double sided, stapled. Whenever you
  53  *   print a job, it prints with these settings, unless you explicitly override
  54  *   them.
  55  * </ul>
  56  * The processing instruction does not specify how the print job processes the
  57  * request; each processing instruction is only a description of the results of
  58  * a print job. The print job determines the manner in which it achieves the
  59  * results specified by the processing instructions. Representing processing
  60  * instructions as descriptive items provides more flexibility for implementing
  61  * print jobs.
  62  *
  63  * <h3>Attribute Categories and Values</h3>
  64  * Each printer has a set of capabilities, such as the ability to print on
  65  * different paper sizes or the ability to print more than one copy. Each of the
  66  * capabilities has a range of values. For example, a printer's orientation
  67  * capability might have this range of values: [landscape, portrait]. For each
  68  * print request, the capability is set to one of these values. The Java Print
  69  * Service API uses the term <b>attribute category</b> to refer to a printer
  70  * capability and the term <b>attribute value</b> to refer to the value of the
  71  * capability.
  72  * <p>
  73  * In the Java Print Service API, an attribute category is represented by a Java
  74  * class implementing the <a href="Attribute.html">Attribute</a> interface.
  75  * Attribute values are instances of such a class or one of its subclasses. For
  76  * example, to specify the number of copies, an application constructs an
  77  * instance of the <a href="standard/Copies.html">Copies</a> class with the
  78  * number of desired copies and uses the {@code Copies} instance as part of the
  79  * print request. In this case, the {@code Copies} class represents the
  80  * attribute category, and the {@code Copies} instance represents the attribute
  81  * value.
  82  *
  83  * <h3><a id="role"></a>Attribute Roles</h3>
  84  * When submitting a print job to a printer, the client provides the attributes
  85  * describing the characteristics of the print data, such as the document name,
  86  * and how the print data should be printed, such as double-sided, five copies.
  87  * If a print job consists of multiple pieces of print data, different pieces
  88  * might have different processing instructions, such as 8 x 11 inch media for
  89  * the first document, and 11 x 17 inch media for another document.
  90  * <p>
  91  * Once the printer starts processing the print job, additional information
  92  * about the job becomes available, which might include: the job state (such as
  93  * <i>completed</i> or <i>queued</i>) and the number of pages printed so far.
  94  * These pieces of information are also attributes. Attributes can also describe
  95  * the printer itself, such as: the printer name, the printer location, and the
  96  * number of jobs queued.
  97  * <p>
  98  * The Java Print Service API defines these different kinds of attributes with
  99  * five subinterfaces of {@code Attribute}:
 100  * <ul>
 101  *   <li><a href="DocAttribute.html">DocAttribute</a> specifies a characteristic
 102  *   of an individual document and the print job settings to be applied to an
 103  *   individual document.
 104  *   <li><a href="PrintRequestAttribute.html">PrintRequestAttribute</a>
 105  *   specifies a setting applied to a whole print job and to all the documents
 106  *   in the print job.
 107  *   <li><a href="PrintJobAttribute.html">PrintJobAttribute</a> reports the
 108  *   status of a print job.
 109  *   <li><a href="PrintServiceAttribute.html">PrintServiceAttribute</a> reports
 110  *   the status of a print service.
 111  *   <li><a href="SupportedValuesAttribute.html">SupportedValuesAttribute</a>
 112  *   gives the supported values for another attribute.
 113  * </ul>
 114  * Each attribute class implements one or more of these tagging subinterfaces to
 115  * indicate where the attribute can be used in the API. If an attribute class
 116  * implements multiple tagging subinterfaces, the attribute can be used in
 117  * multiple contexts. For example, the media attribute can apply to one document
 118  * in a print job as a {@code DocAttribute} or to an entire print job as a
 119  * {@code PrintRequestAttribute}. Certain low-level attributes are never used on
 120  * their own but are always aggregated into higher-level attributes. These
 121  * low-level attribute classes only implement interface
 122  * <a href="Attribute.html">Attribute</a>, not any of the tagging subinterfaces.
 123  * <p>
 124  * The Java Print Service API defines a group of standard attribute classes
 125  * modeled upon the attributes in the Internet Printing Protocol (IPP) version
 126  * 1.1. The standard attribute classes are in the subpackage
 127  * {@code javax.print.attribute.standard} to keep the actual attribute classes
 128  * conceptually separate from the generic apparatus defined in package
 129  * {@code javax.print.attribute}.
 130  *
 131  * <h2>Attribute Sets</h2>
 132  * A client usually needs to provide more than one processing instruction when
 133  * submitting a print job. For example, the client might need to specify a media
 134  * size of A4 and a landscape orientation. To send more than one processing
 135  * instruction, the client collects the attributes into an attribute set, which
 136  * the Java Print Service API represents with the
 137  * <a href="AttributeSet.html">AttributeSet</a> interface.
 138  * <p>
 139  * The {@code AttributeSet} interface is similar to the
 140  * {@link java.util.Map Map} interface: it provides a map of
 141  * key to values, in which each key is unique and can contain no more than one
 142  * value. However, the {@code AttributeSet} interface is designed to
 143  * specifically support the needs of the Java Print Service API. An
 144  * {@code AttributeSet} requires that:
 145  * <ol type=1>
 146  *   <li>Each key in an {@code AttributeSet} corresponds to a category, and the
 147  *   value of the key can only be one of the attribute values that belong to the
 148  *   category represented by the key. Thus, unlike a {@code Map}, an
 149  *   {@code AttributeSet} restricts the possible values of a key: an attribute
 150  *   category cannot be set to an attribute value that does not belong to that
 151  *   category.
 152  *   <li>No two attributes from the same category can exist in the same set. For
 153  *   example, an attribute collection must not contain both a "one-sided"
 154  *   attribute and a "two-sided" attribute because these two attributes give the
 155  *   printer conflicting instructions.
 156  *   <li>Only attributes implementing the {@code Attribute} interface can be
 157  *   added to the set.
 158  * </ol>
 159  * The {@code javax.print.attribute} package includes
 160  * <a href="HashAttributeSet.html">HashAttributeSet</a> as a concrete
 161  * implementation of the attribute set interface. {@code HashAttributeSet}
 162  * provides an attribute set based on a hash map. You can use this
 163  * implementation or provide your own implementation of interface
 164  * {@code AttributeSet}.
 165  * <p>
 166  * The Java Print Service API provides four specializations of an attribute set
 167  * that are restricted to contain just one of the four kinds of attributes, as
 168  * discussed in the <a href="#role">Attribute Roles</a> section:
 169  * <ul>
 170  *   <li><a href="DocAttributeSet.html">DocAttributeSet</a>
 171  *   <li><a href="PrintRequestAttributeSet.html">PrintRequestAttributeSet</a>
 172  *   <li><a href="PrintJobAttributeSet.html"> PrintJobAttributeSet</a>
 173  *   <li><a href="PrintServiceAttributeSet.html">PrintServiceAttributeSet</a>
 174  * </ul>
 175  * Notice that only four kinds of attribute sets are listed here, but there are
 176  * five kinds of attributes. Interface
 177  * <a href="SupportedValuesAttribute.html">SupportedValuesAttribute</a> denotes
 178  * an attribute that gives the supported values for another attribute.
 179  * Supported-values attributes are never aggregated into attribute sets, so
 180  * there is no attribute set subinterface defined for them.
 181  * <p>
 182  * In some contexts, an attribute set is read-only, which means that the client
 183  * is only allowed to examine an attribute set's contents but not change them.
 184  * In other contexts, the attribute set is read-write, which means that the
 185  * client is allowed both to examine and to change an attribute set's contents.
 186  * For a read-only attribute set, calling a mutating operation throws an
 187  * {@code UnmodifiableSetException}.
 188  * <p>
 189  * Package {@code javax.print.attribute} includes one concrete implementation of
 190  * each of the attribute set subinterfaces:
 191  * <ul>
 192  *   <li><a href="HashDocAttributeSet.html"> HashDocAttributeSet</a>
 193  *   <li><a href="HashPrintRequestAttributeSet.html">
 194  *   HashPrintRequestAttributeSet</a>,
 195  *   <li><a href="HashPrintJobAttributeSet.html">HashPrintJobAttributeSet</a>,
 196  *   <li><a href="HashPrintServiceAttributeSet.html">
 197  *   HashPrintServiceAttributeSet</a>.
 198  * </ul>
 199  * All of these classes extend
 200  * <a href="HashAttributeSet.html">HashAttributeSet</a> and enforce the
 201  * restriction that the attribute set is only allowed to contain the
 202  * corresponding kind of attribute.
 203  *
 204  * <h2>Attribute Class Design</h2>
 205  * An attribute value is a small, atomic data item, such as an integer or an
 206  * enumerated value. The Java Print Service API does not use primitive data
 207  * types, such as int, to represent attribute values for these reasons:
 208  * <ul>
 209  *   <li>Primitive data types are not type-safe. For example, a compiler should
 210  *   not allow a "copies" attribute value to be used for a "sides" attribute.
 211  *   <li>Some attributes must be represented as a record of several values. One
 212  *   example is printer resolution, which requires two numbers, such as 600 and
 213  *   300 representing 600 x 300 dpi.
 214  * </ul>
 215  * For type-safety and to represent all attributes uniformly, the Java Print
 216  * Service API defines each attribute category as a class, such as class
 217  * {@code Copies}, class <a href="standard/Sides.html">Sides</a>, and class
 218  * <a href="standard/PrinterResolution.html">PrinterResolution</a>. Each
 219  * attribute class wraps one or more primitive data items containing the
 220  * attribute's value. Attribute set operations perform frequent comparisons
 221  * between attribute category objects when adding attributes, finding existing
 222  * attributes in the same category, and looking up an attribute given its
 223  * category. Because an attribute category is represented by a class, fast
 224  * attribute-value comparisons can be performed with the {@code Class.equals}
 225  * method.
 226  * <p>
 227  * Even though the Java Print Service API includes a large number of different
 228  * attribute categories, there are only a few different types of attribute
 229  * values. Most attributes can be represented by a small number of data types,
 230  * such as: integer values, integer ranges, text, or an enumeration of integer
 231  * values. The type of the attribute value that a category accepts is called the
 232  * attribute's abstract syntax. To provide consistency and reduce code
 233  * duplication, the Java Print Service API defines abstract syntax classes to
 234  * represent each abstract syntax, and these classes are used as the parent of
 235  * standard attributes whenever possible. The abstract syntax classes are:
 236  * <ul>
 237  *   <li><a href="EnumSyntax.html">EnumSyntax</a> provides a type-safe
 238  *   enumeration in which enumerated values are represented as singleton
 239  *   objects. Each enumeration singleton is an instance of the enumeration class
 240  *   that wraps a hidden int value.
 241  *   <li><a href="IntegerSyntax.html">IntegerSyntax</a> is the abstract syntax
 242  *   for integer-valued attributes.
 243  *   <li><a href="TextSyntax.html">TextSyntax</a> is the abstract syntax for
 244  *   text-valued attributes, and includes a locale giving the text string's
 245  *   natural language.
 246  *   <li><a href="SetOfIntegerSyntax.html">SetOfIntegerSyntax</a> is the
 247  *   abstract syntax for attributes representing a range or set of integers
 248  *   <li><a href="ResolutionSyntax.html">ResolutionSyntax</a> is the abstract
 249  *   syntax for attributes representing resolution values, such as 600x300
 250  *   dpi.
 251  *   <li><a href="Size2DSyntax.html">Size2DSyntax</a> is the abstract syntax for
 252  *   attributes representing a two-dimensional size, such as a paper size of
 253  *   8.5 x 11 inches.
 254  *   <li><a href="DateTimeSyntax.html">DateTimeSyntax</a> is the abstract syntax
 255  *   for attributes whose value is a date and time.
 256  *   <li><a href="URISyntax.html">URISyntax</a> is the abstract syntax for
 257  *   attributes whose value is a Uniform Resource Indicator.
 258  * </ul>
 259  * The abstract syntax classes are independent of the attributes that use them.
 260  * In fact, applications that have nothing to do with printing can use the
 261  * abstract syntax classes. Although most of the standard attribute classes
 262  * extend one of the abstract syntax classes, no attribute class is required to
 263  * extend one of these classes. The abstract syntax classes merely provide a
 264  * convenient implementation that can be shared by many attribute classes.
 265  * <p>
 266  * Each attribute class implements the {@code Attribute} interface, either
 267  * directly or indirectly, to mark it as a printing attribute. An attribute
 268  * class that can appear in restricted attribute sets in certain contexts also
 269  * implements one or more subinterfaces of {@code Attribute}. Most attribute
 270  * classes also extend the appropriate abstract syntax class to get the
 271  * implementation. Consider the {@code Sides} attribute class:
 272  * <blockquote>
 273  * <pre>{@code
 274  * public class Sides
 275  *     extends EnumSyntax
 276  *     implements DocAttribute, PrintRequestAttribute, PrintJobAttribute
 277  * {
 278  *     public final Object getCategory()
 279  *     {
 280  *         return Sides.class;
 281  *     }
 282  * ...
 283  * }}
 284  * </pre>
 285  * </blockquote>
 286  * <p>
 287  * Since every attribute class implements {@code Attribute}, every attribute
 288  * class must provide an implementation for the
 289  * {@link javax.print.attribute.Attribute#getCategory() getCategory} method,
 290  * which returns the attribute category. In the case of {@code Sides}, the
 291  * {@code getCategory} method returns {@code Sides.class}. The
 292  * {@code getCategory} method is final to ensure that any vendor-defined
 293  * subclasses of a standard attribute class appear in the same category. Every
 294  * attribute object is immutable once constructed so that attribute object
 295  * references can be passed around freely. To get a different attribute value,
 296  * construct a different attribute object.
 297  *
 298  * <h2>Attribute Vendors</h2>
 299  * The Java Print Service API is designed so that vendors can:
 300  * <ul>
 301  *   <li>define new vendor-specific values for any standard attribute defined in
 302  *   <a href="standard/package-summary.html">javax.print.attribute.standard</a>.
 303  *   <li>define new attribute categories representing the vendor printer's
 304  *   proprietary capabilities not already supported by the standard attributes.
 305  * </ul>
 306  * To define a new value for an attribute, a client can construct instances of
 307  * such attributes with arbitrary values at runtime. However, an enumerated
 308  * attribute using an abstract syntax class of {@code EnumSyntax} specifies all
 309  * the possible attribute values at compile time as singleton instances of the
 310  * attribute class. This means that new enumerated values cannot be constructed
 311  * at run time. To define new vendor-specific values for a standard enumerated
 312  * attribute, the vendor must define a new attribute class specifying the new
 313  * singleton instances. To ensure that the new attribute values fall in the same
 314  * category as the standard attribute values, the new attribute class must be a
 315  * subclass of the standard attribute class.
 316  * <p>
 317  * To define a new attribute category, a vendor defines a new attribute class.
 318  * This attribute class, like the standard attribute classes, implements
 319  * {@code Attribute} or one of its subinterfaces and extends an abstract syntax
 320  * class. The vendor can either use an existing abstract syntax class or define
 321  * a new one. The new vendor-defined attribute can be used wherever an
 322  * {@code Attribute} is used, such as in an {@code AttributeSet}.
 323  *
 324  * <h2>Using Attributes</h2>
 325  * A typical printing application uses the {@code PrintRequestAttributeSet}
 326  * because print-request attributes are the types of attributes that client
 327  * usually specifies. This example demonstrates creating an attribute set of
 328  * print-request attributes and locating a printer that can print the document
 329  * according to the specified attributes:
 330  * <blockquote>
 331  * <pre>{@code
 332  * FileInputStream psStream;
 333  * try {
 334  *     psstream = new FileInputStream("file.ps");
 335  * } catch (FileNotFoundException ffne) {
 336  * }
 337  * if (psstream == null) {
 338  *     return;
 339  * }
 340  * //Set the document type. See the DocFlavor documentation for
 341  * //more information.
 342  * DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
 343  * Doc myDoc = new SimpleDoc(pstream, psInFormat, null);
 344  * PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
 345  * aset.add(new Copies(5));
 346  * aset.add(MediaSize.A4);
 347  * aset.add(Sides.DUPLEX);
 348  * PrintService[] services =
 349  *     PrintServiceLookup.lookupPrintServices(psInFormat, aset);
 350  * if (services.length > 0) {
 351  *     DocPrintJob job = services[0].createPrintJob();
 352  *     try {
 353  *         job.print(myDoc, aset);
 354  *     } catch (PrintException pe) {}
 355  * }
 356  * }</pre>
 357  * </blockquote>
 358  * <p>
 359  * Please note: In the {@code javax.print} APIs, a {@code null} reference
 360  * parameter to methods is incorrect unless explicitly documented on the method
 361  * as having a meaningful interpretation. Usage to the contrary is incorrect
 362  * coding and may result in a run time exception either immediately or at some
 363  * later time. {@code IllegalArgumentException} and {@code NullPointerException}
 364  * are examples of typical and acceptable run time exceptions for such cases.
 365  *
 366  * @since 1.4
 367  */
 368 package javax.print.attribute;