History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/javax/print/PrintService.java (1 of 18352 files). Show all

Unified · Split

java/pkg/javax/print/PrintService.java+488−0
@@ -0,0 +1,488 @@
1+/*
2+ * Copyright (c) 2000, 2006, 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.util.Locale;
29+
30+import javax.print.attribute.Attribute;
31+import javax.print.attribute.AttributeSet;
32+import javax.print.attribute.PrintServiceAttribute;
33+import javax.print.attribute.PrintServiceAttributeSet;
34+import javax.print.event.PrintServiceAttributeListener;
35+
36+
37+/**
38+ * Interface PrintService is the factory for a DocPrintJob. A PrintService
39+ * describes the capabilities of a Printer and can be queried regarding
40+ * a printer's supported attributes.
41+ * <P>
42+ * Example:
43+ * <PRE>
44+ * DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
45+ * PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
46+ * aset.add(MediaSizeName.ISO_A4);
47+ * PrintService[] pservices =
48+ * PrintServiceLookup.lookupPrintServices(flavor, aset);
49+ * if (pservices.length > 0) {
50+ * DocPrintJob pj = pservices[0].createPrintJob();
51+ * try {
52+ * FileInputStream fis = new FileInputStream("test.ps");
53+ * Doc doc = new SimpleDoc(fis, flavor, null);
54+ * pj.print(doc, aset);
55+ * } catch (FileNotFoundException fe) {
56+ * } catch (PrintException e) {
57+ * }
58+ * }
59+ * </PRE>
60+ */
61+public interface PrintService {
62+
63+ /** Returns a String name for this print service which may be used
64+ * by applications to request a particular print service.
65+ * In a suitable context, such as a name service, this name must be
66+ * unique.
67+ * In some environments this unique name may be the same as the user
68+ * friendly printer name defined as the
69+ * {@link javax.print.attribute.standard.PrinterName PrinterName}
70+ * attribute.
71+ * @return name of the service.
72+ */
73+ public String getName();
74+
75+ /**
76+ * Creates and returns a PrintJob capable of handling data from
77+ * any of the supported document flavors.
78+ * @return a DocPrintJob object
79+ */
80+ public DocPrintJob createPrintJob();
81+
82+ /**
83+ * Registers a listener for events on this PrintService.
84+ * @param listener a PrintServiceAttributeListener, which
85+ * monitors the status of a print service
86+ * @see #removePrintServiceAttributeListener
87+ */
88+ public void addPrintServiceAttributeListener(
89+ PrintServiceAttributeListener listener);
90+
91+ /**
92+ * Removes the print-service listener from this print service.
93+ * This means the listener is no longer interested in
94+ * <code>PrintService</code> events.
95+ * @param listener a PrintServiceAttributeListener object
96+ * @see #addPrintServiceAttributeListener
97+ */
98+ public void removePrintServiceAttributeListener(
99+ PrintServiceAttributeListener listener);
100+
101+ /**
102+ * Obtains this print service's set of printer description attributes
103+ * giving this Print Service's status. The returned attribute set object
104+ * is unmodifiable. The returned attribute set object is a "snapshot" of
105+ * this Print Service's attribute set at the time of the
106+ * <CODE>getAttributes()</CODE> method call: that is, the returned
107+ * attribute set's contents will <I>not</I> be updated if this print
108+ * service's attribute set's contents change in the future. To detect
109+ * changes in attribute values, call <CODE>getAttributes()</CODE> again
110+ * and compare the new attribute set to the previous attribute set;
111+ * alternatively, register a listener for print service events.
112+ *
113+ * @return Unmodifiable snapshot of this Print Service's attribute set.
114+ * May be empty, but not null.
115+ */
116+ public PrintServiceAttributeSet getAttributes();
117+
118+ /**
119+ * Gets the value of the single specified service attribute.
120+ * This may be useful to clients which only need the value of one
121+ * attribute and want to minimise overhead.
122+ * @param category the category of a PrintServiceAttribute supported
123+ * by this service - may not be null.
124+ * @return the value of the supported attribute or null if the
125+ * attribute is not supported by this service.
126+ * @exception NullPointerException if the category is null.
127+ * @exception IllegalArgumentException
128+ * (unchecked exception) if <CODE>category</CODE> is not a
129+ * <code>Class</code> that implements interface
130+ *{@link javax.print.attribute.PrintServiceAttribute PrintServiceAttribute}.
131+ */
132+ public <T extends PrintServiceAttribute>
133+ T getAttribute(Class<T> category);
134+
135+ /**
136+ * Determines the print data formats a client can specify when setting
137+ * up a job for this <code>PrintService</code>. A print data format is
138+ * designated by a "doc
139+ * flavor" (class {@link javax.print.DocFlavor DocFlavor})
140+ * consisting of a MIME type plus a print data representation class.
141+ * <P>
142+ * Note that some doc flavors may not be supported in combination
143+ * with all attributes. Use <code>getUnsupportedAttributes(..)</code>
144+ * to validate specific combinations.
145+ *
146+ * @return Array of supported doc flavors, should have at least
147+ * one element.
148+ *
149+ */
150+ public DocFlavor[] getSupportedDocFlavors();
151+
152+ /**
153+ * Determines if this print service supports a specific
154+ * <code>DocFlavor</code>. This is a convenience method to determine
155+ * if the <code>DocFlavor</code> would be a member of the result of
156+ * <code>getSupportedDocFlavors()</code>.
157+ * <p>
158+ * Note that some doc flavors may not be supported in combination
159+ * with all attributes. Use <code>getUnsupportedAttributes(..)</code>
160+ * to validate specific combinations.
161+ *
162+ * @param flavor the <code>DocFlavor</code>to query for support.
163+ * @return <code>true</code> if this print service supports the
164+ * specified <code>DocFlavor</code>; <code>false</code> otherwise.
165+ * @exception NullPointerException
166+ * (unchecked exception) Thrown if <CODE>flavor</CODE> is null.
167+ */
168+ public boolean isDocFlavorSupported(DocFlavor flavor);
169+
170+
171+ /**
172+ * Determines the printing attribute categories a client can specify
173+ * when setting up a job for this print service.
174+ * A printing attribute category is
175+ * designated by a <code>Class</code> that implements interface
176+ * {@link javax.print.attribute.Attribute Attribute}. This method returns
177+ * just the attribute <I>categories</I> that are supported; it does not
178+ * return the particular attribute <I>values</I> that are supported.
179+ * <P>
180+ * This method returns all the printing attribute
181+ * categories this print service supports for any possible job.
182+ * Some categories may not be supported in a particular context (ie
183+ * for a particular <code>DocFlavor</code>).
184+ * Use one of the methods that include a <code>DocFlavor</code> to
185+ * validate the request before submitting it, such as
186+ * <code>getSupportedAttributeValues(..)</code>.
187+ *
188+ * @return Array of printing attribute categories that the client can
189+ * specify as a doc-level or job-level attribute in a Print
190+ * Request. Each element in the array is a {@link java.lang.Class
191+ * Class} that implements interface {@link
192+ * javax.print.attribute.Attribute Attribute}.
193+ * The array is empty if no categories are supported.
194+ */
195+ public Class<?>[] getSupportedAttributeCategories();
196+
197+ /**
198+ * Determines whether a client can specify the given printing
199+ * attribute category when setting up a job for this print service. A
200+ * printing attribute category is designated by a <code>Class</code>
201+ * that implements interface {@link javax.print.attribute.Attribute
202+ * Attribute}. This method tells whether the attribute <I>category</I> is
203+ * supported; it does not tell whether a particular attribute <I>value</I>
204+ * is supported.
205+ * <p>
206+ * Some categories may not be supported in a particular context (ie
207+ * for a particular <code>DocFlavor</code>).
208+ * Use one of the methods which include a <code>DocFlavor</code> to
209+ * validate the request before submitting it, such as
210+ * <code>getSupportedAttributeValues(..)</code>.
211+ * <P>
212+ * This is a convenience method to determine if the category
213+ * would be a member of the result of
214+ * <code>getSupportedAttributeCategories()</code>.
215+ *
216+ * @param category Printing attribute category to test. It must be a
217+ * <code>Class</code> that implements
218+ * interface
219+ * {@link javax.print.attribute.Attribute Attribute}.
220+ *
221+ * @return <code>true</code> if this print service supports
222+ * specifying a doc-level or
223+ * job-level attribute in <CODE>category</CODE> in a Print
224+ * Request; <code>false</code> if it doesn't.
225+ *
226+ * @exception NullPointerException
227+ * (unchecked exception) Thrown if <CODE>category</CODE> is null.
228+ * @exception IllegalArgumentException
229+ * (unchecked exception) Thrown if <CODE>category</CODE> is not a
230+ * <code>Class</code> that implements interface
231+ * {@link javax.print.attribute.Attribute Attribute}.
232+ */
233+ public boolean
234+ isAttributeCategorySupported(Class<? extends Attribute> category);
235+
236+ /**
237+ * Determines this print service's default printing attribute value in
238+ * the given category. A printing attribute value is an instance of
239+ * a class that implements interface
240+ * {@link javax.print.attribute.Attribute Attribute}. If a client sets
241+ * up a print job and does not specify any attribute value in the
242+ * given category, this Print Service will use the
243+ * default attribute value instead.
244+ * <p>
245+ * Some attributes may not be supported in a particular context (ie
246+ * for a particular <code>DocFlavor</code>).
247+ * Use one of the methods that include a <code>DocFlavor</code> to
248+ * validate the request before submitting it, such as
249+ * <code>getSupportedAttributeValues(..)</code>.
250+ * <P>
251+ * Not all attributes have a default value. For example the
252+ * service will not have a defaultvalue for <code>RequestingUser</code>
253+ * i.e. a null return for a supported category means there is no
254+ * service default value for that category. Use the
255+ * <code>isAttributeCategorySupported(Class)</code> method to
256+ * distinguish these cases.
257+ *
258+ * @param category Printing attribute category for which the default
259+ * attribute value is requested. It must be a {@link
260+ * java.lang.Class Class} that implements interface
261+ * {@link javax.print.attribute.Attribute
262+ * Attribute}.
263+ *
264+ * @return Default attribute value for <CODE>category</CODE>, or null
265+ * if this Print Service does not support specifying a doc-level or
266+ * job-level attribute in <CODE>category</CODE> in a Print
267+ * Request, or the service does not have a default value
268+ * for this attribute.
269+ *
270+ * @exception NullPointerException
271+ * (unchecked exception) Thrown if <CODE>category</CODE> is null.
272+ * @exception IllegalArgumentException
273+ * (unchecked exception) Thrown if <CODE>category</CODE> is not a
274+ * {@link java.lang.Class Class} that implements interface {@link
275+ * javax.print.attribute.Attribute Attribute}.
276+ */
277+ public Object
278+ getDefaultAttributeValue(Class<? extends Attribute> category);
279+
280+ /**
281+ * Determines the printing attribute values a client can specify in
282+ * the given category when setting up a job for this print service. A
283+ * printing
284+ * attribute value is an instance of a class that implements interface
285+ * {@link javax.print.attribute.Attribute Attribute}.
286+ * <P>
287+ * If <CODE>flavor</CODE> is null and <CODE>attributes</CODE> is null
288+ * or is an empty set, this method returns all the printing attribute
289+ * values this Print Service supports for any possible job. If
290+ * <CODE>flavor</CODE> is not null or <CODE>attributes</CODE> is not
291+ * an empty set, this method returns just the printing attribute values
292+ * that are compatible with the given doc flavor and/or set of attributes.
293+ * That is, a null return value may indicate that specifying this attribute
294+ * is incompatible with the specified DocFlavor.
295+ * Also if DocFlavor is not null it must be a flavor supported by this
296+ * PrintService, else IllegalArgumentException will be thrown.
297+ * <P>
298+ * If the <code>attributes</code> parameter contains an Attribute whose
299+ * category is the same as the <code>category</code> parameter, the service
300+ * must ignore this attribute in the AttributeSet.
301+ * <p>
302+ * <code>DocAttribute</code>s which are to be specified on the
303+ * <code>Doc</code> must be included in this set to accurately
304+ * represent the context.
305+ * <p>
306+ * This method returns an Object because different printing attribute
307+ * categories indicate the supported attribute values in different ways.
308+ * The documentation for each printing attribute in package {@link
309+ * javax.print.attribute.standard javax.print.attribute.standard}
310+ * describes how each attribute indicates its supported values. Possible
311+ * ways of indicating support include:
312+ * <UL>
313+ * <LI>
314+ * Return a single instance of the attribute category to indicate that any
315+ * value is legal -- used, for example, by an attribute whose value is an
316+ * arbitrary text string. (The value of the returned attribute object is
317+ * irrelevant.)
318+ * <LI>
319+ * Return an array of one or more instances of the attribute category,
320+ * containing the legal values -- used, for example, by an attribute with
321+ * a list of enumerated values. The type of the array is an array of the
322+ * specified attribute category type as returned by its
323+ * <code>getCategory(Class)</code>.
324+ * <LI>
325+ * Return a single object (of some class other than the attribute category)
326+ * that indicates bounds on the legal values -- used, for example, by an
327+ * integer-valued attribute that must lie within a certain range.
328+ * </UL>
329+ * <P>
330+ *
331+ * @param category Printing attribute category to test. It must be a
332+ * {@link java.lang.Class Class} that implements
333+ * interface {@link
334+ * javax.print.attribute.Attribute Attribute}.
335+ * @param flavor Doc flavor for a supposed job, or null.
336+ * @param attributes Set of printing attributes for a supposed job
337+ * (both job-level attributes and document-level
338+ * attributes), or null.
339+ *
340+ * @return Object indicating supported values for <CODE>category</CODE>,
341+ * or null if this Print Service does not support specifying a
342+ * doc-level or job-level attribute in <CODE>category</CODE> in
343+ * a Print Request.
344+ *
345+ * @exception NullPointerException
346+ * (unchecked exception) Thrown if <CODE>category</CODE> is null.
347+ * @exception IllegalArgumentException
348+ * (unchecked exception) Thrown if <CODE>category</CODE> is not a
349+ * {@link java.lang.Class Class} that implements interface {@link
350+ * javax.print.attribute.Attribute Attribute}, or
351+ * <code>DocFlavor</code> is not supported by this service.
352+ */
353+ public Object
354+ getSupportedAttributeValues(Class<? extends Attribute> category,
355+ DocFlavor flavor,
356+ AttributeSet attributes);
357+
358+ /**
359+ * Determines whether a client can specify the given printing
360+ * attribute
361+ * value when setting up a job for this Print Service. A printing
362+ * attribute value is an instance of a class that implements interface
363+ * {@link javax.print.attribute.Attribute Attribute}.
364+ * <P>
365+ * If <CODE>flavor</CODE> is null and <CODE>attributes</CODE> is null or
366+ * is an empty set, this method tells whether this Print Service supports
367+ * the given printing attribute value for some possible combination of doc
368+ * flavor and set of attributes. If <CODE>flavor</CODE> is not null or
369+ * <CODE>attributes</CODE> is not an empty set, this method tells whether
370+ * this Print Service supports the given printing attribute value in
371+ * combination with the given doc flavor and/or set of attributes.
372+ * <p>
373+ * Also if DocFlavor is not null it must be a flavor supported by this
374+ * PrintService, else IllegalArgumentException will be thrown.
375+ * <p>
376+ * <code>DocAttribute</code>s which are to be specified on the
377+ * <code>Doc</code> must be included in this set to accurately
378+ * represent the context.
379+ * <p>
380+ * This is a convenience method to determine if the value
381+ * would be a member of the result of
382+ * <code>getSupportedAttributeValues(...)</code>.
383+ *
384+ * @param attrval Printing attribute value to test.
385+ * @param flavor Doc flavor for a supposed job, or null.
386+ * @param attributes Set of printing attributes for a supposed job
387+ * (both job-level attributes and document-level
388+ * attributes), or null.
389+ *
390+ * @return True if this Print Service supports specifying
391+ * <CODE>attrval</CODE> as a doc-level or job-level attribute in a
392+ * Print Request, false if it doesn't.
393+ *
394+ * @exception NullPointerException
395+ * (unchecked exception) if <CODE>attrval</CODE> is null.
396+ * @exception IllegalArgumentException if flavor is not supported by
397+ * this PrintService.
398+ */
399+ public boolean isAttributeValueSupported(Attribute attrval,
400+ DocFlavor flavor,
401+ AttributeSet attributes);
402+
403+
404+ /**
405+ * Identifies the attributes that are unsupported for a print request
406+ * in the context of a particular DocFlavor.
407+ * This method is useful for validating a potential print job and
408+ * identifying the specific attributes which cannot be supported.
409+ * It is important to supply only a supported DocFlavor or an
410+ * IllegalArgumentException will be thrown. If the
411+ * return value from this method is null, all attributes are supported.
412+ * <p>
413+ * <code>DocAttribute</code>s which are to be specified on the
414+ * <code>Doc</code> must be included in this set to accurately
415+ * represent the context.
416+ * <p>
417+ * If the return value is non-null, all attributes in the returned
418+ * set are unsupported with this DocFlavor. The returned set does not
419+ * distinguish attribute categories that are unsupported from
420+ * unsupported attribute values.
421+ * <p>
422+ * A supported print request can then be created by removing
423+ * all unsupported attributes from the original attribute set,
424+ * except in the case that the DocFlavor is unsupported.
425+ * <p>
426+ * If any attributes are unsupported only because they are in conflict
427+ * with other attributes then it is at the discretion of the service
428+ * to select the attribute(s) to be identified as the cause of the
429+ * conflict.
430+ * <p>
431+ * Use <code>isDocFlavorSupported()</code> to verify that a DocFlavor
432+ * is supported before calling this method.
433+ *
434+ * @param flavor Doc flavor to test, or null
435+ * @param attributes Set of printing attributes for a supposed job
436+ * (both job-level attributes and document-level
437+ * attributes), or null.
438+ *
439+ * @return null if this Print Service supports the print request
440+ * specification, else the unsupported attributes.
441+ *
442+ * @exception IllegalArgumentException if<CODE>flavor</CODE> is
443+ * not supported by this PrintService.
444+ */
445+ public AttributeSet getUnsupportedAttributes(DocFlavor flavor,
446+ AttributeSet attributes);
447+
448+ /**
449+ * Returns a factory for UI components which allow users to interact
450+ * with the service in various roles.
451+ * Services which do not provide any UI should return null.
452+ * Print Services which do provide UI but want to be supported in
453+ * an environment with no UI support should ensure that the factory
454+ * is not initialised unless the application calls this method to
455+ * obtain the factory.
456+ * See <code>ServiceUIFactory</code> for more information.
457+ * @return null or a factory for UI components.
458+ */
459+ public ServiceUIFactory getServiceUIFactory();
460+
461+ /**
462+ * Determines if two services are referring to the same underlying
463+ * service. Objects encapsulating a print service may not exhibit
464+ * equality of reference even though they refer to the same underlying
465+ * service.
466+ * <p>
467+ * Clients should call this method to determine if two services are
468+ * referring to the same underlying service.
469+ * <p>
470+ * Services must implement this method and return true only if the
471+ * service objects being compared may be used interchangeably by the
472+ * client.
473+ * Services are free to return the same object reference to an underlying
474+ * service if that, but clients must not depend on equality of reference.
475+ * @param obj the reference object with which to compare.
476+ * @return true if this service is the same as the obj argument,
477+ * false otherwise.
478+ */
479+ public boolean equals(Object obj);
480+
481+ /**
482+ * This method should be implemented consistently with
483+ * <code>equals(Object)</code>.
484+ * @return hash code of this object.
485+ */
486+ public int hashCode();
487+
488+}

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t