1 /*
2 * Copyright (c) 2000, 2001, 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
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 * <P>
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 * <P>
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,
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 * <P>
108 * <HR>
109 */
110 public interface Doc {
111
112 /**
113 * Determines the doc flavor in which this doc object will supply its
114 * piece of print data.
115 *
116 * @return Doc flavor.
117 */
118 public DocFlavor getDocFlavor();
119
120 /**
121 * Obtains the print data representation object that contains this doc
122 * object's piece of print data in the format corresponding to the
123 * supported doc flavor.
124 * The <CODE>getPrintData()</CODE> method returns an instance of
125 * the representation class whose name is given by <CODE>{@link
126 * #getDocFlavor() getDocFlavor()}.{@link
127 * DocFlavor#getRepresentationClassName()
|
1 /*
2 * Copyright (c) 2000, 2013, 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
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,
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()
|