< prev index next >

src/java.desktop/share/classes/javax/print/DocFlavor.java

Print this page




  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 package javax.print;
  27 
  28 import java.io.IOException;
  29 import java.io.ObjectInputStream;
  30 import java.io.ObjectOutputStream;
  31 import java.io.Serializable;
  32 
  33 
  34 /**
  35  * Class {@code DocFlavor} encapsulates an object that specifies the
  36  * format in which print data is supplied to a {@link DocPrintJob}.
  37  * "Doc" is a short, easy-to-pronounce term that means "a piece of print data."
  38  * The print data format, or "doc flavor", consists of two things:
  39  * <UL>
  40  * <LI>
  41  * <B>MIME type.</B> This is a Multipurpose Internet Mail Extensions (MIME)
  42  * media type (as defined in <A HREF="http://www.ietf.org/rfc/rfc2045.txt">RFC
  43  * 2045</A> and <A HREF="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</A>)
  44  * that specifies how the print data is to be interpreted.
  45  * The charset of text data should be the IANA MIME-preferred name, or its
  46  * canonical name if no preferred name is specified. Additionally a few
  47  * historical names supported by earlier versions of the Java platform may
  48  * be recognized.
  49  * See <a href="../../java/lang/package-summary.html#charenc">
  50  * character encodings</a> for more information on the character encodings
  51  * supported on the Java platform.
  52  *
  53  * <LI>
  54  * <B>Representation class name.</B> This specifies the fully-qualified name of
  55  * the class of the object from which the actual print data comes, as returned
  56  * by the {@link java.lang.Class#getName() Class.getName()} method.
  57  * (Thus the class name for {@code byte[]} is {@code "[B"}, for
  58  * {@code char[]} it is {@code "[C"}.)
  59  * </UL>
  60  * <P>
  61  * A {@code DocPrintJob} obtains its print data by means of interface
  62  * {@link Doc Doc}. A {@code Doc} object lets the {@code DocPrintJob}
  63  * determine the doc flavor the client can supply.  A {@code Doc} object
  64  * also lets the {@code DocPrintJob} obtain an instance of the doc flavor's
  65  * representation class, from which the {@code DocPrintJob} then obtains
  66  * the actual print data.
  67  *
  68  * <HR>
  69  * <H3>Client Formatted Print Data</H3>
  70  * There are two broad categories of print data, client formatted print data
  71  * and service formatted print data.
  72  * <P>
  73  * For <B>client formatted print data</B>, the client determines or knows the
  74  * print data format.
  75  * For example the client may have a JPEG encoded image, a URL for
  76  * HTML code, or a disk file containing plain text in some encoding,
  77  * possibly obtained from an external source, and
  78  * requires a way to describe the data format to the print service.
  79  * <p>
  80  * The doc flavor's representation class is a conduit for the JPS
  81  * {@code DocPrintJob} to obtain a sequence of characters or
  82  * bytes from the client. The
  83  * doc flavor's MIME type is one of the standard media types telling how to
  84  * interpret the sequence of characters or bytes. For a list of standard media
  85  * types, see the Internet Assigned Numbers Authority's (IANA's) <A
  86  * HREF="http://www.iana.org/assignments/media-types/">Media Types
  87  * Directory</A>. Interface {@link Doc Doc} provides two utility operations,
  88  * {@link Doc#getReaderForText() getReaderForText} and
  89  * {@link Doc#getStreamForBytes() getStreamForBytes()}, to help a
  90  * {@code Doc} object's client extract client formatted print data.
  91  * <P>
  92  * For client formatted print data, the print data representation class is
  93  * typically one of the following (although other representation classes are
  94  * permitted):
  95  * <UL>
  96  * <LI>
  97  * Character array ({@code char[]}) -- The print data consists of the
  98  * Unicode characters in the array.
  99  *
 100  * <LI>
 101  * {@code String}  --
 102  * The print data consists of the Unicode characters in the string.
 103  *
 104  * <LI>
 105  * Character stream ({@link java.io.Reader java.io.Reader})
 106  * -- The print data consists of the Unicode characters read from the stream
 107  * up to the end-of-stream.
 108  *
 109  * <LI>
 110  * Byte array ({@code byte[]}) -- The print data consists of the bytes in
 111  * the array. The bytes are encoded in the character set specified by the doc
 112  * flavor's MIME type. If the MIME type does not specify a character set, the
 113  * default character set is US-ASCII.
 114  *
 115  * <LI>
 116  * Byte stream ({@link java.io.InputStream java.io.InputStream}) --
 117  * The print data consists of the bytes read from the stream up to the
 118  * end-of-stream. The bytes are encoded in the character set specified by the
 119  * doc flavor's MIME type. If the MIME type does not specify a character set,
 120  * the default character set is US-ASCII.
 121 
 122  * <LI>
 123  * Uniform Resource Locator ({@link java.net.URL URL})
 124  * -- The print data consists of the bytes read from the URL location.
 125  * The bytes are encoded in the character set specified by the doc flavor's
 126  * MIME type. If the MIME type does not specify a character set, the default
 127  * character set is US-ASCII.
 128  * <P>
 129  * When the representation class is a URL, the print service itself accesses
 130  * and downloads the document directly from its URL address, without involving
 131  * the client. The service may be some form of network print service which
 132  * is executing in a different environment.
 133  * This means you should not use a URL print data flavor to print a
 134  * document at a restricted URL that the client can see but the printer cannot
 135  * see. This also means you should not use a URL print data flavor to print a
 136  * document stored in a local file that is not available at a URL
 137  * accessible independently of the client.
 138  * For example, a file that is not served up by an HTTP server or FTP server.
 139  * To print such documents, let the client open an input stream on the URL
 140  * or file and use an input stream data flavor.
 141  * </UL>
 142  *
 143  * <HR>
 144  * <h3>Default and Platform Encodings</h3>
 145  * <P>
 146  * For byte print data where the doc flavor's MIME type does not include a
 147  * {@code charset} parameter, the Java Print Service instance assumes the
 148  * US-ASCII character set by default. This is in accordance with
 149  * <A HREF="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</A>, which says the
 150  * default character set is US-ASCII. Note that US-ASCII is a subset of
 151  * UTF-8, so in the future this may be widened if a future RFC endorses
 152  * UTF-8 as the default in a compatible manner.
 153  * <p>
 154  * Also note that this is different than the behaviour of the Java runtime
 155  * when interpreting a stream of bytes as text data. That assumes the
 156  * default encoding for the user's locale. Thus, when spooling a file in local
 157  * encoding to a Java Print Service it is important to correctly specify
 158  * the encoding. Developers working in the English locales should
 159  * be particularly conscious of this, as their platform encoding corresponds
 160  * to the default mime charset. By this coincidence that particular
 161  * case may work without specifying the encoding of platform data.
 162  * <p>
 163  * Every instance of the Java virtual machine has a default character encoding
 164  * determined during virtual-machine startup and typically depends upon the
 165  * locale and charset being used by the underlying operating system.
 166  * In a distributed environment there is no guarantee that two VM share
 167  * the same default encoding. Thus clients which want to stream platform
 168  * encoded text data from the host platform to a Java Print Service instance
 169  * must explicitly declare the charset and not rely on defaults.
 170  * <p>
 171  * The preferred form is the official IANA primary name for an encoding.
 172  * Applications which stream text data should always specify the charset
 173  * in the mime type, which necessitates obtaining the encoding of the host
 174  * platform for data (eg files) stored in that platform's encoding.
 175  * A CharSet which corresponds to this and is suitable for use in a
 176  * mime-type for a DocFlavor can be obtained
 177  * from {@link DocFlavor#hostEncoding DocFlavor.hostEncoding}
 178  * This may not always be the primary IANA name but is guaranteed to be
 179  * understood by this VM.
 180  * For common flavors, the pre-defined *HOST DocFlavors may be used.
 181  * <p>
 182  * See <a href="../../java/lang/package-summary.html#charenc">
 183  * character encodings</a> for more information on the character encodings
 184  * supported on the Java platform.
 185  * <HR>

 186  * <h3>Recommended DocFlavors</h3>
 187  * <P>
 188  * The Java Print Service API does not define any mandatorily supported
 189  * DocFlavors.
 190  * However, here are some examples of MIME types that a Java Print Service
 191  * instance might support for client formatted print data.
 192  * Nested classes inside class DocFlavor declare predefined static
 193  * constant DocFlavor objects for these example doc flavors; class DocFlavor's
 194  * constructor can be used to create an arbitrary doc flavor.
 195  * <UL>
 196  * <LI>Preformatted text
 197  * <table class="striped">
 198  * <caption>MIME-Types and their descriptions</caption>
 199  * <thead>
 200  * <TR>
 201  *  <TH>MIME-Type</TH><TH>Description</TH>
 202  * </TR>
 203  * </thead>
 204  * <tbody>
 205  * <TR>
 206  * <TD>{@code "text/plain"}</TD>
 207  * <TD>Plain text in the default character set (US-ASCII)</TD>
 208  * </TR>
 209  * <TR>
 210  * <TD><code>"text/plain; charset=<I>xxx</I>"</code></TD>
 211  * <TD>Plain text in character set <I>xxx</I></TD>
 212  * </TR>
 213  * <TR>
 214  * <TD>{@code "text/html"}</TD>
 215  * <TD>HyperText Markup Language in the default character set (US-ASCII)</TD>
 216  * </TR>
 217  * <TR>
 218  * <TD><code>"text/html; charset=<I>xxx</I>"</code></TD>
 219  * <TD>HyperText Markup Language in character set <I>xxx</I></TD>
 220  * </TR>
 221  * </tbody>
 222  * </TABLE>
 223  * <P>
 224  * In general, preformatted text print data is provided either in a character
 225  * oriented representation class (character array, String, Reader) or in a
 226  * byte oriented representation class (byte array, InputStream, URL).
 227  *
 228  *  <LI>Preformatted page description language (PDL) documents
 229  *
 230  * <table class="striped">
 231  * <caption>MIME-Types and their descriptions</caption>
 232  * <thead>
 233  * <TR>
 234  *  <TH>MIME-Type</TH><TH>Description</TH>
 235  * </TR>
 236  * </thead>
 237  * <tbody>
 238  * <TR>
 239  * <TD>{@code "application/pdf"}</TD>
 240  * <TD>Portable Document Format document</TD>
 241  * </TR>
 242  * <TR>
 243  * <TD>{@code "application/postscript"}</TD>
 244  * <TD>PostScript document</TD>
 245  * </TR>
 246  * <TR>
 247  * <TD>{@code "application/vnd.hp-PCL"}</TD>
 248  * <TD>Printer Control Language document</TD>
 249  * </TR>
 250  * </tbody>
 251  * </TABLE>
 252  * <P>
 253  * In general, preformatted PDL print data is provided in a byte oriented
 254  * representation class (byte array, InputStream, URL).
 255  *
 256  *  <LI>Preformatted images
 257  *
 258  * <table class="striped">
 259  * <caption>MIME-Types and their descriptions</caption>
 260  * <thead>
 261  * <TR>
 262  *  <TH>MIME-Type</TH><TH>Description</TH>
 263  * </TR>
 264  * </thead>
 265  * <tbody>
 266  * <TR>
 267  * <TD>{@code "image/gif"}</TD>
 268  * <TD>Graphics Interchange Format image</TD>
 269  * </TR>
 270  * <TR>
 271  * <TD>{@code "image/jpeg"}</TD>
 272  * <TD>Joint Photographic Experts Group image</TD>
 273  * </TR>
 274  * <TR>
 275  * <TD>{@code "image/png"}</TD>
 276  * <TD>Portable Network Graphics image</TD>
 277  * </TR>
 278  * </tbody>
 279  * </TABLE>
 280  * <P>
 281  * In general, preformatted image print data is provided in a byte oriented
 282  * representation class (byte array, InputStream, URL).
 283  *
 284  *  <LI>Preformatted autosense print data
 285  *
 286  * <table class="striped">
 287  * <caption>MIME-Types and their descriptions</caption>
 288  * <thead>
 289  * <TR>
 290  *  <TH>MIME-Type</TH><TH>Description</TH>
 291  * </TR>
 292  * </thead>
 293  * <tbody>
 294  * <TR>
 295  * <TD>{@code "application/octet-stream"}</TD>
 296  * <TD>The print data format is unspecified (just an octet stream)</TD>
 297  * </TR>
 298  * </tbody>
 299  * </TABLE>
 300  * <P>
 301  * The printer decides how to interpret the print data; the way this
 302  * "autosensing" works is implementation dependent. In general, preformatted
 303  * autosense print data is provided in a byte oriented representation class
 304  * (byte array, InputStream, URL).
 305  * </UL>
 306  *
 307  * <HR>
 308  * <H3>Service Formatted Print Data</H3>
 309  * <P>
 310  * For <B>service formatted print data</B>, the Java Print Service instance
 311  * determines the print data format. The doc flavor's representation class
 312  * denotes an interface whose methods the {@code DocPrintJob} invokes to
 313  * determine the content to be printed -- such as a renderable image
 314  * interface or a Java printable interface.
 315  * The doc flavor's MIME type is the special value
 316  * {@code "application/x-java-jvm-local-objectref"} indicating the client
 317  * will supply a reference to a Java object that implements the interface
 318  * named as the representation class.
 319  * This MIME type is just a placeholder; what's
 320  * important is the print data representation class.
 321  * <P>
 322  * For service formatted print data, the print data representation class is
 323  * typically one of the following (although other representation classes are
 324  * permitted). Nested classes inside class DocFlavor declare predefined static
 325  * constant DocFlavor objects for these example doc flavors; class DocFlavor's
 326  * constructor can be used to create an arbitrary doc flavor.
 327  * <UL>
 328  * <LI>
 329  * Renderable image object -- The client supplies an object that implements
 330  * interface
 331  * {@link java.awt.image.renderable.RenderableImage RenderableImage}. The
 332  * printer calls methods
 333  * in that interface to obtain the image to be printed.
 334  *
 335  * <LI>
 336  * Printable object -- The client supplies an object that implements interface
 337  * {@link java.awt.print.Printable Printable}.
 338  * The printer calls methods in that interface to obtain the pages to be
 339  * printed, one by one.
 340  * For each page, the printer supplies a graphics context, and whatever the
 341  * client draws in that graphics context gets printed.
 342  *
 343  * <LI>
 344  * Pageable object -- The client supplies an object that implements interface
 345  * {@link java.awt.print.Pageable Pageable}. The printer calls
 346  * methods in that interface to obtain the pages to be printed, one by one.
 347  * For each page, the printer supplies a graphics context, and whatever
 348  * the client draws in that graphics context gets printed.
 349  * </UL>
 350  *
 351  * <HR>
 352  *
 353  * <HR>
 354  * <H3>Pre-defined Doc Flavors</H3>
 355  * A Java Print Service instance is not <B><I>required</I></B> to support the
 356  * following print data formats and print data representation classes.  In
 357  * fact, a developer using this class should <b>never</b> assume that a
 358  * particular print service supports the document types corresponding to
 359  * these pre-defined doc flavors.  Always query the print service
 360  * to determine what doc flavors it supports.  However,
 361  * developers who have print services that support these doc flavors are
 362  * encouraged to refer to the predefined singleton instances created here.
 363  * <UL>
 364  * <LI>
 365  * Plain text print data provided through a byte stream. Specifically, the
 366  * following doc flavors are recommended to be supported:
 367  * <BR>·&nbsp;&nbsp;
 368  * {@code ("text/plain", "java.io.InputStream")}
 369  * <BR>·&nbsp;&nbsp;
 370  * {@code ("text/plain; charset=us-ascii", "java.io.InputStream")}
 371  * <BR>·&nbsp;&nbsp;
 372  * {@code ("text/plain; charset=utf-8", "java.io.InputStream")}
 373  *
 374  * <LI>
 375  * Renderable image objects. Specifically, the following doc flavor is
 376  * recommended to be supported:
 377  * <BR>·&nbsp;&nbsp;
 378  * {@code ("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")}
 379  * </UL>
 380  * <P>
 381  * A Java Print Service instance is allowed to support any other doc flavors
 382  * (or none) in addition to the above mandatory ones, at the implementation's
 383  * choice.
 384  * <P>
 385  * Support for the above doc flavors is desirable so a printing client can rely
 386  * on being able to print on any JPS printer, regardless of which doc flavors
 387  * the printer supports. If the printer doesn't support the client's preferred
 388  * doc flavor, the client can at least print plain text, or the client can
 389  * convert its data to a renderable image and print the image.
 390  * <P>
 391  * Furthermore, every Java Print Service instance must fulfill these
 392  * requirements for processing plain text print data:
 393  * <UL>
 394  * <LI>
 395  * The character pair carriage return-line feed (CR-LF) means
 396  * "go to column 1 of the next line."
 397  * <LI>
 398  * A carriage return (CR) character standing by itself means
 399  * "go to column 1 of the next line."
 400  * <LI>
 401  * A line feed (LF) character standing by itself means
 402  * "go to column 1 of the next line."
 403  * </UL>
 404  * <P>
 405  * The client must itself perform all plain text print data formatting not
 406  * addressed by the above requirements.
 407  *
 408  * <H3>Design Rationale</H3>
 409  * <P>
 410  * Class DocFlavor in package javax.print.data is similar to class
 411  * {@link java.awt.datatransfer.DataFlavor DataFlavor}. Class
 412  * {@code DataFlavor}
 413  * is not used in the Java Print Service (JPS) API
 414  * for three reasons which are all rooted in allowing the JPS API to be
 415  * shared by other print services APIs which may need to run on Java profiles
 416  * which do not include all of the Java Platform, Standard Edition.
 417  * <OL TYPE=1>
 418  * <LI>
 419  * The JPS API is designed to be used in Java profiles which do not support
 420  * AWT.
 421  *
 422  * <LI>
 423  * The implementation of class {@code java.awt.datatransfer.DataFlavor}
 424  * does not guarantee that equivalent data flavors will have the same
 425  * serialized representation. DocFlavor does, and can be used in services
 426  * which need this.
 427  *
 428  * <LI>
 429  * The implementation of class {@code java.awt.datatransfer.DataFlavor}
 430  * includes a human presentable name as part of the serialized representation.
 431  * This is not appropriate as part of a service matching constraint.
 432  * </OL>
 433  * <P>
 434  * Class DocFlavor's serialized representation uses the following
 435  * canonical form of a MIME type string. Thus, two doc flavors with MIME types
 436  * that are not identical but that are equivalent (that have the same
 437  * canonical form) may be considered equal.
 438  * <UL>
 439  * <LI> The media type, media subtype, and parameters are retained, but all
 440  *      comments and whitespace characters are discarded.
 441  * <LI> The media type, media subtype, and parameter names are converted to
 442  *      lowercase.
 443  * <LI> The parameter values retain their original case, except a charset
 444  *      parameter value for a text media type is converted to lowercase.
 445  * <LI> Quote characters surrounding parameter values are removed.
 446  * <LI> Quoting backslash characters inside parameter values are removed.
 447  * <LI> The parameters are arranged in ascending order of parameter name.
 448  * </UL>
 449  * <P>
 450  * Class DocFlavor's serialized representation also contains the
 451  * fully-qualified class <I>name</I> of the representation class
 452  * (a String object), rather than the representation class itself
 453  * (a Class object). This allows a client to examine the doc flavors a
 454  * Java Print Service instance supports without having
 455  * to load the representation classes, which may be problematic for
 456  * limited-resource clients.
 457  *
 458  * @author  Alan Kaminsky
 459  */
 460 public class DocFlavor implements Serializable, Cloneable {
 461 



 462     private static final long serialVersionUID = -4512080796965449721L;
 463 
 464     /**
 465      * A String representing the host operating system encoding.
 466      * This will follow the conventions documented in
 467      * <a href="http://www.ietf.org/rfc/rfc2278.txt">
 468      * <i>RFC&nbsp;2278:&nbsp;IANA Charset Registration Procedures</i></a>
 469      * except where historical names are returned for compatibility with
 470      * previous versions of the Java platform.
 471      * The value returned from method is valid only for the VM which
 472      * returns it, for use in a DocFlavor.
 473      * This is the charset for all the "HOST" pre-defined DocFlavors in
 474      * the executing VM.
 475      */
 476     public static final String hostEncoding;
 477 
 478     static {
 479         hostEncoding =
 480             java.security.AccessController.doPrivileged(
 481                   new sun.security.action.GetPropertyAction("file.encoding"));
 482     }
 483 
 484     /**
 485      * MIME type.
 486      */
 487     private transient MimeType myMimeType;
 488 
 489     /**
 490      * Representation class name.

 491      * @serial
 492      */
 493     private String myClassName;
 494 
 495     /**
 496      * String value for this doc flavor. Computed when needed and cached.
 497      */
 498     private transient String myStringValue = null;
 499 
 500 
 501     /**
 502      * Constructs a new doc flavor object from the given MIME type and
 503      * representation class name. The given MIME type is converted into
 504      * canonical form and stored internally.
 505      *
 506      * @param  mimeType   MIME media type string.
 507      * @param  className  Fully-qualified representation class name.
 508      *
 509      * @exception  NullPointerException
 510      *     (unchecked exception) Thrown if {@code mimeType} is null or
 511      *     {@code className} is null.
 512      * @exception  IllegalArgumentException
 513      *     (unchecked exception) Thrown if {@code mimeType} does not
 514      *     obey the syntax for a MIME media type string.
 515      */
 516     public DocFlavor(String mimeType, String className) {
 517         if (className == null) {
 518             throw new NullPointerException();
 519         }
 520         myMimeType = new MimeType (mimeType);
 521         myClassName = className;
 522     }
 523 
 524     /**
 525      * Returns this doc flavor object's MIME type string based on the
 526      * canonical form. Each parameter value is enclosed in quotes.

 527      * @return the mime type
 528      */
 529     public String getMimeType() {
 530         return myMimeType.getMimeType();
 531     }
 532 
 533     /**
 534      * Returns this doc flavor object's media type (from the MIME type).

 535      * @return the media type
 536      */
 537     public String getMediaType() {
 538         return myMimeType.getMediaType();
 539     }
 540 
 541     /**
 542      * Returns this doc flavor object's media subtype (from the MIME type).

 543      * @return the media sub-type
 544      */
 545     public String getMediaSubtype() {
 546         return myMimeType.getMediaSubtype();
 547     }
 548 
 549     /**
 550      * Returns a {@code String} representing a MIME
 551      * parameter.
 552      * Mime types may include parameters which are usually optional.
 553      * The charset for text types is a commonly useful example.
 554      * This convenience method will return the value of the specified
 555      * parameter if one was specified in the mime type for this flavor.
 556      *
 557      * @param paramName the name of the paramater. This name is internally
 558      * converted to the canonical lower case format before performing
 559      * the match.
 560      * @return String representing a mime parameter, or
 561      * null if that parameter is not in the mime type string.
 562      * @exception NullPointerException if paramName is null.
 563      */
 564     public String getParameter(String paramName) {
 565         return myMimeType.getParameterMap().get(paramName.toLowerCase());
 566     }
 567 
 568     /**
 569      * Returns the name of this doc flavor object's representation class.
 570      * @return the name of the representation class.

 571      */
 572     public String getRepresentationClassName() {
 573         return myClassName;
 574     }
 575 
 576     /**
 577      * Converts this {@code DocFlavor} to a string.
 578      *
 579      * @return  MIME type string based on the canonical form. Each parameter
 580      *          value is enclosed in quotes.
 581      *          A "class=" parameter is appended to the
 582      *          MIME type string to indicate the representation class name.
 583      */
 584     public String toString() {
 585         return getStringValue();
 586     }
 587 
 588     /**
 589      * Returns a hash code for this doc flavor object.
 590      */
 591     public int hashCode() {
 592         return getStringValue().hashCode();
 593     }
 594 
 595     /**
 596      * Determines if this doc flavor object is equal to the given object.
 597      * The two are equal if the given object is not null, is an instance
 598      * of {@code DocFlavor}, has a MIME type equivalent to this doc
 599      * flavor object's MIME type (that is, the MIME types have the same media
 600      * type, media subtype, and parameters), and has the same representation
 601      * class name as this doc flavor object. Thus, if two doc flavor objects'
 602      * MIME types are the same except for comments, they are considered equal.
 603      * However, two doc flavor objects with MIME types of "text/plain" and
 604      * "text/plain; charset=US-ASCII" are not considered equal, even though
 605      * they represent the same media type (because the default character
 606      * set for plain text is US-ASCII).
 607      *
 608      * @param  obj  Object to test.
 609      *
 610      * @return  True if this doc flavor object equals {@code obj}, false
 611      *          otherwise.
 612      */
 613     public boolean equals(Object obj) {
 614         return
 615             obj != null &&
 616             obj instanceof DocFlavor &&
 617             getStringValue().equals (((DocFlavor) obj).getStringValue());
 618     }
 619 
 620     /**
 621      * Returns this doc flavor object's string value.


 622      */
 623     private String getStringValue() {
 624         if (myStringValue == null) {
 625             myStringValue = myMimeType + "; class=\"" + myClassName + "\"";
 626         }
 627         return myStringValue;
 628     }
 629 
 630     /**
 631      * Write the instance to a stream (ie serialize the object).
 632      *

 633      * @throws IOException if I/O errors occur while writing to the underlying
 634      * stream
 635      */
 636     private void writeObject(ObjectOutputStream s) throws IOException {
 637 
 638         s.defaultWriteObject();
 639         s.writeObject(myMimeType.getMimeType());
 640     }
 641 
 642     /**
 643      * Reconstitute an instance from a stream (that is, deserialize it).
 644      *

 645      * @throws ClassNotFoundException if the class of a serialized object could
 646      * not be found.
 647      * @throws IOException if I/O errors occur while reading from the underlying
 648      * stream
 649      * @serialData
 650      * The serialised form of a DocFlavor is the String naming the
 651      * representation class followed by the String representing the canonical
 652      * form of the mime type.
 653      */
 654     private void readObject(ObjectInputStream s)
 655         throws ClassNotFoundException, IOException {
 656 
 657         s.defaultReadObject();
 658         myMimeType = new MimeType((String)s.readObject());
 659     }
 660 
 661     /**
 662      * Class DocFlavor.BYTE_ARRAY provides predefined static constant
 663      * DocFlavor objects for example doc flavors using a byte array
 664      * ({@code byte[]}) as the print data representation class.
 665      *
 666      * @author  Alan Kaminsky
 667      */
 668     public static class BYTE_ARRAY extends DocFlavor {
 669 



 670         private static final long serialVersionUID = -9065578006593857475L;
 671 
 672         /**
 673          * Constructs a new doc flavor with the given MIME type and a print
 674          * data representation class name of {@code "[B"} (byte array).
 675          *
 676          * @param  mimeType   MIME media type string.
 677          *
 678          * @exception  NullPointerException
 679          *     (unchecked exception) Thrown if {@code mimeType} is null.
 680          * @exception  IllegalArgumentException
 681          *     (unchecked exception) Thrown if {@code mimeType} does not
 682          *     obey the syntax for a MIME media type string.
 683          */
 684         public BYTE_ARRAY (String mimeType) {
 685             super (mimeType, "[B");
 686         }
 687 
 688         /**
 689          * Doc flavor with MIME type = {@code "text/plain"},
 690          * encoded in the host platform encoding.
 691          * See {@link DocFlavor#hostEncoding hostEncoding}
 692          * Print data representation class name =
 693          * {@code "[B"} (byte array).
 694          */
 695         public static final BYTE_ARRAY TEXT_PLAIN_HOST =
 696             new BYTE_ARRAY ("text/plain; charset="+hostEncoding);
 697 
 698         /**
 699          * Doc flavor with MIME type =
 700          * {@code "text/plain; charset=utf-8"},
 701          * print data representation class name = {@code "[B"} (byte
 702          * array).
 703          */
 704         public static final BYTE_ARRAY TEXT_PLAIN_UTF_8 =
 705             new BYTE_ARRAY ("text/plain; charset=utf-8");
 706 
 707         /**
 708          * Doc flavor with MIME type =
 709          * {@code "text/plain; charset=utf-16"},
 710          * print data representation class name = {@code "[B"} (byte
 711          * array).
 712          */
 713         public static final BYTE_ARRAY TEXT_PLAIN_UTF_16 =
 714             new BYTE_ARRAY ("text/plain; charset=utf-16");
 715 
 716 
 717         /**
 718          * Doc flavor with MIME type =
 719          * {@code "text/plain; charset=utf-16be"}
 720          * (big-endian byte ordering),
 721          * print data representation class name = {@code "[B"} (byte
 722          * array).
 723          */
 724         public static final BYTE_ARRAY TEXT_PLAIN_UTF_16BE =
 725             new BYTE_ARRAY ("text/plain; charset=utf-16be");
 726 
 727         /**
 728          * Doc flavor with MIME type =
 729          * {@code "text/plain; charset=utf-16le"}
 730          * (little-endian byte ordering),
 731          * print data representation class name = {@code "[B"} (byte
 732          * array).
 733          */
 734         public static final BYTE_ARRAY TEXT_PLAIN_UTF_16LE =
 735             new BYTE_ARRAY ("text/plain; charset=utf-16le");
 736 
 737         /**
 738          * Doc flavor with MIME type =
 739          * {@code "text/plain; charset=us-ascii"},
 740          * print data representation class name =
 741          * {@code "[B"} (byte array).
 742          */
 743         public static final BYTE_ARRAY TEXT_PLAIN_US_ASCII =
 744             new BYTE_ARRAY ("text/plain; charset=us-ascii");
 745 
 746 
 747         /**
 748          * Doc flavor with MIME type = {@code "text/html"},
 749          * encoded in the host platform encoding.
 750          * See {@link DocFlavor#hostEncoding hostEncoding}
 751          * Print data representation class name =
 752          * {@code "[B"} (byte array).
 753          */
 754         public static final BYTE_ARRAY TEXT_HTML_HOST =
 755             new BYTE_ARRAY ("text/html; charset="+hostEncoding);
 756 
 757         /**
 758          * Doc flavor with MIME type =
 759          * {@code "text/html; charset=utf-8"},
 760          * print data representation class name = {@code "[B"} (byte
 761          * array).
 762          */
 763         public static final BYTE_ARRAY TEXT_HTML_UTF_8 =
 764             new BYTE_ARRAY ("text/html; charset=utf-8");
 765 
 766         /**
 767          * Doc flavor with MIME type =
 768          * {@code "text/html; charset=utf-16"},
 769          * print data representation class name = {@code "[B"} (byte
 770          * array).
 771          */
 772         public static final BYTE_ARRAY TEXT_HTML_UTF_16 =
 773             new BYTE_ARRAY ("text/html; charset=utf-16");
 774 
 775         /**
 776          * Doc flavor with MIME type =
 777          * {@code "text/html; charset=utf-16be"}
 778          * (big-endian byte ordering),
 779          * print data representation class name = {@code "[B"} (byte
 780          * array).
 781          */
 782         public static final BYTE_ARRAY TEXT_HTML_UTF_16BE =
 783             new BYTE_ARRAY ("text/html; charset=utf-16be");
 784 
 785         /**
 786          * Doc flavor with MIME type =
 787          * {@code "text/html; charset=utf-16le"}
 788          * (little-endian byte ordering),
 789          * print data representation class name = {@code "[B"} (byte
 790          * array).
 791          */
 792         public static final BYTE_ARRAY TEXT_HTML_UTF_16LE =
 793             new BYTE_ARRAY ("text/html; charset=utf-16le");
 794 
 795         /**
 796          * Doc flavor with MIME type =
 797          * {@code "text/html; charset=us-ascii"},
 798          * print data representation class name =
 799          * {@code "[B"} (byte array).
 800          */
 801         public static final BYTE_ARRAY TEXT_HTML_US_ASCII =
 802             new BYTE_ARRAY ("text/html; charset=us-ascii");
 803 
 804 
 805         /**
 806          * Doc flavor with MIME type = {@code "application/pdf"}, print
 807          * data representation class name = {@code "[B"} (byte array).
 808          */
 809         public static final BYTE_ARRAY PDF = new BYTE_ARRAY ("application/pdf");
 810 
 811         /**
 812          * Doc flavor with MIME type = {@code "application/postscript"},
 813          * print data representation class name = {@code "[B"} (byte
 814          * array).
 815          */
 816         public static final BYTE_ARRAY POSTSCRIPT =
 817             new BYTE_ARRAY ("application/postscript");
 818 
 819         /**
 820          * Doc flavor with MIME type = {@code "application/vnd.hp-PCL"},
 821          * print data representation class name = {@code "[B"} (byte
 822          * array).
 823          */
 824         public static final BYTE_ARRAY PCL =
 825             new BYTE_ARRAY ("application/vnd.hp-PCL");
 826 
 827         /**
 828          * Doc flavor with MIME type = {@code "image/gif"}, print data
 829          * representation class name = {@code "[B"} (byte array).
 830          */
 831         public static final BYTE_ARRAY GIF = new BYTE_ARRAY ("image/gif");
 832 
 833         /**
 834          * Doc flavor with MIME type = {@code "image/jpeg"}, print data
 835          * representation class name = {@code "[B"} (byte array).
 836          */
 837         public static final BYTE_ARRAY JPEG = new BYTE_ARRAY ("image/jpeg");
 838 
 839         /**
 840          * Doc flavor with MIME type = {@code "image/png"}, print data
 841          * representation class name = {@code "[B"} (byte array).
 842          */
 843         public static final BYTE_ARRAY PNG = new BYTE_ARRAY ("image/png");
 844 
 845         /**
 846          * Doc flavor with MIME type =
 847          * {@code "application/octet-stream"},
 848          * print data representation class name = {@code "[B"} (byte
 849          * array). The client must determine that data described
 850          * using this DocFlavor is valid for the printer.
 851          */
 852         public static final BYTE_ARRAY AUTOSENSE =
 853             new BYTE_ARRAY ("application/octet-stream");
 854 
 855     }
 856 
 857     /**
 858      * Class DocFlavor.INPUT_STREAM provides predefined static constant
 859      * DocFlavor objects for example doc flavors using a byte stream ({@link
 860      * java.io.InputStream java.io.InputStream}) as the print
 861      * data representation class.
 862      *
 863      * @author  Alan Kaminsky
 864      */
 865     public static class INPUT_STREAM extends DocFlavor {
 866 



 867         private static final long serialVersionUID = -7045842700749194127L;
 868 
 869         /**
 870          * Constructs a new doc flavor with the given MIME type and a print
 871          * data representation class name of
 872          * {@code "java.io.InputStream"} (byte stream).
 873          *
 874          * @param  mimeType   MIME media type string.
 875          *
 876          * @exception  NullPointerException
 877          *     (unchecked exception) Thrown if {@code mimeType} is null.
 878          * @exception  IllegalArgumentException
 879          *     (unchecked exception) Thrown if {@code mimeType} does not
 880          *     obey the syntax for a MIME media type string.
 881          */
 882         public INPUT_STREAM (String mimeType) {
 883             super (mimeType, "java.io.InputStream");
 884         }
 885 
 886         /**
 887          * Doc flavor with MIME type = {@code "text/plain"},
 888          * encoded in the host platform encoding.
 889          * See {@link DocFlavor#hostEncoding hostEncoding}
 890          * Print data representation class name =
 891          * {@code "java.io.InputStream"} (byte stream).
 892          */
 893         public static final INPUT_STREAM TEXT_PLAIN_HOST =
 894             new INPUT_STREAM ("text/plain; charset="+hostEncoding);
 895 
 896         /**
 897          * Doc flavor with MIME type =
 898          * {@code "text/plain; charset=utf-8"},
 899          * print data representation class name =
 900          * {@code "java.io.InputStream"} (byte stream).
 901          */
 902         public static final INPUT_STREAM TEXT_PLAIN_UTF_8 =
 903             new INPUT_STREAM ("text/plain; charset=utf-8");
 904 
 905         /**
 906          * Doc flavor with MIME type =
 907          * {@code "text/plain; charset=utf-16"},
 908          * print data representation class name =
 909          * {@code "java.io.InputStream"} (byte stream).
 910          */
 911         public static final INPUT_STREAM TEXT_PLAIN_UTF_16 =
 912             new INPUT_STREAM ("text/plain; charset=utf-16");
 913 
 914         /**
 915          * Doc flavor with MIME type =
 916          * {@code "text/plain; charset=utf-16be"}
 917          * (big-endian byte ordering),
 918          * print data representation class name =
 919          * {@code "java.io.InputStream"} (byte stream).
 920          */
 921         public static final INPUT_STREAM TEXT_PLAIN_UTF_16BE =
 922             new INPUT_STREAM ("text/plain; charset=utf-16be");
 923 
 924         /**
 925          * Doc flavor with MIME type =
 926          * {@code "text/plain; charset=utf-16le"}
 927          * (little-endian byte ordering),
 928          * print data representation class name =
 929          * {@code "java.io.InputStream"} (byte stream).
 930          */
 931         public static final INPUT_STREAM TEXT_PLAIN_UTF_16LE =
 932             new INPUT_STREAM ("text/plain; charset=utf-16le");
 933 
 934         /**
 935          * Doc flavor with MIME type =
 936          * {@code "text/plain; charset=us-ascii"},
 937          * print data representation class name =
 938          * {@code "java.io.InputStream"} (byte stream).
 939          */
 940         public static final INPUT_STREAM TEXT_PLAIN_US_ASCII =
 941                 new INPUT_STREAM ("text/plain; charset=us-ascii");
 942 
 943         /**
 944          * Doc flavor with MIME type = {@code "text/html"},
 945          * encoded in the host platform encoding.
 946          * See {@link DocFlavor#hostEncoding hostEncoding}
 947          * Print data representation class name =
 948          * {@code "java.io.InputStream"} (byte stream).
 949          */
 950         public static final INPUT_STREAM TEXT_HTML_HOST =
 951             new INPUT_STREAM ("text/html; charset="+hostEncoding);
 952 
 953         /**
 954          * Doc flavor with MIME type =
 955          * {@code "text/html; charset=utf-8"},
 956          * print data representation class name =
 957          * {@code "java.io.InputStream"} (byte stream).
 958          */
 959         public static final INPUT_STREAM TEXT_HTML_UTF_8 =
 960             new INPUT_STREAM ("text/html; charset=utf-8");
 961 
 962         /**
 963          * Doc flavor with MIME type =
 964          * {@code "text/html; charset=utf-16"},
 965          * print data representation class name =
 966          * {@code "java.io.InputStream"} (byte stream).
 967          */
 968         public static final INPUT_STREAM TEXT_HTML_UTF_16 =
 969             new INPUT_STREAM ("text/html; charset=utf-16");
 970 
 971         /**
 972          * Doc flavor with MIME type =
 973          * {@code "text/html; charset=utf-16be"}
 974          * (big-endian byte ordering),
 975          * print data representation class name =
 976          * {@code "java.io.InputStream"} (byte stream).
 977          */
 978         public static final INPUT_STREAM TEXT_HTML_UTF_16BE =
 979             new INPUT_STREAM ("text/html; charset=utf-16be");
 980 
 981         /**
 982          * Doc flavor with MIME type =
 983          * {@code "text/html; charset=utf-16le"}
 984          * (little-endian byte ordering),
 985          * print data representation class name =
 986          * {@code "java.io.InputStream"} (byte stream).
 987          */
 988         public static final INPUT_STREAM TEXT_HTML_UTF_16LE =
 989             new INPUT_STREAM ("text/html; charset=utf-16le");
 990 
 991         /**
 992          * Doc flavor with MIME type =
 993          * {@code "text/html; charset=us-ascii"},
 994          * print data representation class name =
 995          * {@code "java.io.InputStream"} (byte stream).
 996          */
 997         public static final INPUT_STREAM TEXT_HTML_US_ASCII =
 998             new INPUT_STREAM ("text/html; charset=us-ascii");
 999 
1000 
1001         /**
1002          * Doc flavor with MIME type = {@code "application/pdf"}, print
1003          * data representation class name = {@code "java.io.InputStream"}
1004          * (byte stream).
1005          */
1006         public static final INPUT_STREAM PDF = new INPUT_STREAM ("application/pdf");
1007 
1008         /**
1009          * Doc flavor with MIME type = {@code "application/postscript"},
1010          * print data representation class name =
1011          * {@code "java.io.InputStream"} (byte stream).
1012          */
1013         public static final INPUT_STREAM POSTSCRIPT =
1014             new INPUT_STREAM ("application/postscript");
1015 
1016         /**
1017          * Doc flavor with MIME type = {@code "application/vnd.hp-PCL"},
1018          * print data representation class name =
1019          * {@code "java.io.InputStream"} (byte stream).
1020          */
1021         public static final INPUT_STREAM PCL =
1022             new INPUT_STREAM ("application/vnd.hp-PCL");
1023 
1024         /**
1025          * Doc flavor with MIME type = {@code "image/gif"}, print data
1026          * representation class name =
1027          * {@code "java.io.InputStream"} (byte stream).
1028          */
1029         public static final INPUT_STREAM GIF = new INPUT_STREAM ("image/gif");
1030 
1031         /**
1032          * Doc flavor with MIME type = {@code "image/jpeg"}, print data
1033          * representation class name =
1034          * {@code "java.io.InputStream"} (byte stream).
1035          */
1036         public static final INPUT_STREAM JPEG = new INPUT_STREAM ("image/jpeg");
1037 
1038         /**
1039          * Doc flavor with MIME type = {@code "image/png"}, print data
1040          * representation class name =
1041          * {@code "java.io.InputStream"} (byte stream).
1042          */
1043         public static final INPUT_STREAM PNG = new INPUT_STREAM ("image/png");
1044 
1045         /**
1046          * Doc flavor with MIME type =
1047          * {@code "application/octet-stream"},
1048          * print data representation class name =
1049          * {@code "java.io.InputStream"} (byte stream).
1050          * The client must determine that data described
1051          * using this DocFlavor is valid for the printer.
1052          */
1053         public static final INPUT_STREAM AUTOSENSE =
1054             new INPUT_STREAM ("application/octet-stream");
1055 
1056     }
1057 
1058     /**
1059      * Class DocFlavor.URL provides predefined static constant DocFlavor
1060      * objects.
1061      * For example doc flavors using a Uniform Resource Locator ({@link
1062      * java.net.URL java.net.URL}) as the print data
1063      * representation class.
1064      *
1065      * @author  Alan Kaminsky
1066      */
1067     public static class URL extends DocFlavor {




1068         private static final long serialVersionUID = 2936725788144902062L;
1069 
1070         /**
1071          * Constructs a new doc flavor with the given MIME type and a print
1072          * data representation class name of {@code "java.net.URL"}.
1073          *
1074          * @param  mimeType   MIME media type string.
1075          *
1076          * @exception  NullPointerException
1077          *     (unchecked exception) Thrown if {@code mimeType} is null.
1078          * @exception  IllegalArgumentException
1079          *     (unchecked exception) Thrown if {@code mimeType} does not
1080          *     obey the syntax for a MIME media type string.
1081          */
1082         public URL (String mimeType) {
1083             super (mimeType, "java.net.URL");
1084         }
1085 
1086         /**
1087          * Doc flavor with MIME type = {@code "text/plain"},
1088          * encoded in the host platform encoding.
1089          * See {@link DocFlavor#hostEncoding hostEncoding}
1090          * Print data representation class name =
1091          * {@code "java.net.URL"} (byte stream).
1092          */
1093         public static final URL TEXT_PLAIN_HOST =
1094             new URL ("text/plain; charset="+hostEncoding);
1095 
1096         /**
1097          * Doc flavor with MIME type =
1098          * {@code "text/plain; charset=utf-8"},
1099          * print data representation class name =
1100          * {@code "java.net.URL"} (byte stream).
1101          */
1102         public static final URL TEXT_PLAIN_UTF_8 =
1103             new URL ("text/plain; charset=utf-8");
1104 
1105         /**
1106          * Doc flavor with MIME type =
1107          * {@code "text/plain; charset=utf-16"},
1108          * print data representation class name =
1109          * {@code java.net.URL""} (byte stream).
1110          */
1111         public static final URL TEXT_PLAIN_UTF_16 =
1112             new URL ("text/plain; charset=utf-16");
1113 
1114         /**
1115          * Doc flavor with MIME type =
1116          * {@code "text/plain; charset=utf-16be"}
1117          * (big-endian byte ordering),
1118          * print data representation class name =
1119          * {@code "java.net.URL"} (byte stream).
1120          */
1121         public static final URL TEXT_PLAIN_UTF_16BE =
1122             new URL ("text/plain; charset=utf-16be");
1123 
1124         /**
1125          * Doc flavor with MIME type =
1126          * {@code "text/plain; charset=utf-16le"}
1127          * (little-endian byte ordering),
1128          * print data representation class name =
1129          * {@code "java.net.URL"} (byte stream).
1130          */
1131         public static final URL TEXT_PLAIN_UTF_16LE =
1132             new URL ("text/plain; charset=utf-16le");
1133 
1134         /**
1135          * Doc flavor with MIME type =
1136          * {@code "text/plain; charset=us-ascii"},
1137          * print data representation class name =
1138          * {@code "java.net.URL"} (byte stream).
1139          */
1140         public static final URL TEXT_PLAIN_US_ASCII =
1141             new URL ("text/plain; charset=us-ascii");
1142 
1143         /**
1144          * Doc flavor with MIME type = {@code "text/html"},
1145          * encoded in the host platform encoding.
1146          * See {@link DocFlavor#hostEncoding hostEncoding}
1147          * Print data representation class name =
1148          * {@code "java.net.URL"} (byte stream).
1149          */
1150         public static final URL TEXT_HTML_HOST =
1151             new URL ("text/html; charset="+hostEncoding);
1152 
1153         /**
1154          * Doc flavor with MIME type =
1155          * {@code "text/html; charset=utf-8"},
1156          * print data representation class name =
1157          * {@code "java.net.URL"} (byte stream).
1158          */
1159         public static final URL TEXT_HTML_UTF_8 =
1160             new URL ("text/html; charset=utf-8");
1161 
1162         /**
1163          * Doc flavor with MIME type =
1164          * {@code "text/html; charset=utf-16"},
1165          * print data representation class name =
1166          * {@code "java.net.URL"} (byte stream).
1167          */
1168         public static final URL TEXT_HTML_UTF_16 =
1169             new URL ("text/html; charset=utf-16");
1170 
1171         /**
1172          * Doc flavor with MIME type =
1173          * {@code "text/html; charset=utf-16be"}
1174          * (big-endian byte ordering),
1175          * print data representation class name =
1176          * {@code "java.net.URL"} (byte stream).
1177          */
1178         public static final URL TEXT_HTML_UTF_16BE =
1179             new URL ("text/html; charset=utf-16be");
1180 
1181         /**
1182          * Doc flavor with MIME type =
1183          * {@code "text/html; charset=utf-16le"}
1184          * (little-endian byte ordering),
1185          * print data representation class name =
1186          * {@code "java.net.URL"} (byte stream).
1187          */
1188         public static final URL TEXT_HTML_UTF_16LE =
1189             new URL ("text/html; charset=utf-16le");
1190 
1191         /**
1192          * Doc flavor with MIME type =
1193          * {@code "text/html; charset=us-ascii"},
1194          * print data representation class name =
1195          * {@code "java.net.URL"} (byte stream).
1196          */
1197         public static final URL TEXT_HTML_US_ASCII =
1198             new URL ("text/html; charset=us-ascii");
1199 
1200 
1201         /**
1202          * Doc flavor with MIME type = {@code "application/pdf"}, print
1203          * data representation class name = {@code "java.net.URL"}.
1204          */
1205         public static final URL PDF = new URL ("application/pdf");
1206 
1207         /**
1208          * Doc flavor with MIME type = {@code "application/postscript"},
1209          * print data representation class name = {@code "java.net.URL"}.
1210          */
1211         public static final URL POSTSCRIPT = new URL ("application/postscript");
1212 
1213         /**
1214          * Doc flavor with MIME type = {@code "application/vnd.hp-PCL"},
1215          * print data representation class name = {@code "java.net.URL"}.
1216          */
1217         public static final URL PCL = new URL ("application/vnd.hp-PCL");
1218 
1219         /**
1220          * Doc flavor with MIME type = {@code "image/gif"}, print data
1221          * representation class name = {@code "java.net.URL"}.
1222          */
1223         public static final URL GIF = new URL ("image/gif");
1224 
1225         /**
1226          * Doc flavor with MIME type = {@code "image/jpeg"}, print data
1227          * representation class name = {@code "java.net.URL"}.
1228          */
1229         public static final URL JPEG = new URL ("image/jpeg");
1230 
1231         /**
1232          * Doc flavor with MIME type = {@code "image/png"}, print data
1233          * representation class name = {@code "java.net.URL"}.
1234          */
1235         public static final URL PNG = new URL ("image/png");
1236 
1237         /**
1238          * Doc flavor with MIME type =
1239          * {@code "application/octet-stream"},
1240          * print data representation class name = {@code "java.net.URL"}.
1241          *  The client must determine that data described
1242          * using this DocFlavor is valid for the printer.
1243          */
1244         public static final URL AUTOSENSE = new URL ("application/octet-stream");
1245 
1246     }
1247 
1248     /**
1249      * Class DocFlavor.CHAR_ARRAY provides predefined static constant
1250      * DocFlavor objects for example doc flavors using a character array
1251      * ({@code char[]}) as the print data representation class. As such,
1252      * the character set is Unicode.
1253      *
1254      * @author  Alan Kaminsky
1255      */
1256     public static class CHAR_ARRAY extends DocFlavor {
1257 



1258         private static final long serialVersionUID = -8720590903724405128L;
1259 
1260         /**
1261          * Constructs a new doc flavor with the given MIME type and a print
1262          * data representation class name of
1263          * {@code "[C"} (character array).
1264          *
1265          * @param  mimeType  MIME media type string. If it is a text media
1266          *                      type, it is assumed to contain a
1267          *                      {@code "charset=utf-16"} parameter.
1268          *
1269          * @exception  NullPointerException
1270          *     (unchecked exception) Thrown if {@code mimeType} is null.
1271          * @exception  IllegalArgumentException
1272          *     (unchecked exception) Thrown if {@code mimeType} does not
1273          *     obey the syntax for a MIME media type string.
1274          */
1275         public CHAR_ARRAY (String mimeType) {
1276             super (mimeType, "[C");
1277         }
1278 
1279         /**
1280          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16"},
1281          * print data representation class name =
1282          * {@code "[C"} (character array).
1283          */
1284         public static final CHAR_ARRAY TEXT_PLAIN =
1285             new CHAR_ARRAY ("text/plain; charset=utf-16");
1286 
1287         /**
1288          * Doc flavor with MIME type = {@code "text/html; charset=utf-16"},
1289          * print data representation class name =
1290          * {@code "[C"} (character array).
1291          */
1292         public static final CHAR_ARRAY TEXT_HTML =
1293             new CHAR_ARRAY ("text/html; charset=utf-16");
1294 
1295     }
1296 
1297     /**
1298      * Class DocFlavor.STRING provides predefined static constant DocFlavor
1299      * objects for example doc flavors using a string ({@link java.lang.String
1300      * java.lang.String}) as the print data representation class.
1301      * As such, the character set is Unicode.
1302      *
1303      * @author  Alan Kaminsky
1304      */
1305     public static class STRING extends DocFlavor {
1306 



1307         private static final long serialVersionUID = 4414407504887034035L;
1308 
1309         /**
1310          * Constructs a new doc flavor with the given MIME type and a print
1311          * data representation class name of {@code "java.lang.String"}.
1312          *
1313          * @param  mimeType  MIME media type string. If it is a text media
1314          *                      type, it is assumed to contain a
1315          *                      {@code "charset=utf-16"} parameter.
1316          *
1317          * @exception  NullPointerException
1318          *     (unchecked exception) Thrown if {@code mimeType} is null.
1319          * @exception  IllegalArgumentException
1320          *     (unchecked exception) Thrown if {@code mimeType} does not
1321          *     obey the syntax for a MIME media type string.
1322          */
1323         public STRING (String mimeType) {
1324             super (mimeType, "java.lang.String");
1325         }
1326 
1327         /**
1328          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16"},
1329          * print data representation class name =
1330          * {@code "java.lang.String"}.
1331          */
1332         public static final STRING TEXT_PLAIN =
1333             new STRING ("text/plain; charset=utf-16");
1334 
1335         /**
1336          * Doc flavor with MIME type = {@code "text/html; charset=utf-16"},
1337          * print data representation class name =
1338          * {@code "java.lang.String"}.
1339          */
1340         public static final STRING TEXT_HTML =
1341             new STRING ("text/html; charset=utf-16");
1342     }
1343 
1344     /**
1345      * Class DocFlavor.READER provides predefined static constant DocFlavor
1346      * objects for example doc flavors using a character stream ({@link
1347      * java.io.Reader java.io.Reader}) as the print data
1348      * representation class. As such, the character set is Unicode.
1349      *
1350      * @author  Alan Kaminsky
1351      */
1352     public static class READER extends DocFlavor {
1353 



1354         private static final long serialVersionUID = 7100295812579351567L;
1355 
1356         /**
1357          * Constructs a new doc flavor with the given MIME type and a print
1358          * data representation class name of\
1359          * {@code "java.io.Reader"} (character stream).
1360          *
1361          * @param  mimeType  MIME media type string. If it is a text media
1362          *                      type, it is assumed to contain a
1363          *                      {@code "charset=utf-16"} parameter.
1364          *
1365          * @exception  NullPointerException
1366          *     (unchecked exception) Thrown if {@code mimeType} is null.
1367          * @exception  IllegalArgumentException
1368          *     (unchecked exception) Thrown if {@code mimeType} does not
1369          *     obey the syntax for a MIME media type string.
1370          */
1371         public READER (String mimeType) {
1372             super (mimeType, "java.io.Reader");
1373         }
1374 
1375         /**
1376          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16"},
1377          * print data representation class name =
1378          * {@code "java.io.Reader"} (character stream).
1379          */
1380         public static final READER TEXT_PLAIN =
1381             new READER ("text/plain; charset=utf-16");
1382 
1383         /**
1384          * Doc flavor with MIME type = {@code "text/html; charset=utf-16"},
1385          * print data representation class name =
1386          * {@code "java.io.Reader"} (character stream).
1387          */
1388         public static final READER TEXT_HTML =
1389             new READER ("text/html; charset=utf-16");
1390 
1391     }
1392 
1393     /**
1394      * Class DocFlavor.SERVICE_FORMATTED provides predefined static constant
1395      * DocFlavor objects for example doc flavors for service formatted print
1396      * data.
1397      *
1398      * @author  Alan Kaminsky
1399      */
1400     public static class SERVICE_FORMATTED extends DocFlavor {
1401 



1402         private static final long serialVersionUID = 6181337766266637256L;
1403 
1404         /**
1405          * Constructs a new doc flavor with a MIME type of
1406          * {@code "application/x-java-jvm-local-objectref"} indicating
1407          * service formatted print data and the given print data
1408          * representation class name.
1409          *
1410          * @param  className  Fully-qualified representation class name.
1411          *
1412          * @exception  NullPointerException
1413          *     (unchecked exception) Thrown if {@code className} is
1414          *     null.
1415          */
1416         public SERVICE_FORMATTED (String className) {
1417             super ("application/x-java-jvm-local-objectref", className);
1418         }
1419 
1420         /**
1421          * Service formatted print data doc flavor with print data
1422          * representation class name =
1423          * {@code "java.awt.image.renderable.RenderableImage"}
1424          * (renderable image object).
1425          */
1426         public static final SERVICE_FORMATTED RENDERABLE_IMAGE =
1427             new SERVICE_FORMATTED("java.awt.image.renderable.RenderableImage");
1428 
1429         /**
1430          * Service formatted print data doc flavor with print data
1431          * representation class name = {@code "java.awt.print.Printable"}
1432          * (printable object).
1433          */
1434         public static final SERVICE_FORMATTED PRINTABLE =
1435             new SERVICE_FORMATTED ("java.awt.print.Printable");
1436 
1437         /**
1438          * Service formatted print data doc flavor with print data
1439          * representation class name = {@code "java.awt.print.Pageable"}
1440          * (pageable object).
1441          */
1442         public static final SERVICE_FORMATTED PAGEABLE =
1443             new SERVICE_FORMATTED ("java.awt.print.Pageable");
1444 
1445         }
1446 
1447 }


  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 package javax.print;
  27 
  28 import java.io.IOException;
  29 import java.io.ObjectInputStream;
  30 import java.io.ObjectOutputStream;
  31 import java.io.Serializable;
  32 

  33 /**
  34  * Class {@code DocFlavor} encapsulates an object that specifies the format in
  35  * which print data is supplied to a {@link DocPrintJob}. "Doc" is a short,
  36  * easy-to-pronounce term that means "a piece of print data." The print data
  37  * format, or "doc flavor", consists of two things:
  38  * <ul>
  39  *   <li><b>MIME type.</b> This is a Multipurpose Internet Mail Extensions
  40  *   (MIME) media type (as defined in
  41  *   <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a> and
  42  *   <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>) that specifies
  43  *   how the print data is to be interpreted. The charset of text data should be
  44  *   the IANA MIME-preferred name, or its canonical name if no preferred name is
  45  *   specified. Additionally a few historical names supported by earlier
  46  *   versions of the Java platform may be recognized. See
  47  *   <a href="../../java/lang/package-summary.html#charenc">character encodings
  48  *   </a> for more information on the character encodings supported on the Java
  49  *   platform.
  50  *   <li><b>Representation class name.</b> This specifies the fully-qualified
  51  *   name of the class of the object from which the actual print data comes, as
  52  *   returned by the {@link Class#getName() Class.getName()} method. (Thus the
  53  *   class name for {@code byte[]} is {@code "[B"}, for {@code char[]} it is
  54  *   {@code "[C"}.)
  55  * </ul>




  56  * A {@code DocPrintJob} obtains its print data by means of interface
  57  * {@link Doc Doc}. A {@code Doc} object lets the {@code DocPrintJob} determine
  58  * the doc flavor the client can supply. A {@code Doc} object also lets the
  59  * {@code DocPrintJob} obtain an instance of the doc flavor's representation
  60  * class, from which the {@code DocPrintJob} then obtains the actual print data.
  61  *
  62  * <hr>
  63  * <h3>Client Formatted Print Data</h3>
  64  * There are two broad categories of print data, client formatted print data and
  65  * service formatted print data.
  66  * <p>
  67  * For <b>client formatted print data</b>, the client determines or knows the
  68  * print data format. For example the client may have a JPEG encoded image, a
  69  * {@code URL} for HTML code, or a disk file containing plain text in some
  70  * encoding, possibly obtained from an external source, and requires a way to
  71  * describe the data format to the print service.


  72  * <p>
  73  * The doc flavor's representation class is a conduit for the JPS
  74  * {@code DocPrintJob} to obtain a sequence of characters or bytes from the
  75  * client. The doc flavor's MIME type is one of the standard media types telling
  76  * how to interpret the sequence of characters or bytes. For a list of standard
  77  * media types, see the Internet Assigned Numbers Authority's (IANA's)
  78  * <a href="http://www.iana.org/assignments/media-types/">Media Types Directory
  79  * </a>. Interface {@link Doc Doc} provides two utility operations,

  80  * {@link Doc#getReaderForText() getReaderForText} and
  81  * {@link Doc#getStreamForBytes() getStreamForBytes()}, to help a {@code Doc}
  82  * object's client extract client formatted print data.
  83  * <p>
  84  * For client formatted print data, the print data representation class is
  85  * typically one of the following (although other representation classes are
  86  * permitted):
  87  * <ul>
  88  *   <li>Character array ({@code char[]}) -- The print data consists of the

  89  *   Unicode characters in the array.
  90  *   <li>{@code String} -- The print data consists of the Unicode characters in
  91  *   the string.
  92  *   <li>Character stream ({@link java.io.Reader java.io.Reader}) -- The print
  93  *   data consists of the Unicode characters read from the stream up to the
  94  *   end-of-stream.
  95  *   <li>Byte array ({@code byte[]}) -- The print data consists of the bytes in






  96  *   the array. The bytes are encoded in the character set specified by the doc
  97  *   flavor's MIME type. If the MIME type does not specify a character set, the
  98  *   default character set is US-ASCII.
  99  *   <li>Byte stream ({@link java.io.InputStream java.io.InputStream}) -- The
 100  *   print data consists of the bytes read from the stream up to the


 101  *   end-of-stream. The bytes are encoded in the character set specified by the
 102  *   doc flavor's MIME type. If the MIME type does not specify a character set,
 103  *   the default character set is US-ASCII.
 104  *   <li>Uniform Resource Locator ({@link java.net.URL URL}) -- The print data
 105  *   consists of the bytes read from the URL location. The bytes are encoded in
 106  *   the character set specified by the doc flavor's MIME type. If the MIME type
 107  *   does not specify a character set, the default character set is US-ASCII.
 108  *   When the representation class is a {@code URL}, the print service itself
 109  *   accesses and downloads the document directly from its {@code URL} address,
 110  *   without involving the client. The service may be some form of network print
 111  *   service which is executing in a different environment. This means you
 112  *   should not use a {@code URL} print data flavor to print a document at a
 113  *   restricted {@code URL} that the client can see but the printer cannot see.
 114  *   This also means you should not use a {@code URL} print data flavor to print
 115  *   a document stored in a local file that is not available at a {@code URL}
 116  *   accessible independently of the client. For example, a file that is not
 117  *   served up by an HTTP server or FTP server. To print such documents, let the
 118  *   client open an input stream on the {@code URL} or file and use an input
 119  *   stream data flavor.
 120  * </ul>




 121  *
 122  * <hr>
 123  * <h3>Default and Platform Encodings</h3>

 124  * For byte print data where the doc flavor's MIME type does not include a
 125  * {@code charset} parameter, the Java Print Service instance assumes the
 126  * US-ASCII character set by default. This is in accordance with
 127  * <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>, which says the
 128  * default character set is US-ASCII. Note that US-ASCII is a subset of UTF-8,
 129  * so in the future this may be widened if a future RFC endorses UTF-8 as the
 130  * default in a compatible manner.
 131  * <p>
 132  * Also note that this is different than the behaviour of the Java runtime when
 133  * interpreting a stream of bytes as text data. That assumes the default
 134  * encoding for the user's locale. Thus, when spooling a file in local encoding
 135  * to a Java Print Service it is important to correctly specify the encoding.
 136  * Developers working in the English locales should be particularly conscious of
 137  * this, as their platform encoding corresponds to the default mime charset. By
 138  * this coincidence that particular case may work without specifying the
 139  * encoding of platform data.
 140  * <p>
 141  * Every instance of the Java virtual machine has a default character encoding
 142  * determined during virtual-machine startup and typically depends upon the
 143  * locale and charset being used by the underlying operating system. In a
 144  * distributed environment there is no guarantee that two VM share the same
 145  * default encoding. Thus clients which want to stream platform encoded text
 146  * data from the host platform to a Java Print Service instance must explicitly
 147  * declare the charset and not rely on defaults.
 148  * <p>
 149  * The preferred form is the official IANA primary name for an encoding.
 150  * Applications which stream text data should always specify the charset in the
 151  * mime type, which necessitates obtaining the encoding of the host platform for
 152  * data (eg files) stored in that platform's encoding. A {@code CharSet} which
 153  * corresponds to this and is suitable for use in a mime-type for a
 154  * {@code DocFlavor} can be obtained from
 155  * {@link DocFlavor#hostEncoding DocFlavor.hostEncoding} This may not always be
 156  * the primary IANA name but is guaranteed to be understood by this VM. For
 157  * common flavors, the pre-defined *HOST {@code DocFlavors} may be used.

 158  * <p>
 159  * See <a href="../../java/lang/package-summary.html#charenc">character
 160  * encodings</a> for more information on the character encodings supported on
 161  * the Java platform.
 162  *
 163  * <hr>
 164  * <h3>Recommended DocFlavors</h3>

 165  * The Java Print Service API does not define any mandatorily supported
 166  * {@code DocFlavors}. However, here are some examples of MIME types that a Java
 167  * Print Service instance might support for client formatted print data. Nested
 168  * classes inside class {@code DocFlavor} declare predefined static constant
 169  * {@code DocFlavor} objects for these example doc flavors; class
 170  * {@code DocFlavor}'s constructor can be used to create an arbitrary doc
 171  * flavor.
 172  * <ul>
 173  *   <li>Preformatted text
 174  *   <table class="striped">
 175  *   <caption>MIME-Types and their descriptions</caption>
 176  *   <thead>
 177  *     <tr>
 178  *       <th>MIME-Type
 179  *       <th>Description
 180  *   </thead>
 181  *   <tbody>
 182  *     <tr>
 183  *       <td>{@code "text/plain"}
 184  *       <td>Plain text in the default character set (US-ASCII)
 185  *     <tr>
 186  *       <td><code> "text/plain; charset=<i>xxx</i>"</code>
 187  *       <td>Plain text in character set <i>xxx</i>
 188  *     <tr>
 189  *       <td>{@code "text/html"}
 190  *       <td>HyperText Markup Language in the default character set (US-ASCII)
 191  *     <tr>
 192  *       <td><code> "text/html; charset=<i>xxx</i>"</code>
 193  *       <td>HyperText Markup Language in character set <i>xxx</i>




 194  *   </tbody>
 195  *   </table>

 196  *   In general, preformatted text print data is provided either in a character
 197  *   oriented representation class (character array, String, Reader) or in a
 198  *   byte oriented representation class (byte array, InputStream, URL).
 199  *   <li>Preformatted page description language (PDL) documents


 200  *   <table class="striped">
 201  *   <caption>MIME-Types and their descriptions</caption>
 202  *   <thead>
 203  *     <tr>
 204  *       <th>MIME-Type
 205  *       <th>Description
 206  *   </thead>
 207  *   <tbody>
 208  *     <tr>
 209  *       <td>{@code "application/pdf"}
 210  *       <td>Portable Document Format document
 211  *     <tr>
 212  *       <td>{@code "application/postscript"}
 213  *       <td>PostScript document
 214  *     <tr>
 215  *       <td>{@code "application/vnd.hp-PCL"}
 216  *       <td>Printer Control Language document



 217  *   </tbody>
 218  *   </table>

 219  *   In general, preformatted PDL print data is provided in a byte oriented
 220  *   representation class (byte array, {@code InputStream}, {@code URL}).
 221  *   <li>Preformatted images


 222  *   <table class="striped">
 223  *   <caption>MIME-Types and their descriptions</caption>
 224  *   <thead>
 225  *     <tr>
 226  *       <th>MIME-Type
 227  *       <th>Description
 228  *   </thead>
 229  *   <tbody>
 230  *     <tr>
 231  *       <td>{@code "image/gif"}
 232  *       <td>Graphics Interchange Format image
 233  *     <tr>
 234  *       <td>{@code "image/jpeg"}
 235  *       <td>Joint Photographic Experts Group image
 236  *     <tr>
 237  *       <td>{@code "image/png"}
 238  *       <td>Portable Network Graphics image



 239  *   </tbody>
 240  *   </table>

 241  *   In general, preformatted image print data is provided in a byte oriented
 242  *   representation class (byte array, {@code InputStream}, {@code URL}).
 243  *   <li>Preformatted autosense print data


 244  *   <table class="striped">
 245  *   <caption>MIME-Types and their descriptions</caption>
 246  *   <thead>
 247  *     <tr>
 248  *       <th>MIME-Type
 249  *       <th>Description
 250  *   </thead>
 251  *   <tbody>
 252  *     <tr>
 253  *       <td>{@code "application/octet-stream"}
 254  *       <td>The print data format is unspecified (just an octet stream)

 255  *   </tbody>
 256  *   </table>

 257  *   The printer decides how to interpret the print data; the way this
 258  *   "autosensing" works is implementation dependent. In general, preformatted
 259  *   autosense print data is provided in a byte oriented representation class
 260  *   (byte array, {@code InputStream}, {@code URL}).
 261  * </ul>
 262  *
 263  * <hr>
 264  * <h3>Service Formatted Print Data</h3>
 265  * For <b>service formatted print data</b>, the Java Print Service instance

 266  * determines the print data format. The doc flavor's representation class
 267  * denotes an interface whose methods the {@code DocPrintJob} invokes to
 268  * determine the content to be printed -- such as a renderable image interface
 269  * or a Java printable interface. The doc flavor's MIME type is the special
 270  * value {@code "application/x-java-jvm-local-objectref"} indicating the client
 271  * will supply a reference to a Java object that implements the interface named
 272  * as the representation class. This MIME type is just a placeholder; what's


 273  * important is the print data representation class.
 274  * <p>
 275  * For service formatted print data, the print data representation class is
 276  * typically one of the following (although other representation classes are
 277  * permitted). Nested classes inside class {@code DocFlavor} declare predefined
 278  * static constant {@code DocFlavor} objects for these example doc flavors;
 279  * class {@code DocFlavor}'s constructor can be used to create an arbitrary doc
 280  * flavor.
 281  * <ul>
 282  *   <li>Renderable image object -- The client supplies an object that
 283  *   implements interface
 284  *   {@link java.awt.image.renderable.RenderableImage RenderableImage}. The
 285  *   printer calls methods in that interface to obtain the image to be printed.
 286  *   <li>Printable object -- The client supplies an object that implements
 287  *   interface {@link java.awt.print.Printable Printable}. The printer calls
 288  *   methods in that interface to obtain the pages to be printed, one by one.




 289  *   For each page, the printer supplies a graphics context, and whatever the
 290  *   client draws in that graphics context gets printed.
 291  *   <li>Pageable object -- The client supplies an object that implements
 292  *   interface {@link java.awt.print.Pageable Pageable}. The printer calls


 293  *   methods in that interface to obtain the pages to be printed, one by one.
 294  *   For each page, the printer supplies a graphics context, and whatever the
 295  *   client draws in that graphics context gets printed.
 296  * </ul>
 297  *
 298  * <hr>
 299  * <h3>Pre-defined Doc Flavors</h3>
 300  * A Java Print Service instance is not <b><i>required</i></b> to support the
 301  * following print data formats and print data representation classes. In fact,
 302  * a developer using this class should <b>never</b> assume that a particular
 303  * print service supports the document types corresponding to these pre-defined
 304  * doc flavors. Always query the print service to determine what doc flavors it
 305  * supports. However, developers who have print services that support these doc
 306  * flavors are encouraged to refer to the predefined singleton instances created
 307  * here.
 308  * <ul>
 309  *   <li>Plain text print data provided through a byte stream. Specifically, the



 310  *   following doc flavors are recommended to be supported:
 311  *   <br>·&nbsp;&nbsp;
 312  *   {@code ("text/plain", "java.io.InputStream")}
 313  *   <br>·&nbsp;&nbsp;
 314  *   {@code ("text/plain; charset=us-ascii", "java.io.InputStream")}
 315  *   <br>·&nbsp;&nbsp;
 316  *   {@code ("text/plain; charset=utf-8", "java.io.InputStream")}
 317  *   <li>Renderable image objects. Specifically, the following doc flavor is


 318  *   recommended to be supported:
 319  *   <br>·&nbsp;&nbsp;
 320  *   {@code ("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")}
 321  * </ul>
 322  * A Java Print Service instance is allowed to support any other doc flavors (or
 323  * none) in addition to the above mandatory ones, at the implementation's

 324  * choice.
 325  * <p>
 326  * Support for the above doc flavors is desirable so a printing client can rely
 327  * on being able to print on any JPS printer, regardless of which doc flavors
 328  * the printer supports. If the printer doesn't support the client's preferred
 329  * doc flavor, the client can at least print plain text, or the client can
 330  * convert its data to a renderable image and print the image.
 331  * <p>
 332  * Furthermore, every Java Print Service instance must fulfill these
 333  * requirements for processing plain text print data:
 334  * <ul>
 335  *   <li>The character pair carriage return-line feed (CR-LF) means "go to
 336  *   column 1 of the next line."
 337  *   <li>A carriage return (CR) character standing by itself means "go to column
 338  *   1 of the next line."
 339  *   <li>A line feed (LF) character standing by itself means "go to column 1 of
 340  *   the next line."
 341  * </ul>




 342  * The client must itself perform all plain text print data formatting not
 343  * addressed by the above requirements.
 344  *
 345  * <h3>Design Rationale</h3>
 346  * Class {@code DocFlavor} in package {@code javax.print} is similar to class
 347  * {@link java.awt.datatransfer.DataFlavor}. Class {@code DataFlavor} is not
 348  * used in the Java Print Service (JPS) API for three reasons which are all
 349  * rooted in allowing the JPS API to be shared by other print services APIs
 350  * which may need to run on Java profiles which do not include all of the Java
 351  * Platform, Standard Edition.
 352  * <ol type=1>
 353  *   <li>The JPS API is designed to be used in Java profiles which do not
 354  *   support AWT.
 355  *   <li>The implementation of class {@code java.awt.datatransfer.DataFlavor}





 356  *   does not guarantee that equivalent data flavors will have the same
 357  *   serialized representation. {@code DocFlavor} does, and can be used in
 358  *   services which need this.
 359  *   <li>The implementation of class {@code java.awt.datatransfer.DataFlavor}


 360  *   includes a human presentable name as part of the serialized representation.
 361  *   This is not appropriate as part of a service matching constraint.
 362  * </ol>
 363  * Class {@code DocFlavor}'s serialized representation uses the following

 364  * canonical form of a MIME type string. Thus, two doc flavors with MIME types
 365  * that are not identical but that are equivalent (that have the same canonical
 366  * form) may be considered equal.
 367  * <ul>
 368  *   <li>The media type, media subtype, and parameters are retained, but all
 369  *   comments and whitespace characters are discarded.
 370  *   <li>The media type, media subtype, and parameter names are converted to
 371  *   lowercase.
 372  *   <li>The parameter values retain their original case, except a charset
 373  *   parameter value for a text media type is converted to lowercase.
 374  *   <li>Quote characters surrounding parameter values are removed.
 375  *   <li>Quoting backslash characters inside parameter values are removed.
 376  *   <li>The parameters are arranged in ascending order of parameter name.
 377  * </ul>
 378  * Class {@code DocFlavor}'s serialized representation also contains the
 379  * fully-qualified class <i>name</i> of the representation class (a
 380  * {@code String} object), rather than the representation class itself (a
 381  * {@code Class} object). This allows a client to examine the doc flavors a Java
 382  * Print Service instance supports without having to load the representation
 383  * classes, which may be problematic for limited-resource clients.


 384  *
 385  * @author Alan Kaminsky
 386  */
 387 public class DocFlavor implements Serializable, Cloneable {
 388 
 389     /**
 390      * Use serialVersionUID from JDK 1.4 for interoperability.
 391      */
 392     private static final long serialVersionUID = -4512080796965449721L;
 393 
 394     /**
 395      * A string representing the host operating system encoding. This will
 396      * follow the conventions documented in
 397      * <a href="http://www.ietf.org/rfc/rfc2278.txt">
 398      * <i>RFC&nbsp;2278:&nbsp;IANA Charset Registration Procedures</i></a>
 399      * except where historical names are returned for compatibility with
 400      * previous versions of the Java platform. The value returned from method is
 401      * valid only for the VM which returns it, for use in a {@code DocFlavor}.
 402      * This is the charset for all the "HOST" pre-defined {@code DocFlavors} in

 403      * the executing VM.
 404      */
 405     public static final String hostEncoding;
 406 
 407     static {
 408         hostEncoding =
 409             java.security.AccessController.doPrivileged(
 410                   new sun.security.action.GetPropertyAction("file.encoding"));
 411     }
 412 
 413     /**
 414      * MIME type.
 415      */
 416     private transient MimeType myMimeType;
 417 
 418     /**
 419      * Representation class name.
 420      *
 421      * @serial
 422      */
 423     private String myClassName;
 424 
 425     /**
 426      * String value for this doc flavor. Computed when needed and cached.
 427      */
 428     private transient String myStringValue = null;
 429 

 430     /**
 431      * Constructs a new doc flavor object from the given MIME type and
 432      * representation class name. The given MIME type is converted into
 433      * canonical form and stored internally.
 434      *
 435      * @param  mimeType MIME media type string
 436      * @param  className fully-qualified representation class name
 437      * @throws NullPointerException if {@code mimeType} or {@code className} are
 438      *         {@code null}
 439      * @throws IllegalArgumentException if {@code mimeType} does not obey the
 440      *         syntax for a MIME media type string



 441      */
 442     public DocFlavor(String mimeType, String className) {
 443         if (className == null) {
 444             throw new NullPointerException();
 445         }
 446         myMimeType = new MimeType (mimeType);
 447         myClassName = className;
 448     }
 449 
 450     /**
 451      * Returns this doc flavor object's MIME type string based on the canonical
 452      * form. Each parameter value is enclosed in quotes.
 453      *
 454      * @return the mime type
 455      */
 456     public String getMimeType() {
 457         return myMimeType.getMimeType();
 458     }
 459 
 460     /**
 461      * Returns this doc flavor object's media type (from the MIME type).
 462      *
 463      * @return the media type
 464      */
 465     public String getMediaType() {
 466         return myMimeType.getMediaType();
 467     }
 468 
 469     /**
 470      * Returns this doc flavor object's media subtype (from the MIME type).
 471      *
 472      * @return the media sub-type
 473      */
 474     public String getMediaSubtype() {
 475         return myMimeType.getMediaSubtype();
 476     }
 477 
 478     /**
 479      * Returns a {@code String} representing a MIME parameter. Mime types may
 480      * include parameters which are usually optional. The charset for text types
 481      * is a commonly useful example. This convenience method will return the
 482      * value of the specified parameter if one was specified in the mime type
 483      * for this flavor.

 484      *
 485      * @param  paramName the name of the parameter. This name is internally
 486      *         converted to the canonical lower case format before performing
 487      *         the match.
 488      * @return the string representing a mime parameter, or {@code null} if that
 489      *         parameter is not in the mime type string
 490      * @throws NullPointerException if paramName is {@code null}
 491      */
 492     public String getParameter(String paramName) {
 493         return myMimeType.getParameterMap().get(paramName.toLowerCase());
 494     }
 495 
 496     /**
 497      * Returns the name of this doc flavor object's representation class.
 498      *
 499      * @return the name of the representation class
 500      */
 501     public String getRepresentationClassName() {
 502         return myClassName;
 503     }
 504 
 505     /**
 506      * Converts this {@code DocFlavor} to a string.
 507      *
 508      * @return MIME type string based on the canonical form. Each parameter
 509      *         value is enclosed in quotes. A "class=" parameter is appended to
 510      *         the MIME type string to indicate the representation class name.

 511      */
 512     public String toString() {
 513         return getStringValue();
 514     }
 515 
 516     /**
 517      * Returns a hash code for this doc flavor object.
 518      */
 519     public int hashCode() {
 520         return getStringValue().hashCode();
 521     }
 522 
 523     /**
 524      * Determines if this doc flavor object is equal to the given object. The
 525      * two are equal if the given object is not {@code null}, is an instance of
 526      * {@code DocFlavor}, has a MIME type equivalent to this doc flavor object's
 527      * MIME type (that is, the MIME types have the same media type, media
 528      * subtype, and parameters), and has the same representation class name as
 529      * this doc flavor object. Thus, if two doc flavor objects' MIME types are
 530      * the same except for comments, they are considered equal. However, two doc
 531      * flavor objects with MIME types of "text/plain" and "text/plain;
 532      * charset=US-ASCII" are not considered equal, even though they represent
 533      * the same media type (because the default character set for plain text is
 534      * US-ASCII).
 535      *
 536      * @param  obj {@code Object} to test
 537      * @return {@code true} if this doc flavor object equals {@code obj},
 538      *         {@code false} otherwise

 539      */
 540     public boolean equals(Object obj) {
 541         return
 542             obj != null &&
 543             obj instanceof DocFlavor &&
 544             getStringValue().equals (((DocFlavor) obj).getStringValue());
 545     }
 546 
 547     /**
 548      * Returns this doc flavor object's string value.
 549      *
 550      * @return the string value
 551      */
 552     private String getStringValue() {
 553         if (myStringValue == null) {
 554             myStringValue = myMimeType + "; class=\"" + myClassName + "\"";
 555         }
 556         return myStringValue;
 557     }
 558 
 559     /**
 560      * Write the instance to a stream (ie serialize the object).
 561      *
 562      * @param  s the output stream
 563      * @throws IOException if I/O errors occur while writing to the underlying
 564      *         stream
 565      */
 566     private void writeObject(ObjectOutputStream s) throws IOException {
 567 
 568         s.defaultWriteObject();
 569         s.writeObject(myMimeType.getMimeType());
 570     }
 571 
 572     /**
 573      * Reconstitute an instance from a stream (that is, deserialize it).
 574      *
 575      * @param  s the input stream
 576      * @throws ClassNotFoundException if the class of a serialized object could
 577      *         not be found
 578      * @throws IOException if I/O errors occur while reading from the underlying
 579      *         stream
 580      * @serialData The serialised form of a {@code DocFlavor} is the
 581      *             {@code String} naming the representation class followed by
 582      *             the {@code String} representing the canonical form of the
 583      *             mime type
 584      */
 585     private void readObject(ObjectInputStream s)
 586         throws ClassNotFoundException, IOException {
 587 
 588         s.defaultReadObject();
 589         myMimeType = new MimeType((String)s.readObject());
 590     }
 591 
 592     /**
 593      * Class {@code DocFlavor.BYTE_ARRAY} provides predefined static constant
 594      * {@code DocFlavor} objects for example doc flavors using a byte array
 595      * ({@code byte[]}) as the print data representation class.
 596      *
 597      * @author Alan Kaminsky
 598      */
 599     public static class BYTE_ARRAY extends DocFlavor {
 600 
 601         /**
 602          * Use serialVersionUID from JDK 1.4 for interoperability.
 603          */
 604         private static final long serialVersionUID = -9065578006593857475L;
 605 
 606         /**
 607          * Constructs a new doc flavor with the given MIME type and a print data
 608          * representation class name of {@code "[B"} (byte array).
 609          *
 610          * @param  mimeType MIME media type string
 611          * @throws NullPointerException if {@code mimeType} is {@code null}
 612          * @throws IllegalArgumentException if {@code mimeType} does not obey
 613          *         the syntax for a MIME media type string



 614          */
 615         public BYTE_ARRAY (String mimeType) {
 616             super (mimeType, "[B");
 617         }
 618 
 619         /**
 620          * Doc flavor with MIME type = {@code "text/plain"}, encoded in the host
 621          * platform encoding. See {@link DocFlavor#hostEncoding hostEncoding}.
 622          * Print data representation class name = {@code "[B"} (byte array).


 623          */
 624         public static final BYTE_ARRAY TEXT_PLAIN_HOST =
 625             new BYTE_ARRAY ("text/plain; charset="+hostEncoding);
 626 
 627         /**
 628          * Doc flavor with MIME type = {@code "text/plain; charset=utf-8"},
 629          * print data representation class name = {@code "[B"} (byte array).


 630          */
 631         public static final BYTE_ARRAY TEXT_PLAIN_UTF_8 =
 632             new BYTE_ARRAY ("text/plain; charset=utf-8");
 633 
 634         /**
 635          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16"},
 636          * print data representation class name = {@code "[B"} (byte array).


 637          */
 638         public static final BYTE_ARRAY TEXT_PLAIN_UTF_16 =
 639             new BYTE_ARRAY ("text/plain; charset=utf-16");
 640 

 641         /**
 642          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16be"}
 643          * (big-endian byte ordering), print data representation class name =
 644          * {@code "[B"} (byte array).


 645          */
 646         public static final BYTE_ARRAY TEXT_PLAIN_UTF_16BE =
 647             new BYTE_ARRAY ("text/plain; charset=utf-16be");
 648 
 649         /**
 650          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16le"}
 651          * (little-endian byte ordering), print data representation class name =
 652          * {@code "[B"} (byte array).


 653          */
 654         public static final BYTE_ARRAY TEXT_PLAIN_UTF_16LE =
 655             new BYTE_ARRAY ("text/plain; charset=utf-16le");
 656 
 657         /**
 658          * Doc flavor with MIME type = {@code "text/plain; charset=us-ascii"},
 659          * print data representation class name = {@code "[B"} (byte array).


 660          */
 661         public static final BYTE_ARRAY TEXT_PLAIN_US_ASCII =
 662             new BYTE_ARRAY ("text/plain; charset=us-ascii");
 663 
 664 
 665         /**
 666          * Doc flavor with MIME type = {@code "text/html"}, encoded in the host
 667          * platform encoding. See {@link DocFlavor#hostEncoding hostEncoding}.
 668          * Print data representation class name = {@code "[B"} (byte array).


 669          */
 670         public static final BYTE_ARRAY TEXT_HTML_HOST =
 671             new BYTE_ARRAY ("text/html; charset="+hostEncoding);
 672 
 673         /**
 674          * Doc flavor with MIME type = {@code "text/html; charset=utf-8"}, print
 675          * data representation class name = {@code "[B"} (byte array).


 676          */
 677         public static final BYTE_ARRAY TEXT_HTML_UTF_8 =
 678             new BYTE_ARRAY ("text/html; charset=utf-8");
 679 
 680         /**
 681          * Doc flavor with MIME type = {@code "text/html; charset=utf-16"},
 682          * print data representation class name = {@code "[B"} (byte array).


 683          */
 684         public static final BYTE_ARRAY TEXT_HTML_UTF_16 =
 685             new BYTE_ARRAY ("text/html; charset=utf-16");
 686 
 687         /**
 688          * Doc flavor with MIME type = {@code "text/html; charset=utf-16be"}
 689          * (big-endian byte ordering), print data representation class name =
 690          * {@code "[B"} (byte array).


 691          */
 692         public static final BYTE_ARRAY TEXT_HTML_UTF_16BE =
 693             new BYTE_ARRAY ("text/html; charset=utf-16be");
 694 
 695         /**
 696          * Doc flavor with MIME type = {@code "text/html; charset=utf-16le"}
 697          * (little-endian byte ordering), print data representation class name =
 698          * {@code "[B"} (byte array).


 699          */
 700         public static final BYTE_ARRAY TEXT_HTML_UTF_16LE =
 701             new BYTE_ARRAY ("text/html; charset=utf-16le");
 702 
 703         /**
 704          * Doc flavor with MIME type = {@code "text/html; charset=us-ascii"},
 705          * print data representation class name = {@code "[B"} (byte array).


 706          */
 707         public static final BYTE_ARRAY TEXT_HTML_US_ASCII =
 708             new BYTE_ARRAY ("text/html; charset=us-ascii");
 709 
 710 
 711         /**
 712          * Doc flavor with MIME type = {@code "application/pdf"}, print data
 713          * representation class name = {@code "[B"} (byte array).
 714          */
 715         public static final BYTE_ARRAY PDF = new BYTE_ARRAY ("application/pdf");
 716 
 717         /**
 718          * Doc flavor with MIME type = {@code "application/postscript"}, print
 719          * data representation class name = {@code "[B"} (byte array).

 720          */
 721         public static final BYTE_ARRAY POSTSCRIPT =
 722             new BYTE_ARRAY ("application/postscript");
 723 
 724         /**
 725          * Doc flavor with MIME type = {@code "application/vnd.hp-PCL"}, print
 726          * data representation class name = {@code "[B"} (byte array).

 727          */
 728         public static final BYTE_ARRAY PCL =
 729             new BYTE_ARRAY ("application/vnd.hp-PCL");
 730 
 731         /**
 732          * Doc flavor with MIME type = {@code "image/gif"}, print data
 733          * representation class name = {@code "[B"} (byte array).
 734          */
 735         public static final BYTE_ARRAY GIF = new BYTE_ARRAY ("image/gif");
 736 
 737         /**
 738          * Doc flavor with MIME type = {@code "image/jpeg"}, print data
 739          * representation class name = {@code "[B"} (byte array).
 740          */
 741         public static final BYTE_ARRAY JPEG = new BYTE_ARRAY ("image/jpeg");
 742 
 743         /**
 744          * Doc flavor with MIME type = {@code "image/png"}, print data
 745          * representation class name = {@code "[B"} (byte array).
 746          */
 747         public static final BYTE_ARRAY PNG = new BYTE_ARRAY ("image/png");
 748 
 749         /**
 750          * Doc flavor with MIME type = {@code "application/octet-stream"}, print
 751          * data representation class name = {@code "[B"} (byte array). The
 752          * client must determine that data described using this
 753          * {@code DocFlavor} is valid for the printer.

 754          */
 755         public static final BYTE_ARRAY AUTOSENSE =
 756             new BYTE_ARRAY ("application/octet-stream");

 757     }
 758 
 759     /**
 760      * Class {@code DocFlavor.INPUT_STREAM} provides predefined static constant
 761      * {@code DocFlavor} objects for example doc flavors using a byte stream
 762      * ({@link java.io.InputStream java.io.InputStream}) as the print data
 763      * representation class.
 764      *
 765      * @author Alan Kaminsky
 766      */
 767     public static class INPUT_STREAM extends DocFlavor {
 768 
 769         /**
 770          * Use serialVersionUID from JDK 1.4 for interoperability.
 771          */
 772         private static final long serialVersionUID = -7045842700749194127L;
 773 
 774         /**
 775          * Constructs a new doc flavor with the given MIME type and a print data
 776          * representation class name of {@code "java.io.InputStream"} (byte
 777          * stream).
 778          *
 779          * @param  mimeType MIME media type string
 780          * @throws NullPointerException if {@code mimeType} is {@code null}
 781          * @throws IllegalArgumentException if {@code mimeType} does not obey
 782          *         the syntax for a MIME media type string.



 783          */
 784         public INPUT_STREAM (String mimeType) {
 785             super (mimeType, "java.io.InputStream");
 786         }
 787 
 788         /**
 789          * Doc flavor with MIME type = {@code "text/plain"}, encoded in the host
 790          * platform encoding. See {@link DocFlavor#hostEncoding hostEncoding}.
 791          * Print data representation class name = {@code "java.io.InputStream"}
 792          * (byte stream).

 793          */
 794         public static final INPUT_STREAM TEXT_PLAIN_HOST =
 795             new INPUT_STREAM ("text/plain; charset="+hostEncoding);
 796 
 797         /**
 798          * Doc flavor with MIME type = {@code "text/plain; charset=utf-8"},
 799          * print data representation class name = {@code "java.io.InputStream"}
 800          * (byte stream).

 801          */
 802         public static final INPUT_STREAM TEXT_PLAIN_UTF_8 =
 803             new INPUT_STREAM ("text/plain; charset=utf-8");
 804 
 805         /**
 806          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16"},
 807          * print data representation class name = {@code "java.io.InputStream"}
 808          * (byte stream).

 809          */
 810         public static final INPUT_STREAM TEXT_PLAIN_UTF_16 =
 811             new INPUT_STREAM ("text/plain; charset=utf-16");
 812 
 813         /**
 814          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16be"}
 815          * (big-endian byte ordering), print data representation class name =


 816          * {@code "java.io.InputStream"} (byte stream).
 817          */
 818         public static final INPUT_STREAM TEXT_PLAIN_UTF_16BE =
 819             new INPUT_STREAM ("text/plain; charset=utf-16be");
 820 
 821         /**
 822          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16le"}
 823          * (little-endian byte ordering), print data representation class name =


 824          * {@code "java.io.InputStream"} (byte stream).
 825          */
 826         public static final INPUT_STREAM TEXT_PLAIN_UTF_16LE =
 827             new INPUT_STREAM ("text/plain; charset=utf-16le");
 828 
 829         /**
 830          * Doc flavor with MIME type = {@code "text/plain; charset=us-ascii"},
 831          * print data representation class name = {@code "java.io.InputStream"}
 832          * (byte stream).

 833          */
 834         public static final INPUT_STREAM TEXT_PLAIN_US_ASCII =
 835                 new INPUT_STREAM ("text/plain; charset=us-ascii");
 836 
 837         /**
 838          * Doc flavor with MIME type = {@code "text/html"}, encoded in the host
 839          * platform encoding. See {@link DocFlavor#hostEncoding hostEncoding}.
 840          * Print data representation class name = {@code "java.io.InputStream"}
 841          * (byte stream).

 842          */
 843         public static final INPUT_STREAM TEXT_HTML_HOST =
 844             new INPUT_STREAM ("text/html; charset="+hostEncoding);
 845 
 846         /**
 847          * Doc flavor with MIME type = {@code "text/html; charset=utf-8"}, print
 848          * data representation class name = {@code "java.io.InputStream"} (byte
 849          * stream).

 850          */
 851         public static final INPUT_STREAM TEXT_HTML_UTF_8 =
 852             new INPUT_STREAM ("text/html; charset=utf-8");
 853 
 854         /**
 855          * Doc flavor with MIME type = {@code "text/html; charset=utf-16"},
 856          * print data representation class name = {@code "java.io.InputStream"}
 857          * (byte stream).

 858          */
 859         public static final INPUT_STREAM TEXT_HTML_UTF_16 =
 860             new INPUT_STREAM ("text/html; charset=utf-16");
 861 
 862         /**
 863          * Doc flavor with MIME type = {@code "text/html; charset=utf-16be"}
 864          * (big-endian byte ordering), print data representation class name =


 865          * {@code "java.io.InputStream"} (byte stream).
 866          */
 867         public static final INPUT_STREAM TEXT_HTML_UTF_16BE =
 868             new INPUT_STREAM ("text/html; charset=utf-16be");
 869 
 870         /**
 871          * Doc flavor with MIME type = {@code "text/html; charset=utf-16le"}
 872          * (little-endian byte ordering), print data representation class name =


 873          * {@code "java.io.InputStream"} (byte stream).
 874          */
 875         public static final INPUT_STREAM TEXT_HTML_UTF_16LE =
 876             new INPUT_STREAM ("text/html; charset=utf-16le");
 877 
 878         /**
 879          * Doc flavor with MIME type = {@code "text/html; charset=us-ascii"},
 880          * print data representation class name = {@code "java.io.InputStream"}
 881          * (byte stream).

 882          */
 883         public static final INPUT_STREAM TEXT_HTML_US_ASCII =
 884             new INPUT_STREAM ("text/html; charset=us-ascii");
 885 

 886         /**
 887          * Doc flavor with MIME type = {@code "application/pdf"}, print data
 888          * representation class name = {@code "java.io.InputStream"} (byte
 889          * stream).
 890          */
 891         public static final INPUT_STREAM PDF = new INPUT_STREAM ("application/pdf");
 892 
 893         /**
 894          * Doc flavor with MIME type = {@code "application/postscript"}, print
 895          * data representation class name = {@code "java.io.InputStream"} (byte
 896          * stream).
 897          */
 898         public static final INPUT_STREAM POSTSCRIPT =
 899             new INPUT_STREAM ("application/postscript");
 900 
 901         /**
 902          * Doc flavor with MIME type = {@code "application/vnd.hp-PCL"}, print
 903          * data representation class name = {@code "java.io.InputStream"} (byte
 904          * stream).
 905          */
 906         public static final INPUT_STREAM PCL =
 907             new INPUT_STREAM ("application/vnd.hp-PCL");
 908 
 909         /**
 910          * Doc flavor with MIME type = {@code "image/gif"}, print data
 911          * representation class name = {@code "java.io.InputStream"} (byte
 912          * stream).
 913          */
 914         public static final INPUT_STREAM GIF = new INPUT_STREAM ("image/gif");
 915 
 916         /**
 917          * Doc flavor with MIME type = {@code "image/jpeg"}, print data
 918          * representation class name = {@code "java.io.InputStream"} (byte
 919          * stream).
 920          */
 921         public static final INPUT_STREAM JPEG = new INPUT_STREAM ("image/jpeg");
 922 
 923         /**
 924          * Doc flavor with MIME type = {@code "image/png"}, print data
 925          * representation class name = {@code "java.io.InputStream"} (byte
 926          * stream).
 927          */
 928         public static final INPUT_STREAM PNG = new INPUT_STREAM ("image/png");
 929 
 930         /**
 931          * Doc flavor with MIME type = {@code "application/octet-stream"}, print
 932          * data representation class name = {@code "java.io.InputStream"} (byte
 933          * stream). The client must determine that data described using this
 934          * {@code DocFlavor} is valid for the printer.


 935          */
 936         public static final INPUT_STREAM AUTOSENSE =
 937             new INPUT_STREAM ("application/octet-stream");

 938     }
 939 
 940     /**
 941      * Class {@code DocFlavor.URL} provides predefined static constant
 942      * {@code DocFlavor} objects. For example doc flavors using a Uniform
 943      * Resource Locator ({@link java.net.URL java.net.URL}) as the print data

 944      * representation class.
 945      *
 946      * @author Alan Kaminsky
 947      */
 948     public static class URL extends DocFlavor {
 949 
 950         /**
 951          * Use serialVersionUID from JDK 1.4 for interoperability.
 952          */
 953         private static final long serialVersionUID = 2936725788144902062L;
 954 
 955         /**
 956          * Constructs a new doc flavor with the given MIME type and a print data
 957          * representation class name of {@code "java.net.URL"}.


 958          *
 959          * @param  mimeType MIME media type string
 960          * @throws NullPointerException if {@code mimeType} is {@code null}
 961          * @throws IllegalArgumentException if {@code mimeType} does not obey
 962          *         the syntax for a MIME media type string

 963          */
 964         public URL (String mimeType) {
 965             super (mimeType, "java.net.URL");
 966         }
 967 
 968         /**
 969          * Doc flavor with MIME type = {@code "text/plain"}, encoded in the host
 970          * platform encoding. See {@link DocFlavor#hostEncoding hostEncoding}.
 971          * Print data representation class name = {@code "java.net.URL"} (byte
 972          * stream).

 973          */
 974         public static final URL TEXT_PLAIN_HOST =
 975             new URL ("text/plain; charset="+hostEncoding);
 976 
 977         /**
 978          * Doc flavor with MIME type = {@code "text/plain; charset=utf-8"},
 979          * print data representation class name = {@code "java.net.URL"} (byte
 980          * stream).

 981          */
 982         public static final URL TEXT_PLAIN_UTF_8 =
 983             new URL ("text/plain; charset=utf-8");
 984 
 985         /**
 986          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16"},
 987          * print data representation class name = {@code java.net.URL""} (byte
 988          * stream).

 989          */
 990         public static final URL TEXT_PLAIN_UTF_16 =
 991             new URL ("text/plain; charset=utf-16");
 992 
 993         /**
 994          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16be"}
 995          * (big-endian byte ordering), print data representation class name =


 996          * {@code "java.net.URL"} (byte stream).
 997          */
 998         public static final URL TEXT_PLAIN_UTF_16BE =
 999             new URL ("text/plain; charset=utf-16be");
1000 
1001         /**
1002          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16le"}
1003          * (little-endian byte ordering), print data representation class name =


1004          * {@code "java.net.URL"} (byte stream).
1005          */
1006         public static final URL TEXT_PLAIN_UTF_16LE =
1007             new URL ("text/plain; charset=utf-16le");
1008 
1009         /**
1010          * Doc flavor with MIME type = {@code "text/plain; charset=us-ascii"},
1011          * print data representation class name = {@code "java.net.URL"} (byte
1012          * stream).

1013          */
1014         public static final URL TEXT_PLAIN_US_ASCII =
1015             new URL ("text/plain; charset=us-ascii");
1016 
1017         /**
1018          * Doc flavor with MIME type = {@code "text/html"}, encoded in the host
1019          * platform encoding. See {@link DocFlavor#hostEncoding hostEncoding}.
1020          * Print data representation class name = {@code "java.net.URL"} (byte
1021          * stream).

1022          */
1023         public static final URL TEXT_HTML_HOST =
1024             new URL ("text/html; charset="+hostEncoding);
1025 
1026         /**
1027          * Doc flavor with MIME type = {@code "text/html; charset=utf-8"}, print
1028          * data representation class name = {@code "java.net.URL"} (byte
1029          * stream).

1030          */
1031         public static final URL TEXT_HTML_UTF_8 =
1032             new URL ("text/html; charset=utf-8");
1033 
1034         /**
1035          * Doc flavor with MIME type = {@code "text/html; charset=utf-16"},
1036          * print data representation class name = {@code "java.net.URL"} (byte
1037          * stream).

1038          */
1039         public static final URL TEXT_HTML_UTF_16 =
1040             new URL ("text/html; charset=utf-16");
1041 
1042         /**
1043          * Doc flavor with MIME type = {@code "text/html; charset=utf-16be"}
1044          * (big-endian byte ordering), print data representation class name =


1045          * {@code "java.net.URL"} (byte stream).
1046          */
1047         public static final URL TEXT_HTML_UTF_16BE =
1048             new URL ("text/html; charset=utf-16be");
1049 
1050         /**
1051          * Doc flavor with MIME type = {@code "text/html; charset=utf-16le"}
1052          * (little-endian byte ordering), print data representation class name =


1053          * {@code "java.net.URL"} (byte stream).
1054          */
1055         public static final URL TEXT_HTML_UTF_16LE =
1056             new URL ("text/html; charset=utf-16le");
1057 
1058         /**
1059          * Doc flavor with MIME type = {@code "text/html; charset=us-ascii"},
1060          * print data representation class name = {@code "java.net.URL"} (byte
1061          * stream).

1062          */
1063         public static final URL TEXT_HTML_US_ASCII =
1064             new URL ("text/html; charset=us-ascii");
1065 

1066         /**
1067          * Doc flavor with MIME type = {@code "application/pdf"}, print data
1068          * representation class name = {@code "java.net.URL"}.
1069          */
1070         public static final URL PDF = new URL ("application/pdf");
1071 
1072         /**
1073          * Doc flavor with MIME type = {@code "application/postscript"}, print
1074          * data representation class name = {@code "java.net.URL"}.
1075          */
1076         public static final URL POSTSCRIPT = new URL ("application/postscript");
1077 
1078         /**
1079          * Doc flavor with MIME type = {@code "application/vnd.hp-PCL"}, print
1080          * data representation class name = {@code "java.net.URL"}.
1081          */
1082         public static final URL PCL = new URL ("application/vnd.hp-PCL");
1083 
1084         /**
1085          * Doc flavor with MIME type = {@code "image/gif"}, print data
1086          * representation class name = {@code "java.net.URL"}.
1087          */
1088         public static final URL GIF = new URL ("image/gif");
1089 
1090         /**
1091          * Doc flavor with MIME type = {@code "image/jpeg"}, print data
1092          * representation class name = {@code "java.net.URL"}.
1093          */
1094         public static final URL JPEG = new URL ("image/jpeg");
1095 
1096         /**
1097          * Doc flavor with MIME type = {@code "image/png"}, print data
1098          * representation class name = {@code "java.net.URL"}.
1099          */
1100         public static final URL PNG = new URL ("image/png");
1101 
1102         /**
1103          * Doc flavor with MIME type = {@code "application/octet-stream"}, print
1104          * data representation class name = {@code "java.net.URL"}. The client
1105          * must determine that data described using this {@code DocFlavor} is
1106          * valid for the printer.

1107          */
1108         public static final URL AUTOSENSE = new URL ("application/octet-stream");

1109     }
1110 
1111     /**
1112      * Class {@code DocFlavor.CHAR_ARRAY} provides predefined static constant
1113      * {@code DocFlavor} objects for example doc flavors using a character array
1114      * ({@code char[]}) as the print data representation class. As such, the
1115      * character set is Unicode.
1116      *
1117      * @author Alan Kaminsky
1118      */
1119     public static class CHAR_ARRAY extends DocFlavor {
1120 
1121         /**
1122          * Use serialVersionUID from JDK 1.4 for interoperability.
1123          */
1124         private static final long serialVersionUID = -8720590903724405128L;
1125 
1126         /**
1127          * Constructs a new doc flavor with the given MIME type and a print data
1128          * representation class name of {@code "[C"} (character array).
1129          *
1130          * @param  mimeType MIME media type string. If it is a text media type,
1131          *         it is assumed to contain a {@code "charset=utf-16"}
1132          *         parameter.
1133          * @throws NullPointerException if {@code mimeType} is {@code null}
1134          * @throws IllegalArgumentException if {@code mimeType} does not obey
1135          *         the syntax for a MIME media type string




1136          */
1137         public CHAR_ARRAY (String mimeType) {
1138             super (mimeType, "[C");
1139         }
1140 
1141         /**
1142          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16"},
1143          * print data representation class name = {@code "[C"} (character
1144          * array).
1145          */
1146         public static final CHAR_ARRAY TEXT_PLAIN =
1147             new CHAR_ARRAY ("text/plain; charset=utf-16");
1148 
1149         /**
1150          * Doc flavor with MIME type = {@code "text/html; charset=utf-16"},
1151          * print data representation class name = {@code "[C"} (character
1152          * array).
1153          */
1154         public static final CHAR_ARRAY TEXT_HTML =
1155             new CHAR_ARRAY ("text/html; charset=utf-16");

1156     }
1157 
1158     /**
1159      * Class {@code DocFlavor.STRING} provides predefined static constant
1160      * {@code DocFlavor} objects for example doc flavors using a string
1161      * ({@link String java.lang.String}) as the print data representation class.
1162      * As such, the character set is Unicode.
1163      *
1164      * @author Alan Kaminsky
1165      */
1166     public static class STRING extends DocFlavor {
1167 
1168         /**
1169          * Use serialVersionUID from JDK 1.4 for interoperability.
1170          */
1171         private static final long serialVersionUID = 4414407504887034035L;
1172 
1173         /**
1174          * Constructs a new doc flavor with the given MIME type and a print data
1175          * representation class name of {@code "java.lang.String"}.
1176          *
1177          * @param  mimeType MIME media type string. If it is a text media type,
1178          *         it is assumed to contain a {@code "charset=utf-16"}
1179          *         parameter.
1180          * @throws NullPointerException if {@code mimeType} is {@code null}
1181          * @throws IllegalArgumentException if {@code mimeType} does not obey
1182          *         the syntax for a MIME media type string



1183          */
1184         public STRING (String mimeType) {
1185             super (mimeType, "java.lang.String");
1186         }
1187 
1188         /**
1189          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16"},
1190          * print data representation class name = {@code "java.lang.String"}.

1191          */
1192         public static final STRING TEXT_PLAIN =
1193             new STRING ("text/plain; charset=utf-16");
1194 
1195         /**
1196          * Doc flavor with MIME type = {@code "text/html; charset=utf-16"},
1197          * print data representation class name = {@code "java.lang.String"}.

1198          */
1199         public static final STRING TEXT_HTML =
1200             new STRING ("text/html; charset=utf-16");
1201     }
1202 
1203     /**
1204      * Class {@code DocFlavor.READER} provides predefined static constant
1205      * {@code DocFlavor} objects for example doc flavors using a character
1206      * stream ({@link java.io.Reader java.io.Reader}) as the print data
1207      * representation class. As such, the character set is Unicode.
1208      *
1209      * @author Alan Kaminsky
1210      */
1211     public static class READER extends DocFlavor {
1212 
1213         /**
1214          * Use serialVersionUID from JDK 1.4 for interoperability.
1215          */
1216         private static final long serialVersionUID = 7100295812579351567L;
1217 
1218         /**
1219          * Constructs a new doc flavor with the given MIME type and a print data
1220          * representation class name of {@code "java.io.Reader"} (character
1221          * stream).
1222          *
1223          * @param  mimeType MIME media type string. If it is a text media type,
1224          *         it is assumed to contain a {@code "charset=utf-16"}
1225          *         parameter.
1226          * @throws NullPointerException if {@code mimeType} is {@code null}
1227          * @throws IllegalArgumentException if {@code mimeType} does not obey
1228          *         the syntax for a MIME media type string



1229          */
1230         public READER (String mimeType) {
1231             super (mimeType, "java.io.Reader");
1232         }
1233 
1234         /**
1235          * Doc flavor with MIME type = {@code "text/plain; charset=utf-16"},
1236          * print data representation class name = {@code "java.io.Reader"}
1237          * (character stream).
1238          */
1239         public static final READER TEXT_PLAIN =
1240             new READER ("text/plain; charset=utf-16");
1241 
1242         /**
1243          * Doc flavor with MIME type = {@code "text/html; charset=utf-16"},
1244          * print data representation class name = {@code "java.io.Reader"}
1245          * (character stream).
1246          */
1247         public static final READER TEXT_HTML =
1248             new READER ("text/html; charset=utf-16");
1249 
1250     }
1251 
1252     /**
1253      * Class {@code DocFlavor.SERVICE_FORMATTED} provides predefined static
1254      * constant {@code DocFlavor} objects for example doc flavors for service
1255      * formatted print data.
1256      *
1257      * @author Alan Kaminsky
1258      */
1259     public static class SERVICE_FORMATTED extends DocFlavor {
1260 
1261         /**
1262          * Use serialVersionUID from JDK 1.4 for interoperability.
1263          */
1264         private static final long serialVersionUID = 6181337766266637256L;
1265 
1266         /**
1267          * Constructs a new doc flavor with a MIME type of
1268          * {@code "application/x-java-jvm-local-objectref"} indicating service
1269          * formatted print data and the given print data representation class
1270          * name.
1271          *
1272          * @param  className fully-qualified representation class name
1273          * @throws NullPointerException if {@code className} is {@code null}



1274          */
1275         public SERVICE_FORMATTED (String className) {
1276             super ("application/x-java-jvm-local-objectref", className);
1277         }
1278 
1279         /**
1280          * Service formatted print data doc flavor with print data
1281          * representation class name =
1282          * {@code "java.awt.image.renderable.RenderableImage"} (renderable image
1283          * object).
1284          */
1285         public static final SERVICE_FORMATTED RENDERABLE_IMAGE =
1286             new SERVICE_FORMATTED("java.awt.image.renderable.RenderableImage");
1287 
1288         /**
1289          * Service formatted print data doc flavor with print data
1290          * representation class name = {@code "java.awt.print.Printable"}
1291          * (printable object).
1292          */
1293         public static final SERVICE_FORMATTED PRINTABLE =
1294             new SERVICE_FORMATTED ("java.awt.print.Printable");
1295 
1296         /**
1297          * Service formatted print data doc flavor with print data
1298          * representation class name = {@code "java.awt.print.Pageable"}
1299          * (pageable object).
1300          */
1301         public static final SERVICE_FORMATTED PAGEABLE =
1302             new SERVICE_FORMATTED ("java.awt.print.Pageable");
1303 
1304         }

1305 }
< prev index next >