Class DocFlavor

java.lang.Object sample code for java.lang.Object definition code for java.lang.Object 
  extended by javax.print.DocFlavor
All Implemented Interfaces:
Serializable sample code for definition code for , Cloneable sample code for java.lang.Cloneable definition code for java.lang.Cloneable
Direct Known Subclasses:
DocFlavor.BYTE_ARRAY sample code for javax.print.DocFlavor.BYTE_ARRAY definition code for javax.print.DocFlavor.BYTE_ARRAY , DocFlavor.CHAR_ARRAY sample code for javax.print.DocFlavor.CHAR_ARRAY definition code for javax.print.DocFlavor.CHAR_ARRAY , DocFlavor.INPUT_STREAM sample code for javax.print.DocFlavor.INPUT_STREAM definition code for javax.print.DocFlavor.INPUT_STREAM , DocFlavor.READER sample code for javax.print.DocFlavor.READER definition code for javax.print.DocFlavor.READER , DocFlavor.SERVICE_FORMATTED sample code for javax.print.DocFlavor.SERVICE_FORMATTED definition code for javax.print.DocFlavor.SERVICE_FORMATTED , DocFlavor.STRING sample code for javax.print.DocFlavor.STRING definition code for javax.print.DocFlavor.STRING , DocFlavor.URL sample code for javax.print.DocFlavor.URL definition code for javax.print.DocFlavor.URL

public class DocFlavor
extends Object sample code for java.lang.Object definition code for java.lang.Object
implements Serializable sample code for definition code for , Cloneable sample code for java.lang.Cloneable definition code for java.lang.Cloneable

Class DocFlavor encapsulates an object that specifies the format in which print data is supplied to a DocPrintJob sample code for javax.print.DocPrintJob definition code for javax.print.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 sample code for javax.print.Doc definition code for javax.print.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 sample code for javax.print.Doc definition code for javax.print.Doc provides two utility operations, getReaderForText sample code for javax.print.Doc.getReaderForText() definition code for javax.print.Doc.getReaderForText() and getStreamForBytes() sample code for javax.print.Doc.getStreamForBytes() definition code for javax.print.Doc.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 sample code for javax.print.DocFlavor.hostEncoding definition code for javax.print.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.