Serializable
, Cloneable
DocFlavor.BYTE_ARRAY
, DocFlavor.CHAR_ARRAY
, DocFlavor.INPUT_STREAM
, DocFlavor.READER
, DocFlavor.SERVICE_FORMATTED
, DocFlavor.STRING
, DocFlavor.URL
public class DocFlavor extends Object implements Serializable, Cloneable
DocFlavor
encapsulates an object that specifies the format in which print data is supplied to a DocPrintJob
. "Doc" is a short, easy-to-pronounce term that means "a piece of print data." The print data format, or "doc flavor", consists of two things: Class.getName()
method. (Thus the class name for byte[]
is "[B"
, for char[]
it is "[C"
.) DocPrintJob
obtains its print data by means of interface Doc
. A Doc
object lets the DocPrintJob
determine the doc flavor the client can supply. A Doc
object also lets the DocPrintJob
obtain an instance of the doc flavor's representation class, from which the DocPrintJob
then obtains the actual print data. For client formatted print data, the client determines or knows the print data format. For example the client may have a JPEG encoded image, a URL
for HTML code, or a disk file containing plain text in some encoding, possibly obtained from an external source, and requires a way to describe the data format to the print service.
The doc flavor's representation class is a conduit for the JPS DocPrintJob
to obtain a sequence of characters or bytes from the client. The doc flavor's MIME type is one of the standard media types telling how to interpret the sequence of characters or bytes. For a list of standard media types, see the Internet Assigned Numbers Authority's (IANA's) Media Types Directory . Interface Doc
provides two utility operations, getReaderForText
and getStreamForBytes()
, to help a Doc
object's client extract client formatted print data.
For client formatted print data, the print data representation class is typically one of the following (although other representation classes are permitted):
char[]
) -- The print data consists of the Unicode characters in the array. String
-- The print data consists of the Unicode characters in the string. java.io.Reader
) -- The print data consists of the Unicode characters read from the stream up to the end-of-stream. byte[]
) -- 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. 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, the default character set is US-ASCII. URL
) -- The print data consists of the bytes read from the URL location. 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. When the representation class is a URL
, the print service itself accesses and downloads the document directly from its URL
address, without involving the client. The service may be some form of network print service which is executing in a different environment. This means you should not use a URL
print data flavor to print a document at a restricted URL
that the client can see but the printer cannot see. This also means you should not use a URL
print data flavor to print a document stored in a local file that is not available at a URL
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. charset
parameter, the Java Print Service instance assumes the US-ASCII character set by default. This is in accordance with RFC 2046, which says the default character set is US-ASCII. Note that US-ASCII is a subset of UTF-8, so in the future this may be widened if a future RFC endorses UTF-8 as the default in a compatible manner. Also note that this is different than the behaviour of the Java runtime when interpreting a stream of bytes as text data. That assumes the default encoding for the user's locale. Thus, when spooling a file in local encoding to a Java Print Service it is important to correctly specify the encoding. Developers working in the English locales should be particularly conscious of this, as their platform encoding corresponds to the default mime charset. By this coincidence that particular case may work without specifying the encoding of platform data.
Every instance of the Java virtual machine has a default character encoding determined during virtual-machine startup and typically depends upon the locale and charset being used by the underlying operating system. In a distributed environment there is no guarantee that two VM share the same default encoding. Thus clients which want to stream platform encoded text data from the host platform to a Java Print Service instance must explicitly declare the charset and not rely on defaults.
The preferred form is the official IANA primary name for an encoding. Applications which stream text data should always specify the charset in the mime type, which necessitates obtaining the encoding of the host platform for data (eg files) stored in that platform's encoding. A CharSet
which corresponds to this and is suitable for use in a mime-type for a DocFlavor
can be obtained from 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.
See character encodings for more information on the character encodings supported on the Java platform.
DocFlavors
. However, here are some examples of MIME types that a Java Print Service instance might support for client formatted print data. 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. MIME-Type | Description |
---|---|
"text/plain" |
Plain text in the default character set (US-ASCII) |
"text/plain; charset=xxx" |
Plain text in character set xxx |
"text/html" |
HyperText Markup Language in the default character set (US-ASCII) |
"text/html; charset=xxx" |
HyperText Markup Language in character set xxx |
MIME-Type | Description |
---|---|
"application/pdf" |
Portable Document Format document |
"application/postscript" |
PostScript document |
"application/vnd.hp-PCL" |
Printer Control Language document |
InputStream
, URL
). MIME-Type | Description |
---|---|
"image/gif" |
Graphics Interchange Format image |
"image/jpeg" |
Joint Photographic Experts Group image |
"image/png" |
Portable Network Graphics image |
InputStream
, URL
). MIME-Type | Description |
---|---|
"application/octet-stream" |
The print data format is unspecified (just an octet stream) |
InputStream
, URL
). DocPrintJob
invokes to determine the content to be printed -- such as a renderable image interface or a Java printable interface. The doc flavor's MIME type is the special value "application/x-java-jvm-local-objectref"
indicating the client will supply a reference to a Java object that implements the interface named as the representation class. This MIME type is just a placeholder; what's important is the print data representation class. For service formatted print data, the print data representation class is typically one of the following (although other representation classes are permitted). 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.
RenderableImage
. The printer calls methods in that interface to obtain the image to be printed. 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. 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. ("text/plain", "java.io.InputStream")
("text/plain; charset=us-ascii", "java.io.InputStream")
("text/plain; charset=utf-8", "java.io.InputStream")
("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")
Support for the above doc flavors is desirable so a printing client can rely on being able to print on any JPS printer, regardless of which doc flavors the printer supports. If the printer doesn't support the client's preferred doc flavor, the client can at least print plain text, or the client can convert its data to a renderable image and print the image.
Furthermore, every Java Print Service instance must fulfill these requirements for processing plain text print data:
DocFlavor
in package javax.print
is similar to class DataFlavor
. Class DataFlavor
is not used in the Java Print Service (JPS) API for three reasons which are all rooted in allowing the JPS API to be shared by other print services APIs which may need to run on Java profiles which do not include all of the Java Platform, Standard Edition. java.awt.datatransfer.DataFlavor
does not guarantee that equivalent data flavors will have the same serialized representation. DocFlavor
does, and can be used in services which need this. java.awt.datatransfer.DataFlavor
includes a human presentable name as part of the serialized representation. This is not appropriate as part of a service matching constraint. DocFlavor
's serialized representation uses the following canonical form of a MIME type string. Thus, two doc flavors with MIME types that are not identical but that are equivalent (that have the same canonical form) may be considered equal. DocFlavor
's serialized representation also contains the fully-qualified class name of the representation class (a String
object), rather than the representation class itself (a Class
object). This allows a client to examine the doc flavors a Java Print Service instance supports without having to load the representation classes, which may be problematic for limited-resource clients.Modifier and Type | Class | Description |
---|---|---|
static class |
DocFlavor.BYTE_ARRAY |
Class DocFlavor.BYTE_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a byte array (byte[] ) as the print data representation class. |
static class |
DocFlavor.CHAR_ARRAY |
Class DocFlavor.CHAR_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a character array (char[] ) as the print data representation class. |
static class |
DocFlavor.INPUT_STREAM |
Class DocFlavor.INPUT_STREAM provides predefined static constant DocFlavor objects for example doc flavors using a byte stream (java.io.InputStream ) as the print data representation class. |
static class |
DocFlavor.READER |
Class DocFlavor.READER provides predefined static constant DocFlavor objects for example doc flavors using a character stream (java.io.Reader ) as the print data representation class. |
static class |
DocFlavor.SERVICE_FORMATTED |
Class DocFlavor.SERVICE_FORMATTED provides predefined static constant DocFlavor objects for example doc flavors for service formatted print data. |
static class |
DocFlavor.STRING |
Class DocFlavor.STRING provides predefined static constant DocFlavor objects for example doc flavors using a string (java.lang.String ) as the print data representation class. |
static class |
DocFlavor.URL |
Class DocFlavor.URL provides predefined static constant DocFlavor objects. |
Modifier and Type | Field | Description |
---|---|---|
static final String |
hostEncoding |
A string representing the host operating system encoding. |
Constructor | Description |
---|---|
DocFlavor |
Constructs a new doc flavor object from the given MIME type and representation class name. |
Modifier and Type | Method | Description |
---|---|---|
boolean |
equals |
Determines if this doc flavor object is equal to the given object. |
String |
getMediaSubtype() |
Returns this doc flavor object's media subtype (from the MIME type). |
String |
getMediaType() |
Returns this doc flavor object's media type (from the MIME type). |
String |
getMimeType() |
Returns this doc flavor object's MIME type string based on the canonical form. |
String |
getParameter |
Returns a String representing a MIME parameter. |
String |
getRepresentationClassName() |
Returns the name of this doc flavor object's representation class. |
int |
hashCode() |
Returns a hash code for this doc flavor object. |
String |
toString() |
Converts this DocFlavor to a string. |
public static final String hostEncoding
DocFlavor
. This is the charset for all the "HOST" pre-defined DocFlavors
in the executing VM.public DocFlavor(String mimeType, String className)
mimeType
- MIME media type stringclassName
- fully-qualified representation class nameNullPointerException
- if mimeType
or className
is null
IllegalArgumentException
- if mimeType
does not obey the syntax for a MIME media type stringpublic String getMimeType()
public String getMediaType()
public String getMediaSubtype()
public String getParameter(String paramName)
String
representing a MIME parameter. Mime types may include parameters which are usually optional. The charset for text types is a commonly useful example. This convenience method will return the value of the specified parameter if one was specified in the mime type for this flavor.paramName
- the name of the parameter. This name is internally converted to the canonical lower case format before performing the match.null
if that parameter is not in the mime type stringNullPointerException
- if paramName is null
public String getRepresentationClassName()
public String toString()
DocFlavor
to a string.public int hashCode()
public boolean equals(Object obj)
null
, is an instance of DocFlavor
, has a MIME type equivalent to this doc flavor object's MIME type (that is, the MIME types have the same media type, media subtype, and parameters), and has the same representation class name as this doc flavor object. Thus, if two doc flavor objects' MIME types are the same except for comments, they are considered equal. However, two doc flavor objects with MIME types of "text/plain" and "text/plain; charset=US-ASCII" are not considered equal, even though they represent the same media type (because the default character set for plain text is US-ASCII).
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/print/DocFlavor.html