KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > print > Doc


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