/*
 * @(#)Doc.java	1.6 03/01/23
 *
 * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.print;

import java.io.InputStream;
import java.io.IOException;
import java.io.Reader;
import java.io.UnsupportedEncodingException;

import javax.print.attribute.AttributeSet;
import javax.print.attribute.DocAttributeSet;


/**
 * Interface Doc specifies the interface for an object that supplies one piece 
 * of print data for a Print Job. "Doc" is a short, easy-to-pronounce term     
 * that means "a piece of print data." The client passes to the Print Job an
 * object that implements interface Doc, and the Print Job calls methods on
 * that object to obtain the print data. The Doc interface lets a Print Job: 
 * <UL>
 * <LI>
 * Determine the format, or "doc flavor" (class {@link DocFlavor DocFlavor}),
 * in which the print data is available. A doc flavor designates the print 
 * data format (a MIME type) and the representation class of the object
 * from which the print data comes. 
 * <P>
 * <LI>
 * Obtain the print data representation object, which is an instance of the  
 * doc flavor's representation class. The Print Job can then obtain the actual
 * print data from the representation object.
 * <P>
 * <LI>
 * Obtain the printing attributes that specify additional characteristics of  
 * the doc or that specify processing instructions to be applied to the doc. 
 * Printing attributes are defined in package {@link javax.print.attribute 
 * javax.print.attribute}. The doc returns its printing attributes stored in 
 * an {@link javax.print.attribute.DocAttributeSet javax.print.attribute.DocAttributeSet}. 
 * </UL>
 * <P>
 * Each method in an implementation of interface Doc is permitted always to 
 * return the same object each time the method is called.
 * This has implications 
 * for a Print Job or other caller of a doc object whose print data 
 * representation object "consumes" the print data as the caller obtains the 
 * print data, such as a print data representation object which is a stream. 
 * Once the Print Job has called {@link #getPrintData() 
 * <CODE>getPrintData()</CODE>} and obtained the stream, any further calls to 
 * {@link #getPrintData() <CODE>getPrintData()</CODE>} will return the same 
 * stream object upon which reading may already be in progress, <I>not</I> a new 
 * stream object that will re-read the print data from the beginning. Specifying 
 * a doc object to behave this way simplifies the implementation of doc objects, 
 * and is justified on the grounds that a particular doc is intended to convey 
 * print data only to one Print Job, not to several different Print Jobs. (To 
 * convey the same print data to several different Print Jobs, you have to 
 * create several different doc objects on top of the same print data source.) 
 * <P>
 * Interface Doc affords considerable implementation flexibility. The print data 
 * might already be in existence when the doc object is constructed. In this 
 * case the objects returned by the doc's methods can be supplied to the doc's 
 * constructor, be stored in the doc ahead of time, and simply be returned when 
 * called for. Alternatively, the print data might not exist yet when the doc 
 * object is constructed. In this case the doc object might provide a "lazy" 
 * implementation that generates the print data representation object (and/or 
 * the print data) only when the Print Job calls for it (when the Print Job 
 * calls the {@link #getPrintData() <CODE>getPrintData()</CODE>} method). 
 * <P>
 * There is no restriction on the number of client threads that may be 
 * simultaneously accessing the same doc. Therefore, all implementations of 
 * interface Doc must be designed to be multiple thread safe. 
 * <p>
 * However there can only be one consumer of the print data obtained from a
 * Doc.
 * <p>
 * If print data is obtained from the client as a stream, by calling Doc's
 * <code>getReaderForText()</code> or <code>getStreamForBytes()</code>
 * methods, or because the print data source is already an InputStream or
 * Reader, then the print service should always close these streams for the
 * client on all job completion conditions. With the following caveat.
 * If the print data is itself a stream, the service will always close it.
 * If the print data is otherwise something that can be requested as a stream,
 * the service will only close the stream if it has obtained the stream before
 * terminating. That is, just because a print service might request data as
 * a stream does not mean that it will, with the implications that Doc
 * implementors which rely on the service to close them should create such
 * streams only in response to a request from the service.
 * <P>
 * <HR>
 */
public interface Doc {

    /**
     * Determines the doc flavor in which this doc object will supply its
     * piece of print data. 
     *
     * @return  Doc flavor.
     */
    public DocFlavor getDocFlavor();
    
    /**
     * Obtains the print data representation object that contains this doc 
     * object's piece of print data in the format corresponding to the
     * supported doc flavor.
     * The <CODE>getPrintData()</CODE> method returns an instance of 
     * the representation class whose name is given by <CODE>{@link 
     * #getDocFlavor() getDocFlavor()}.{@link 
     * DocFlavor#getRepresentationClassName() 
     * getRepresentationClassName()}</CODE>, and the return value can be cast 
     * from class Object to that representation class. 
     *
     * @return  Print data representation object. 
     *
     * @exception  IOException
     *     Thrown if the representation class is a stream and there was an I/O 
     *     error while constructing the stream. 
     */
    public Object getPrintData() throws IOException;
    
    /**
     * Obtains the set of printing attributes for this doc object. If the 
     * returned attribute set includes an instance of a particular attribute 
     * <I>X,</I> the printer must use that attribute value for this doc, 
     * overriding any value of attribute <I>X</I> in the job's attribute set. 
     * If the returned attribute set does not include an instance 
     * of a particular attribute <I>X</I> or if null is returned, the printer 
     * must consult the job's attribute set to obtain the value for 
     * attribute <I>X,</I> and if not found there, the printer must use an 
     * implementation-dependent default value. The returned attribute set is 
     * unmodifiable. 
     *
     * @return  Unmodifiable set of printing attributes for this doc, or null
     *          to obtain all attribute values from the job's attribute 
     *          set. 
     */
    public DocAttributeSet getAttributes();
    
    /**
     * Obtains a reader for extracting character print data from this doc.
     * The Doc implementation is required to support this method if the 
     * DocFlavor has one of the following print data representation classes,
     * and return null otherwise:
     * <UL>
     * <LI> char[]
     * <LI> java.lang.String
     * <LI> java.io.Reader
     * </UL>
     * The doc's print data representation object is used to construct and
     * return a Reader for reading the print data as a stream of characters
     * from the print data representation object.
     * However, if the print data representation object is itself a Reader,
     * then the print data representation object is simply returned.
     * <P>
     * @return  Reader for reading the print data characters from this doc.
     *          If a reader cannot be provided because this doc does not meet
     *          the criteria stated above, null is returned. 
     *
     * @exception  IOException
     *     Thrown if there was an I/O error while creating the reader.
     */
    public Reader getReaderForText() throws IOException;
    
    /**
     * Obtains an input stream for extracting byte print data from this
     * doc.  The Doc implementation is required to support this method if
     * the DocFlavor has one of the following print data representation
     * classes, and return null otherwise:
     * <UL>
     * <LI> byte[]
     * <LI> java.io.InputStream
     * </UL>
     * This doc's print data representation object is obtained, then an input 
     * stream for reading the print data from the print data representation 
     * object as a stream of bytes is created and returned. However, if the 
     * print data representation object is itself an input stream, then the 
     * print data representation object is simply returned. 
     * <P>
     * @return  Input stream for reading the print data bytes from this doc. If
     *          an input stream cannot be provided because this doc does not 
     *          meet the criteria stated above, null is returned. 
     *
     * @exception  IOException
     *     Thrown if there was an I/O error while creating the input stream.
     */
    public InputStream getStreamForBytes() throws IOException;
    
}