1 /*
2 * Copyright (c) 2000, 2007, 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.OutputStream;
29
30 import java.util.ArrayList;
31 import java.util.Iterator;
32
33 import javax.print.DocFlavor;
34
35 import sun.awt.AppContext;
36 import java.util.ServiceLoader;
37 import java.util.ServiceConfigurationError;
38
39 /**
40 * A <code>StreamPrintServiceFactory</code> is the factory for
41 * {@link StreamPrintService} instances,
42 * which can print to an output stream in a particular
43 * document format described as a mime type.
44 * A typical output document format may be Postscript(TM).
45 * <p>
46 * This class is implemented by a service and located by the
47 * implementation using the
48 * <a href="../../../technotes/guides/jar/jar.html#Service Provider">
49 * SPI JAR File specification</a>.
50 * <p>
51 * Applications locate instances of this class by calling the
52 * {@link #lookupStreamPrintServiceFactories(DocFlavor, String)} method.
53 * <p>
54 * Applications can use a <code>StreamPrintService</code> obtained from a
55 * factory in place of a <code>PrintService</code> which represents a
56 * physical printer device.
57 */
58
59 public abstract class StreamPrintServiceFactory {
60
61 static class Services {
62 private ArrayList listOfFactories = null;
63 }
64
65 private static Services getServices() {
66 Services services =
67 (Services)AppContext.getAppContext().get(Services.class);
68 if (services == null) {
69 services = new Services();
70 AppContext.getAppContext().put(Services.class, services);
71 }
72 return services;
73 }
74
75 private static ArrayList getListOfFactories() {
76 return getServices().listOfFactories;
77 }
78
79 private static ArrayList initListOfFactories() {
80 ArrayList listOfFactories = new ArrayList();
81 getServices().listOfFactories = listOfFactories;
82 return listOfFactories;
83 }
84
85 /**
86 * Locates factories for print services that can be used with
87 * a print job to output a stream of data in the
88 * format specified by {@code outputMimeType}.
89 * <p>
90 * The {@code outputMimeType} parameter describes the document type that
91 * you want to create, whereas the {@code flavor} parameter describes the
92 * format in which the input data will be provided by the application
93 * to the {@code StreamPrintService}.
94 * <p>
95 * Although null is an acceptable value to use in the lookup of stream
96 * printing services, it's typical to search for a particular
97 * desired format, such as Postscript(TM).
98 * <p>
99 * @param flavor of the input document type - null means match all
100 * types.
101 * @param outputMimeType representing the required output format, used to
102 * identify suitable stream printer factories. A value of null means
103 * match all formats.
104 * @return - matching factories for stream print service instance,
105 * empty if no suitable factories could be located.
106 */
107 public static StreamPrintServiceFactory[]
108 lookupStreamPrintServiceFactories(DocFlavor flavor,
109 String outputMimeType) {
110
111 ArrayList list = getFactories(flavor, outputMimeType);
112 return (StreamPrintServiceFactory[])
113 (list.toArray(new StreamPrintServiceFactory[list.size()]));
114 }
115
116 /** Queries the factory for the document format that is emitted
117 * by printers obtained from this factory.
118 *
119 * @return the output format described as a mime type.
120 */
121 public abstract String getOutputFormat();
122
123 /**
124 * Queries the factory for the document flavors that can be accepted
125 * by printers obtained from this factory.
126 * @return array of supported doc flavors.
127 */
128 public abstract DocFlavor[] getSupportedDocFlavors();
129
130 /**
131 * Returns a <code>StreamPrintService</code> that can print to
132 * the specified output stream.
133 * The output stream is created and managed by the application.
134 * It is the application's responsibility to close the stream and
135 * to ensure that this Printer is not reused.
136 * The application should not close this stream until any print job
137 * created from the printer is complete. Doing so earlier may generate
138 * a <code>PrinterException</code> and an event indicating that the
139 * job failed.
140 * <p>
141 * Whereas a <code>PrintService</code> connected to a physical printer
142 * can be reused,
143 * a <code>StreamPrintService</code> connected to a stream cannot.
144 * The underlying <code>StreamPrintService</code> may be disposed by
145 * the print system with
146 * the {@link StreamPrintService#dispose() dispose} method
147 * before returning from the
148 * {@link DocPrintJob#print(Doc, javax.print.attribute.PrintRequestAttributeSet) print}
149 * method of <code>DocPrintJob</code> so that the print system knows
150 * this printer is no longer usable.
151 * This is equivalent to a physical printer going offline - permanently.
152 * Applications may supply a null print stream to create a queryable
153 * service. It is not valid to create a PrintJob for such a stream.
154 * Implementations which allocate resources on construction should examine
155 * the stream and may wish to only allocate resources if the stream is
156 * non-null.
157 * <p>
158 * @param out destination stream for generated output.
159 * @return a PrintService which will generate the format specified by the
160 * DocFlavor supported by this Factory.
161 */
162 public abstract StreamPrintService getPrintService(OutputStream out);
163
164
165 private static ArrayList getAllFactories() {
166 synchronized (StreamPrintServiceFactory.class) {
167
168 ArrayList listOfFactories = getListOfFactories();
169 if (listOfFactories != null) {
170 return listOfFactories;
171 } else {
172 listOfFactories = initListOfFactories();
173 }
174
175 try {
176 java.security.AccessController.doPrivileged(
177 new java.security.PrivilegedExceptionAction() {
178 public Object run() {
179 Iterator<StreamPrintServiceFactory> iterator =
180 ServiceLoader.load
181 (StreamPrintServiceFactory.class).iterator();
182 ArrayList lof = getListOfFactories();
183 while (iterator.hasNext()) {
184 try {
185 lof.add(iterator.next());
186 } catch (ServiceConfigurationError err) {
187 /* In the applet case, we continue */
188 if (System.getSecurityManager() != null) {
189 err.printStackTrace();
190 } else {
191 throw err;
192 }
193 }
194 }
195 return null;
196 }
197 });
198 } catch (java.security.PrivilegedActionException e) {
199 }
200 return listOfFactories;
201 }
202 }
203
204 private static boolean isMember(DocFlavor flavor, DocFlavor[] flavors) {
205 for (int f=0; f<flavors.length; f++ ) {
206 if (flavor.equals(flavors[f])) {
207 return true;
208 }
209 }
210 return false;
211 }
212
213 private static ArrayList getFactories(DocFlavor flavor, String outType) {
214
215 if (flavor == null && outType == null) {
216 return getAllFactories();
217 }
218
219 ArrayList list = new ArrayList();
220 Iterator iterator = getAllFactories().iterator();
221 while (iterator.hasNext()) {
222 StreamPrintServiceFactory factory =
223 (StreamPrintServiceFactory)iterator.next();
224 if ((outType == null ||
225 outType.equalsIgnoreCase(factory.getOutputFormat())) &&
226 (flavor == null ||
227 isMember(flavor, factory.getSupportedDocFlavors()))) {
228 list.add(factory);
229 }
230 }
231
232 return list;
233 }
234
235 }