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 |