Specifying Document Types

From the user's perspective, a document can take many different forms, including: a PDF file, an image from a digital camera, an email, a word processor document, or a web page. Before printing a document of a particular format, the client needs to ensure that the printer can understand the format. Sometimes a printer can directly print documents of a given format: photo printers can directly print images of various formats, and PostScript^TM printers can directly print a PostScript^TM document. However, there are few printers that can directly print a wide range of formats; most printers require some higher-level software support to translate the source document into a format they can print.

A printing API needs to provide a way to describe document types so that:

• The printer can report what formats it can print.
• The client can describe the format of the data it wants to print.
• The client can describe the encoding of text data.

The Java^TM Print Service API describes document types using the DocFlavor class. A DocFlavor is comprised of:

• A MIME type that tells the printer how to interpret the data.
• A representation class name indicating the Java class that describes how the data is sent to the printer.

To describe an HTML page to a print service, a client might choose to use a DocFlavor with a MIME type string of "text/html; charset=utf-16" and a representation class name of "java.io.InputStream". The client can obtain this DocFlavor in one of two ways:

• Construct a DocFlavor:DocFlavor htmlStreamFlavor = new DocFlavor("text/html; charset=utf-16", "java.io.InputStream");
• Use the pre-defined instance that represents this type of DocFlavor:DocFlavor.INPUT_STREAM TEXT_HTML_UTF_16 . The Java Print Service API provides a set of pre-defined instances for common doc flavors as a convenience.

Because the HTML page contains text data, the MIME type String includes the text encoding, which is charset=utf-16 in this example. The client is responsible for accurately describing the print data to the print service. The section, Client-Formatted Print Data, explains how to properly construct a DocFlavor to accomplish this. If the text encoding is not included in the MIME type, unexpected results can occur, as explained in the section, Importance of Character Encoding. The client can allow the service to determine the format of data that the client supplies as a Java object. The Service-Formatted Print Data section describes using a DocFlavor to represent service-formatted print data.

Keep in mand that, just because the DocFlavor API has a pre-declared doc flavor, this doesn't mean that an implementation of the particular flavor is available. For example, even if you use the pre-defined DocFlavor representing HTML text in UTF-16, you won't be able to print the HTML unless you have a print service that supports printing HTML. Again, it is the user's responsibility to ensure that a printer supports a particular format.