src/share/classes/javax/print/DocFlavor.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
--- 1,7 ----
/*
! * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
*** 47,57 ****
* historical names supported by earlier versions of the Java platform may
* be recognized.
* See <a href="../../java/lang/package-summary.html#charenc">
* character encodings</a> for more information on the character encodings
* supported on the Java platform.
! * <P>
* <LI>
* <B>Representation class name.</B> This specifies the fully-qualified name of
* the class of the object from which the actual print data comes, as returned
* by the {@link java.lang.Class#getName() Class.getName()} method.
* (Thus the class name for <CODE>byte[]</CODE> is <CODE>"[B"</CODE>, for
--- 47,57 ----
* historical names supported by earlier versions of the Java platform may
* be recognized.
* See <a href="../../java/lang/package-summary.html#charenc">
* character encodings</a> for more information on the character encodings
* supported on the Java platform.
! *
* <LI>
* <B>Representation class name.</B> This specifies the fully-qualified name of
* the class of the object from which the actual print data comes, as returned
* by the {@link java.lang.Class#getName() Class.getName()} method.
* (Thus the class name for <CODE>byte[]</CODE> is <CODE>"[B"</CODE>, for
*** 62,72 ****
* {@link Doc Doc}. A <code>Doc</code> object lets the <code>DocPrintJob</code>
* determine the doc flavor the client can supply. A <code>Doc</code> object
* also lets the <code>DocPrintJob</code> obtain an instance of the doc flavor's
* representation class, from which the <code>DocPrintJob</code> then obtains
* the actual print data.
! * <P>
* <HR>
* <H3>Client Formatted Print Data</H3>
* There are two broad categories of print data, client formatted print data
* and service formatted print data.
* <P>
--- 62,72 ----
* {@link Doc Doc}. A <code>Doc</code> object lets the <code>DocPrintJob</code>
* determine the doc flavor the client can supply. A <code>Doc</code> object
* also lets the <code>DocPrintJob</code> obtain an instance of the doc flavor's
* representation class, from which the <code>DocPrintJob</code> then obtains
* the actual print data.
! *
* <HR>
* <H3>Client Formatted Print Data</H3>
* There are two broad categories of print data, client formatted print data
* and service formatted print data.
* <P>
*** 94,119 ****
* permitted):
* <UL>
* <LI>
* Character array (<CODE>char[]</CODE>) -- The print data consists of the
* Unicode characters in the array.
! * <P>
* <LI>
* <code>String</code> --
* The print data consists of the Unicode characters in the string.
! * <P>
* <LI>
* Character stream ({@link java.io.Reader java.io.Reader})
* -- The print data consists of the Unicode characters read from the stream
* up to the end-of-stream.
! * <P>
* <LI>
* Byte array (<CODE>byte[]</CODE>) -- The print data consists of the bytes in
* the array. The bytes are encoded in the character set specified by the doc
* flavor's MIME type. If the MIME type does not specify a character set, the
* default character set is US-ASCII.
! * <P>
* <LI>
* Byte stream ({@link java.io.InputStream java.io.InputStream}) --
* The print data consists of the bytes read from the stream up to the
* end-of-stream. The bytes are encoded in the character set specified by the
* doc flavor's MIME type. If the MIME type does not specify a character set,
--- 94,119 ----
* permitted):
* <UL>
* <LI>
* Character array (<CODE>char[]</CODE>) -- The print data consists of the
* Unicode characters in the array.
! *
* <LI>
* <code>String</code> --
* The print data consists of the Unicode characters in the string.
! *
* <LI>
* Character stream ({@link java.io.Reader java.io.Reader})
* -- The print data consists of the Unicode characters read from the stream
* up to the end-of-stream.
! *
* <LI>
* Byte array (<CODE>byte[]</CODE>) -- The print data consists of the bytes in
* the array. The bytes are encoded in the character set specified by the doc
* flavor's MIME type. If the MIME type does not specify a character set, the
* default character set is US-ASCII.
! *
* <LI>
* Byte stream ({@link java.io.InputStream java.io.InputStream}) --
* The print data consists of the bytes read from the stream up to the
* end-of-stream. The bytes are encoded in the character set specified by the
* doc flavor's MIME type. If the MIME type does not specify a character set,
*** 137,147 ****
* accessible independently of the client.
* For example, a file that is not served up by an HTTP server or FTP server.
* To print such documents, let the client open an input stream on the URL
* or file and use an input stream data flavor.
* </UL>
! * <p>
* <HR>
* <h3>Default and Platform Encodings</h3>
* <P>
* For byte print data where the doc flavor's MIME type does not include a
* <CODE>charset</CODE> parameter, the Java Print Service instance assumes the
--- 137,147 ----
* accessible independently of the client.
* For example, a file that is not served up by an HTTP server or FTP server.
* To print such documents, let the client open an input stream on the URL
* or file and use an input stream data flavor.
* </UL>
! *
* <HR>
* <h3>Default and Platform Encodings</h3>
* <P>
* For byte print data where the doc flavor's MIME type does not include a
* <CODE>charset</CODE> parameter, the Java Print Service instance assumes the
*** 177,191 ****
* from {@link DocFlavor#hostEncoding DocFlavor.hostEncoding}
* This may not always be the primary IANA name but is guaranteed to be
* understood by this VM.
* For common flavors, the pre-defined *HOST DocFlavors may be used.
* <p>
- * <p>
* See <a href="../../java/lang/package-summary.html#charenc">
* character encodings</a> for more information on the character encodings
* supported on the Java platform.
- * <p>
* <HR>
* <h3>Recommended DocFlavors</h3>
* <P>
* The Java Print Service API does not define any mandatorily supported
* DocFlavors.
--- 177,189 ----
*** 194,204 ****
* Nested classes inside class DocFlavor declare predefined static
* constant DocFlavor objects for these example doc flavors; class DocFlavor's
* constructor can be used to create an arbitrary doc flavor.
* <UL>
* <LI>Preformatted text
- * <P>
* <TABLE BORDER=1 CELLPADDING=0 CELLSPACING=0 SUMMARY="MIME-Types and their descriptions">
* <TR>
* <TH>MIME-Type</TH><TH>Description</TH>
* </TR>
* <TR>
--- 192,201 ----
*** 220,232 ****
* </TABLE>
* <P>
* In general, preformatted text print data is provided either in a character
* oriented representation class (character array, String, Reader) or in a
* byte oriented representation class (byte array, InputStream, URL).
! * <P>
* <LI>Preformatted page description language (PDL) documents
! *<P>
* <TABLE BORDER=1 CELLPADDING=0 CELLSPACING=0 SUMMARY="MIME-Types and their descriptions">
* <TR>
* <TH>MIME-Type</TH><TH>Description</TH>
* </TR>
*<TR>
--- 217,229 ----
* </TABLE>
* <P>
* In general, preformatted text print data is provided either in a character
* oriented representation class (character array, String, Reader) or in a
* byte oriented representation class (byte array, InputStream, URL).
! *
* <LI>Preformatted page description language (PDL) documents
! *
* <TABLE BORDER=1 CELLPADDING=0 CELLSPACING=0 SUMMARY="MIME-Types and their descriptions">
* <TR>
* <TH>MIME-Type</TH><TH>Description</TH>
* </TR>
*<TR>
*** 243,255 ****
* </TR>
* </TABLE>
* <P>
* In general, preformatted PDL print data is provided in a byte oriented
* representation class (byte array, InputStream, URL).
! * <P>
* <LI>Preformatted images
! *<P>
* <TABLE BORDER=1 CELLPADDING=0 CELLSPACING=0 SUMMARY="MIME-Types and their descriptions">
* <TR>
* <TH>MIME-Type</TH><TH>Description</TH>
* </TR>
*
--- 240,252 ----
* </TR>
* </TABLE>
* <P>
* In general, preformatted PDL print data is provided in a byte oriented
* representation class (byte array, InputStream, URL).
! *
* <LI>Preformatted images
! *
* <TABLE BORDER=1 CELLPADDING=0 CELLSPACING=0 SUMMARY="MIME-Types and their descriptions">
* <TR>
* <TH>MIME-Type</TH><TH>Description</TH>
* </TR>
*
*** 267,279 ****
* </TR>
* </TABLE>
* <P>
* In general, preformatted image print data is provided in a byte oriented
* representation class (byte array, InputStream, URL).
! * <P>
* <LI>Preformatted autosense print data
! * <P>
* <TABLE BORDER=1 CELLPADDING=0 CELLSPACING=0 SUMMARY="MIME-Types and their descriptions">
* <TR>
* <TH>MIME-Type</TH><TH>Description</TH>
* </TR>
*
--- 264,276 ----
* </TR>
* </TABLE>
* <P>
* In general, preformatted image print data is provided in a byte oriented
* representation class (byte array, InputStream, URL).
! *
* <LI>Preformatted autosense print data
! *
* <TABLE BORDER=1 CELLPADDING=0 CELLSPACING=0 SUMMARY="MIME-Types and their descriptions">
* <TR>
* <TH>MIME-Type</TH><TH>Description</TH>
* </TR>
*
*** 285,295 ****
* The printer decides how to interpret the print data; the way this
* "autosensing" works is implementation dependent. In general, preformatted
* autosense print data is provided in a byte oriented representation class
* (byte array, InputStream, URL).
* </UL>
! * <P>
* <HR>
* <H3>Service Formatted Print Data</H3>
* <P>
* For <B>service formatted print data</B>, the Java Print Service instance
* determines the print data format. The doc flavor's representation class
--- 282,292 ----
* The printer decides how to interpret the print data; the way this
* "autosensing" works is implementation dependent. In general, preformatted
* autosense print data is provided in a byte oriented representation class
* (byte array, InputStream, URL).
* </UL>
! *
* <HR>
* <H3>Service Formatted Print Data</H3>
* <P>
* For <B>service formatted print data</B>, the Java Print Service instance
* determines the print data format. The doc flavor's representation class
*** 313,341 ****
* Renderable image object -- The client supplies an object that implements
* interface
* {@link java.awt.image.renderable.RenderableImage RenderableImage}. The
* printer calls methods
* in that interface to obtain the image to be printed.
! * <P>
* <LI>
* Printable object -- The client supplies an object that implements interface
* {@link java.awt.print.Printable Printable}.
* The printer calls methods in that interface to obtain the pages to be
* printed, one by one.
* For each page, the printer supplies a graphics context, and whatever the
* client draws in that graphics context gets printed.
! * <P>
* <LI>
* Pageable object -- The client supplies an object that implements interface
* {@link java.awt.print.Pageable Pageable}. The printer calls
* methods in that interface to obtain the pages to be printed, one by one.
* For each page, the printer supplies a graphics context, and whatever
* the client draws in that graphics context gets printed.
* </UL>
! * <P>
* <HR>
! * <P>
* <HR>
* <H3>Pre-defined Doc Flavors</H3>
* A Java Print Service instance is not <B><I>required</I></B> to support the
* following print data formats and print data representation classes. In
* fact, a developer using this class should <b>never</b> assume that a
--- 310,338 ----
* Renderable image object -- The client supplies an object that implements
* interface
* {@link java.awt.image.renderable.RenderableImage RenderableImage}. The
* printer calls methods
* in that interface to obtain the image to be printed.
! *
* <LI>
* Printable object -- The client supplies an object that implements interface
* {@link java.awt.print.Printable Printable}.
* The printer calls methods in that interface to obtain the pages to be
* printed, one by one.
* For each page, the printer supplies a graphics context, and whatever the
* client draws in that graphics context gets printed.
! *
* <LI>
* Pageable object -- The client supplies an object that implements interface
* {@link java.awt.print.Pageable Pageable}. The printer calls
* methods in that interface to obtain the pages to be printed, one by one.
* For each page, the printer supplies a graphics context, and whatever
* the client draws in that graphics context gets printed.
* </UL>
! *
* <HR>
! *
* <HR>
* <H3>Pre-defined Doc Flavors</H3>
* A Java Print Service instance is not <B><I>required</I></B> to support the
* following print data formats and print data representation classes. In
* fact, a developer using this class should <b>never</b> assume that a
*** 352,362 ****
* <CODE>("text/plain", "java.io.InputStream")</CODE>
* <BR>·
* <CODE>("text/plain; charset=us-ascii", "java.io.InputStream")</CODE>
* <BR>·
* <CODE>("text/plain; charset=utf-8", "java.io.InputStream")</CODE>
! * <P>
* <LI>
* Renderable image objects. Specifically, the following doc flavor is
* recommended to be supported:
* <BR>·
* <CODE>("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")</CODE>
--- 349,359 ----
* <CODE>("text/plain", "java.io.InputStream")</CODE>
* <BR>·
* <CODE>("text/plain; charset=us-ascii", "java.io.InputStream")</CODE>
* <BR>·
* <CODE>("text/plain; charset=utf-8", "java.io.InputStream")</CODE>
! *
* <LI>
* Renderable image objects. Specifically, the following doc flavor is
* recommended to be supported:
* <BR>·
* <CODE>("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")</CODE>
*** 387,397 ****
* <LI>
* </UL>
* <P>
* The client must itself perform all plain text print data formatting not
* addressed by the above requirements.
! * <P>
* <H3>Design Rationale</H3>
* <P>
* Class DocFlavor in package javax.print.data is similar to class
* {@link java.awt.datatransfer.DataFlavor DataFlavor}. Class
* <code>DataFlavor</code>
--- 384,394 ----
* <LI>
* </UL>
* <P>
* The client must itself perform all plain text print data formatting not
* addressed by the above requirements.
! *
* <H3>Design Rationale</H3>
* <P>
* Class DocFlavor in package javax.print.data is similar to class
* {@link java.awt.datatransfer.DataFlavor DataFlavor}. Class
* <code>DataFlavor</code>
*** 401,417 ****
* which do not include all of the Java Platform, Standard Edition.
* <OL TYPE=1>
* <LI>
* The JPS API is designed to be used in Java profiles which do not support
* AWT.
! * <P>
* <LI>
* The implementation of class <code>java.awt.datatransfer.DataFlavor</code>
* does not guarantee that equivalent data flavors will have the same
* serialized representation. DocFlavor does, and can be used in services
* which need this.
! * <P>
* <LI>
* The implementation of class <code>java.awt.datatransfer.DataFlavor</code>
* includes a human presentable name as part of the serialized representation.
* This is not appropriate as part of a service matching constraint.
* </OL>
--- 398,414 ----
* which do not include all of the Java Platform, Standard Edition.
* <OL TYPE=1>
* <LI>
* The JPS API is designed to be used in Java profiles which do not support
* AWT.
! *
* <LI>
* The implementation of class <code>java.awt.datatransfer.DataFlavor</code>
* does not guarantee that equivalent data flavors will have the same
* serialized representation. DocFlavor does, and can be used in services
* which need this.
! *
* <LI>
* The implementation of class <code>java.awt.datatransfer.DataFlavor</code>
* includes a human presentable name as part of the serialized representation.
* This is not appropriate as part of a service matching constraint.
* </OL>