< prev index next >

src/java.desktop/share/classes/javax/print/Doc.java

Print this page




  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()</code> or <code>getStreamForBytes()</code>
  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()</CODE> method returns an instance of
 124      * the representation class whose name is given by <CODE>{@link
 125      * #getDocFlavor() getDocFlavor()}.{@link
 126      * DocFlavor#getRepresentationClassName()
 127      * getRepresentationClassName()}</CODE>, 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




  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


< prev index next >