/*
 * @(#)DocFlavor.java	1.20 06/04/05
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.print;

import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.Serializable;

import java.util.Map;

/**
 * Class <code>DocFlavor</code> encapsulates an object that specifies the 
 * format in which print data is supplied to a {@link 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: 
 * <UL>
 * <LI>
 * <B>MIME type.</B> This is a Multipurpose Internet Mail Extensions (MIME) 
 * media type (as defined in <A HREF="http://www.ietf.org/rfc/rfc2045.txt">RFC 
 * 2045</A> and <A HREF="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</A>)
 * that specifies how the print data is to be interpreted.
 * The charset of text data should be the IANA MIME-preferred name, or its
 * canonical name if no preferred name is specified. Additionally a few
 * 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() <CODE>Class.getName()</CODE>} method. 
 * (Thus the class name for <CODE>byte[]</CODE> is <CODE>"[B"</CODE>, for 
 * <CODE>char[]</CODE> it is <CODE>"[C"</CODE>.) 
 * </UL>
 * <P>
 * A <code>DocPrintJob</code> obtains its print data by means of interface 
 * {@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>
 * For <B>client formatted print data</B>, 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.
 * <p>
 * The doc flavor's representation class is a conduit for the JPS
 * <code>DocPrintJob</code> 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) <A 
 * HREF="http://www.isi.edu/in-notes/iana/assignments/media-types/">Media Types 
 * Directory</A>. Interface {@link Doc Doc} provides two utility operations, 
 * {@link Doc#getReaderForText() getReaderForText} and 
 * {@link Doc#getStreamForBytes() getStreamForBytes()}, to help a 
 * <code>Doc</code> object's client extract client formatted print data. 
 * <P>
 * For client formatted print data, the print data representation class is 
 * typically one of the following (although other representation classes are 
 * permitted): 
 * <UL>
 * <LI>
 * Character array (<CODE>char[]</CODE>) -- The print data consists of the 
 * Unicde 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