1 /*
   2  * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.print;
  27 
  28 import java.io.InputStream;
  29 import java.io.IOException;
  30 import java.io.Reader;
  31 
  32 import javax.print.attribute.DocAttributeSet;
  33 
  34 
  35 /**
  36  * Interface Doc specifies the interface for an object that supplies one piece
  37  * of print data for a Print Job. "Doc" is a short, easy-to-pronounce term
  38  * that means "a piece of print data." The client passes to the Print Job an
  39  * object that implements interface Doc, and the Print Job calls methods on
  40  * that object to obtain the print data. The Doc interface lets a Print Job:
  41  * <UL>
  42  * <LI>
  43  * Determine the format, or "doc flavor" (class {@link DocFlavor DocFlavor}),
  44  * in which the print data is available. A doc flavor designates the print
  45  * data format (a MIME type) and the representation class of the object
  46  * from which the print data comes.
  47  *
  48  * <LI>
  49  * Obtain the print data representation object, which is an instance of the
  50  * doc flavor's representation class. The Print Job can then obtain the actual
  51  * print data from the representation object.
  52  *
  53  * <LI>
  54  * Obtain the printing attributes that specify additional characteristics of
  55  * the doc or that specify processing instructions to be applied to the doc.
  56  * Printing attributes are defined in package {@link javax.print.attribute
  57  * javax.print.attribute}. The doc returns its printing attributes stored in
  58  * an {@link javax.print.attribute.DocAttributeSet javax.print.attribute.DocAttributeSet}.
  59  * </UL>
  60  * <P>
  61  * Each method in an implementation of interface Doc is permitted always to
  62  * return the same object each time the method is called.
  63  * This has implications
  64  * for a Print Job or other caller of a doc object whose print data
  65  * representation object "consumes" the print data as the caller obtains the
  66  * print data, such as a print data representation object which is a stream.
  67  * Once the Print Job has called {@link #getPrintData()
  68  * getPrintData()} and obtained the stream, any further calls to
  69  * {@link #getPrintData() getPrintData()} will return the same
  70  * stream object upon which reading may already be in progress, <I>not</I> a new
  71  * stream object that will re-read the print data from the beginning. Specifying
  72  * a doc object to behave this way simplifies the implementation of doc objects,
  73  * and is justified on the grounds that a particular doc is intended to convey
  74  * print data only to one Print Job, not to several different Print Jobs. (To
  75  * convey the same print data to several different Print Jobs, you have to
  76  * create several different doc objects on top of the same print data source.)
  77  * <P>
  78  * Interface Doc affords considerable implementation flexibility. The print data
  79  * might already be in existence when the doc object is constructed. In this
  80  * case the objects returned by the doc's methods can be supplied to the doc's
  81  * constructor, be stored in the doc ahead of time, and simply be returned when
  82  * called for. Alternatively, the print data might not exist yet when the doc
  83  * object is constructed. In this case the doc object might provide a "lazy"
  84  * implementation that generates the print data representation object (and/or
  85  * the print data) only when the Print Job calls for it (when the Print Job
  86  * calls the {@link #getPrintData() getPrintData()} method).
  87  * <P>
  88  * There is no restriction on the number of client threads that may be
  89  * simultaneously accessing the same doc. Therefore, all implementations of
  90  * interface Doc must be designed to be multiple thread safe.
  91  * <p>
  92  * However there can only be one consumer of the print data obtained from a
  93  * Doc.
  94  * <p>
  95  * If print data is obtained from the client as a stream, by calling Doc's
  96  * {@code getReaderForText()} or {@code getStreamForBytes()}
  97  * methods, or because the print data source is already an InputStream or
  98  * Reader, then the print service should always close these streams for the
  99  * client on all job completion conditions. With the following caveat.
 100  * If the print data is itself a stream, the service will always close it.
 101  * If the print data is otherwise something that can be requested as a stream,
 102  * the service will only close the stream if it has obtained the stream before
 103  * terminating. That is, just because a print service might request data as
 104  * a stream does not mean that it will, with the implications that Doc
 105  * implementors which rely on the service to close them should create such
 106  * streams only in response to a request from the service.
 107  * <HR>
 108  */
 109 public interface Doc {
 110 
 111     /**
 112      * Determines the doc flavor in which this doc object will supply its
 113      * piece of print data.
 114      *
 115      * @return  Doc flavor.
 116      */
 117     public DocFlavor getDocFlavor();
 118 
 119     /**
 120      * Obtains the print data representation object that contains this doc
 121      * object's piece of print data in the format corresponding to the
 122      * supported doc flavor.
 123      * The {@code getPrintData()} method returns an instance of
 124      * the representation class whose name is given by {@link
 125      * #getDocFlavor() getDocFlavor()}.{@link
 126      * DocFlavor#getRepresentationClassName()
 127      * getRepresentationClassName()}, and the return value can be cast
 128      * from class Object to that representation class.
 129      *
 130      * @return  Print data representation object.
 131      *
 132      * @exception  IOException
 133      *     Thrown if the representation class is a stream and there was an I/O
 134      *     error while constructing the stream.
 135      */
 136     public Object getPrintData() throws IOException;
 137 
 138     /**
 139      * Obtains the set of printing attributes for this doc object. If the
 140      * returned attribute set includes an instance of a particular attribute
 141      * <I>X,</I> the printer must use that attribute value for this doc,
 142      * overriding any value of attribute <I>X</I> in the job's attribute set.
 143      * If the returned attribute set does not include an instance
 144      * of a particular attribute <I>X</I> or if null is returned, the printer
 145      * must consult the job's attribute set to obtain the value for
 146      * attribute <I>X,</I> and if not found there, the printer must use an
 147      * implementation-dependent default value. The returned attribute set is
 148      * unmodifiable.
 149      *
 150      * @return  Unmodifiable set of printing attributes for this doc, or null
 151      *          to obtain all attribute values from the job's attribute
 152      *          set.
 153      */
 154     public DocAttributeSet getAttributes();
 155 
 156     /**
 157      * Obtains a reader for extracting character print data from this doc.
 158      * The Doc implementation is required to support this method if the
 159      * DocFlavor has one of the following print data representation classes,
 160      * and return null otherwise:
 161      * <UL>
 162      * <LI> char[]
 163      * <LI> java.lang.String
 164      * <LI> java.io.Reader
 165      * </UL>
 166      * The doc's print data representation object is used to construct and
 167      * return a Reader for reading the print data as a stream of characters
 168      * from the print data representation object.
 169      * However, if the print data representation object is itself a Reader,
 170      * then the print data representation object is simply returned.
 171      *
 172      * @return  Reader for reading the print data characters from this doc.
 173      *          If a reader cannot be provided because this doc does not meet
 174      *          the criteria stated above, null is returned.
 175      *
 176      * @exception  IOException
 177      *     Thrown if there was an I/O error while creating the reader.
 178      */
 179     public Reader getReaderForText() throws IOException;
 180 
 181     /**
 182      * Obtains an input stream for extracting byte print data from this
 183      * doc.  The Doc implementation is required to support this method if
 184      * the DocFlavor has one of the following print data representation
 185      * classes, and return null otherwise:
 186      * <UL>
 187      * <LI> byte[]
 188      * <LI> java.io.InputStream
 189      * </UL>
 190      * This doc's print data representation object is obtained, then an input
 191      * stream for reading the print data from the print data representation
 192      * object as a stream of bytes is created and returned. However, if the
 193      * print data representation object is itself an input stream, then the
 194      * print data representation object is simply returned.
 195      *
 196      * @return  Input stream for reading the print data bytes from this doc. If
 197      *          an input stream cannot be provided because this doc does not
 198      *          meet the criteria stated above, null is returned.
 199      *
 200      * @exception  IOException
 201      *     Thrown if there was an I/O error while creating the input stream.
 202      */
 203     public InputStream getStreamForBytes() throws IOException;
 204 
 205 }