JavaTM 2 Platform
Standard Ed. 5.0

Class DocFlavor

  extended by javax.print.DocFlavor
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:

public class DocFlavor
extends Object
implements Serializable, Cloneable

Class 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:

A 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.

Client Formatted Print Data

There are two broad categories of print data, client formatted print data and service formatted 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):

Default and Platform Encodings

For byte print data where the doc flavor's MIME type does not include a 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 gurantee that two VM's 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.

Recommended DocFlavors

The Java Print Service API does not define any mandatorily supported 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.