| /* | |
| * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved. | |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
| * | |
| * This code is free software; you can redistribute it and/or modify it | |
| * under the terms of the GNU General Public License version 2 only, as | |
| * published by the Free Software Foundation. Oracle designates this | |
| * particular file as subject to the "Classpath" exception as provided | |
| * by Oracle in the LICENSE file that accompanied this code. | |
| * | |
| * This code is distributed in the hope that it will be useful, but WITHOUT | |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| * version 2 for more details (a copy is included in the LICENSE file that | |
| * accompanied this code). | |
| * | |
| * You should have received a copy of the GNU General Public License version | |
| * 2 along with this work; if not, write to the Free Software Foundation, | |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
| * | |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | |
| * or visit www.oracle.com if you need additional information or have any | |
| * questions. | |
| */ | |
| package javax.print; | |
| import javax.print.attribute.Attribute; | |
| import javax.print.attribute.AttributeSet; | |
| import javax.print.attribute.PrintServiceAttribute; | |
| import javax.print.attribute.PrintServiceAttributeSet; | |
| import javax.print.event.PrintServiceAttributeListener; | |
| /** | |
| * Interface {@code PrintService} is the factory for a {@code DocPrintJob}. A | |
| * {@code PrintService} describes the capabilities of a printer and can be | |
| * queried regarding a printer's supported attributes. | |
| * <p> | |
| * Example: | |
| * <pre>{@code | |
| * DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT; | |
| * PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet(); | |
| * aset.add(MediaSizeName.ISO_A4); | |
| * PrintService[] pservices = | |
| * PrintServiceLookup.lookupPrintServices(flavor, aset); | |
| * if (pservices.length > 0) { | |
| * DocPrintJob pj = pservices[0].createPrintJob(); | |
| * try { | |
| * FileInputStream fis = new FileInputStream("test.ps"); | |
| * Doc doc = new SimpleDoc(fis, flavor, null); | |
| * pj.print(doc, aset); | |
| * } catch (FileNotFoundException fe) { | |
| * } catch (PrintException e) { | |
| * } | |
| * } | |
| * }</pre> | |
| */ | |
| public interface PrintService { | |
| /** | |
| * Returns a string name for this print service which may be used by | |
| * applications to request a particular print service. In a suitable | |
| * context, such as a name service, this name must be unique. In some | |
| * environments this unique name may be the same as the user friendly | |
| * printer name defined as the | |
| * {@link javax.print.attribute.standard.PrinterName PrinterName} attribute. | |
| * | |
| * @return name of the service | |
| */ | |
| public String getName(); | |
| /** | |
| * Creates and returns a {@code PrintJob} capable of handling data from any | |
| * of the supported document flavors. | |
| * | |
| * @return a {@code DocPrintJob} object | |
| */ | |
| public DocPrintJob createPrintJob(); | |
| /** | |
| * Registers a listener for events on this {@code PrintService}. | |
| * | |
| * @param listener a PrintServiceAttributeListener, which monitors the | |
| * status of a print service | |
| * @see #removePrintServiceAttributeListener | |
| */ | |
| public void addPrintServiceAttributeListener( | |
| PrintServiceAttributeListener listener); | |
| /** | |
| * Removes the print-service listener from this print service. This means | |
| * the listener is no longer interested in {@code PrintService} events. | |
| * | |
| * @param listener a {@code PrintServiceAttributeListener} object | |
| * @see #addPrintServiceAttributeListener | |
| */ | |
| public void removePrintServiceAttributeListener( | |
| PrintServiceAttributeListener listener); | |
| /** | |
| * Obtains this print service's set of printer description attributes giving | |
| * this Print Service's status. The returned attribute set object is | |
| * unmodifiable. The returned attribute set object is a "snapshot" of this | |
| * Print Service's attribute set at the time of the {@code getAttributes()} | |
| * method call: that is, the returned attribute set's contents will | |
| * <i>not</i> be updated if this print service's attribute set's contents | |
| * change in the future. To detect changes in attribute values, call | |
| * {@code getAttributes()} again and compare the new attribute set to the | |
| * previous attribute set; alternatively, register a listener for print | |
| * service events. | |
| * | |
| * @return unmodifiable snapshot of this Print Service's attribute set. May | |
| * be empty, but not {@code null}. | |
| */ | |
| public PrintServiceAttributeSet getAttributes(); | |
| /** | |
| * Gets the value of the single specified service attribute. This may be | |
| * useful to clients which only need the value of one attribute and want to | |
| * minimize overhead. | |
| * | |
| * @param <T> the type of the specified service attribute | |
| * @param category the category of a {@code PrintServiceAttribute} | |
| * supported by this service - may not be {@code null} | |
| * @return the value of the supported attribute or {@code null} if the | |
| * attribute is not supported by this service | |
| * @throws NullPointerException if the category is {@code null} | |
| * @throws IllegalArgumentException if {@code category} is not a | |
| * {@code Class} that implements interface | |
| * {@link PrintServiceAttribute PrintServiceAttribute} | |
| */ | |
| public <T extends PrintServiceAttribute> | |
| T getAttribute(Class<T> category); | |
| /** | |
| * Determines the print data formats a client can specify when setting up a | |
| * job for this {@code PrintService}. A print data format is designated by a | |
| * "doc flavor" (class {@link DocFlavor DocFlavor}) consisting of a MIME | |
| * type plus a print data representation class. | |
| * <p> | |
| * Note that some doc flavors may not be supported in combination with all | |
| * attributes. Use {@code getUnsupportedAttributes(..)} to validate specific | |
| * combinations. | |
| * | |
| * @return array of supported doc flavors, should have at least one element | |
| */ | |
| public DocFlavor[] getSupportedDocFlavors(); | |
| /** | |
| * Determines if this print service supports a specific {@code DocFlavor}. | |
| * This is a convenience method to determine if the {@code DocFlavor} would | |
| * be a member of the result of {@code getSupportedDocFlavors()}. | |
| * <p> | |
| * Note that some doc flavors may not be supported in combination with all | |
| * attributes. Use {@code getUnsupportedAttributes(..)} to validate specific | |
| * combinations. | |
| * | |
| * @param flavor the {@code DocFlavor} to query for support | |
| * @return {@code true} if this print service supports the specified | |
| * {@code DocFlavor}; {@code false} otherwise | |
| * @throws NullPointerException if {@code flavor} is {@code null} | |
| */ | |
| public boolean isDocFlavorSupported(DocFlavor flavor); | |
| /** | |
| * Determines the printing attribute categories a client can specify when | |
| * setting up a job for this print service. A printing attribute category is | |
| * designated by a {@code Class} that implements interface | |
| * {@link Attribute Attribute}. This method returns just the attribute | |
| * <i>categories</i> that are supported; it does not return the particular | |
| * attribute <i>values</i> that are supported. | |
| * <p> | |
| * This method returns all the printing attribute categories this print | |
| * service supports for any possible job. Some categories may not be | |
| * supported in a particular context (ie for a particular | |
| * {@code DocFlavor}). Use one of the methods that include a | |
| * {@code DocFlavor} to validate the request before submitting it, such as | |
| * {@code getSupportedAttributeValues(..)}. | |
| * | |
| * @return array of printing attribute categories that the client can | |
| * specify as a doc-level or job-level attribute in a Print Request. | |
| * Each element in the array is a {@link Class Class} that | |
| * implements interface {@link Attribute Attribute}. The array is | |
| * empty if no categories are supported. | |
| */ | |
| public Class<?>[] getSupportedAttributeCategories(); | |
| /** | |
| * Determines whether a client can specify the given printing attribute | |
| * category when setting up a job for this print service. A printing | |
| * attribute category is designated by a {@code Class} that implements | |
| * interface {@link Attribute Attribute}. This method | |
| * tells whether the attribute <i>category</i> is supported; it does not | |
| * tell whether a particular attribute <i>value</i> is supported. | |
| * <p> | |
| * Some categories may not be supported in a particular context (ie for a | |
| * particular {@code DocFlavor}). Use one of the methods which include a | |
| * {@code DocFlavor} to validate the request before submitting it, such as | |
| * {@code getSupportedAttributeValues(..)}. | |
| * <p> | |
| * This is a convenience method to determine if the category would be a | |
| * member of the result of {@code getSupportedAttributeCategories()}. | |
| * | |
| * @param category printing attribute category to test. It must be a | |
| * {@code Class} that implements interface | |
| * {@link Attribute Attribute}. | |
| * @return {@code true} if this print service supports specifying a | |
| * doc-level or job-level attribute in {@code category} in a Print | |
| * Request; {@code false} if it doesn't | |
| * @throws NullPointerException if {@code category} is {@code null} | |
| * @throws IllegalArgumentException if {@code category} is not a | |
| * {@code Class} that implements interface | |
| * {@link Attribute Attribute} | |
| */ | |
| public boolean | |
| isAttributeCategorySupported(Class<? extends Attribute> category); | |
| /** | |
| * Determines this print service's default printing attribute value in the | |
| * given category. A printing attribute value is an instance of a class that | |
| * implements interface {@link Attribute Attribute}. If a client sets up a | |
| * print job and does not specify any attribute value in the given category, | |
| * this Print Service will use the default attribute value instead. | |
| * <p> | |
| * Some attributes may not be supported in a particular context (ie for a | |
| * particular {@code DocFlavor}). Use one of the methods that include a | |
| * {@code DocFlavor} to validate the request before submitting it, such as | |
| * {@code getSupportedAttributeValues(..)}. | |
| * <p> | |
| * Not all attributes have a default value. For example the service will not | |
| * have a default value for {@code RequestingUser} i.e. a {@code null} | |
| * return for a supported category means there is no service default value | |
| * for that category. Use the {@code isAttributeCategorySupported(Class)} | |
| * method to distinguish these cases. | |
| * | |
| * @param category printing attribute category for which the default | |
| * attribute value is requested. It must be a {@link Class Class} | |
| * that implements interface {@link Attribute Attribute}. | |
| * @return default attribute value for {@code category}, or {@code null} if | |
| * this Print Service does not support specifying a doc-level or | |
| * job-level attribute in {@code category} in a Print Request, or | |
| * the service does not have a default value for this attribute | |
| * @throws NullPointerException if {@code category} is {@code null} | |
| * @throws IllegalArgumentException if {@code category} is not a | |
| * {@link Class Class} that implements interface | |
| * {@link Attribute Attribute} | |
| */ | |
| public Object | |
| getDefaultAttributeValue(Class<? extends Attribute> category); | |
| /** | |
| * Determines the printing attribute values a client can specify in the | |
| * given category when setting up a job for this print service. A printing | |
| * attribute value is an instance of a class that implements interface | |
| * {@link Attribute Attribute}. | |
| * <p> | |
| * If {@code flavor} is {@code null} and {@code attributes} is {@code null} | |
| * or is an empty set, this method returns all the printing attribute values | |
| * this Print Service supports for any possible job. If {@code flavor} is not | |
| * {@code null} or {@code attributes} is not an empty set, this method | |
| * returns just the printing attribute values that are compatible with the | |
| * given doc flavor and/or set of attributes. That is, a {@code null} return | |
| * value may indicate that specifying this attribute is incompatible with | |
| * the specified DocFlavor. Also if {@code DocFlavor} is not {@code null} it | |
| * must be a flavor supported by this {@code PrintService}, else | |
| * {@code IllegalArgumentException} will be thrown. | |
| * <p> | |
| * If the {@code attributes} parameter contains an {@code Attribute} whose | |
| * category is the same as the {@code category} parameter, the service must | |
| * ignore this attribute in the {@code AttributeSet}. | |
| * <p> | |
| * {@code DocAttribute}s which are to be specified on the {@code Doc} must | |
| * be included in this set to accurately represent the context. | |
| * <p> | |
| * This method returns an {@code Object} because different printing | |
| * attribute categories indicate the supported attribute values in different | |
| * ways. The documentation for each printing attribute in package | |
| * {@link javax.print.attribute.standard javax.print.attribute.standard} | |
| * describes how each attribute indicates its supported values. Possible | |
| * ways of indicating support include: | |
| * <ul> | |
| * <li>Return a single instance of the attribute category to indicate that | |
| * any value is legal -- used, for example, by an attribute whose value is | |
| * an arbitrary text string. (The value of the returned attribute object | |
| * is irrelevant.) | |
| * <li>Return an array of one or more instances of the attribute category, | |
| * containing the legal values -- used, for example, by an attribute with | |
| * a list of enumerated values. The type of the array is an array of the | |
| * specified attribute category type as returned by its | |
| * {@code getCategory(Class)}. | |
| * <li>Return a single object (of some class other than the attribute | |
| * category) that indicates bounds on the legal values -- used, for | |
| * example, by an integer-valued attribute that must lie within a certain | |
| * range. | |
| * </ul> | |
| * | |
| * @param category printing attribute category to test. It must be a | |
| * {@link Class Class} that implements interface | |
| * {@link Attribute Attribute}. | |
| * @param flavor doc flavor for a supposed job, or {@code null} | |
| * @param attributes set of printing attributes for a supposed job (both | |
| * job-level attributes and document-level attributes), or | |
| * {@code null} | |
| * @return object indicating supported values for {@code category}, or | |
| * {@code null} if this Print Service does not support specifying a | |
| * doc-level or job-level attribute in {@code category} in a Print | |
| * Request | |
| * @throws NullPointerException if {@code category} is {@code null} | |
| * @throws IllegalArgumentException if {@code category} is not a | |
| * {@link Class Class} that implements interface | |
| * {@link Attribute Attribute}, or {@code DocFlavor} is not | |
| * supported by this service | |
| */ | |
| public Object | |
| getSupportedAttributeValues(Class<? extends Attribute> category, | |
| DocFlavor flavor, | |
| AttributeSet attributes); | |
| /** | |
| * Determines whether a client can specify the given printing attribute | |
| * value when setting up a job for this Print Service. A printing attribute | |
| * value is an instance of a class that implements interface | |
| * {@link Attribute Attribute}. | |
| * <p> | |
| * If {@code flavor} is {@code null} and {@code attributes} is {@code null} | |
| * or is an empty set, this method tells whether this Print Service supports | |
| * the given printing attribute value for some possible combination of doc | |
| * flavor and set of attributes. If {@code flavor} is not {@code null} or | |
| * {@code attributes} is not an empty set, this method tells whether this | |
| * Print Service supports the given printing attribute value in combination | |
| * with the given doc flavor and/or set of attributes. | |
| * <p> | |
| * Also if {@code DocFlavor} is not {@code null} it must be a flavor | |
| * supported by this {@code PrintService}, else | |
| * {@code IllegalArgumentException} will be thrown. | |
| * <p> | |
| * {@code DocAttribute}s which are to be specified on the {@code Doc} must | |
| * be included in this set to accurately represent the context. | |
| * <p> | |
| * This is a convenience method to determine if the value would be a member | |
| * of the result of {@code getSupportedAttributeValues(...)}. | |
| * | |
| * @param attrval printing attribute value to test | |
| * @param flavor doc flavor for a supposed job, or {@code null} | |
| * @param attributes set of printing attributes for a supposed job (both | |
| * job-level attributes and document-level attributes), or | |
| * {@code null} | |
| * @return {@code true} if this Print Service supports specifying | |
| * {@code attrval} as a doc-level or job-level attribute in a Print | |
| * Request, {@code false} if it doesn't | |
| * @throws NullPointerException if {@code attrval} is {@code null} | |
| * @throws IllegalArgumentException if flavor is not supported by this | |
| * {@code PrintService} | |
| */ | |
| public boolean isAttributeValueSupported(Attribute attrval, | |
| DocFlavor flavor, | |
| AttributeSet attributes); | |
| /** | |
| * Identifies the attributes that are unsupported for a print request in the | |
| * context of a particular {@code DocFlavor}. This method is useful for | |
| * validating a potential print job and identifying the specific attributes | |
| * which cannot be supported. It is important to supply only a supported | |
| * {@code DocFlavor} or an {@code IllegalArgumentException} will be thrown. | |
| * If the return value from this method is {@code null}, all attributes are | |
| * supported. | |
| * <p> | |
| * {@code DocAttribute}s which are to be specified on the {@code Doc} must | |
| * be included in this set to accurately represent the context. | |
| * <p> | |
| * If the return value is {@code non-null}, all attributes in the returned | |
| * set are unsupported with this {@code DocFlavor}. The returned set does | |
| * not distinguish attribute categories that are unsupported from | |
| * unsupported attribute values. | |
| * <p> | |
| * A supported print request can then be created by removing all unsupported | |
| * attributes from the original attribute set, except in the case that the | |
| * {@code DocFlavor} is unsupported. | |
| * <p> | |
| * If any attributes are unsupported only because they are in conflict with | |
| * other attributes then it is at the discretion of the service to select | |
| * the attribute(s) to be identified as the cause of the conflict. | |
| * <p> | |
| * Use {@code isDocFlavorSupported()} to verify that a {@code DocFlavor} is | |
| * supported before calling this method. | |
| * | |
| * @param flavor doc flavor to test, or {@code null} | |
| * @param attributes set of printing attributes for a supposed job (both | |
| * job-level attributes and document-level attributes), or | |
| * {@code null} | |
| * @return {@code null} if this Print Service supports the print request | |
| * specification, else the unsupported attributes | |
| * @throws IllegalArgumentException if {@code flavor} is not supported by | |
| * this {@code PrintService} | |
| */ | |
| public AttributeSet getUnsupportedAttributes(DocFlavor flavor, | |
| AttributeSet attributes); | |
| /** | |
| * Returns a factory for UI components which allow users to interact with | |
| * the service in various roles. Services which do not provide any UI should | |
| * return {@code null}. Print Services which do provide UI but want to be | |
| * supported in an environment with no UI support should ensure that the | |
| * factory is not initialised unless the application calls this method to | |
| * obtain the factory. See {@code ServiceUIFactory} for more information. | |
| * | |
| * @return {@code null} or a factory for UI components | |
| */ | |
| public ServiceUIFactory getServiceUIFactory(); | |
| /** | |
| * Determines if two services are referring to the same underlying service. | |
| * Objects encapsulating a print service may not exhibit equality of | |
| * reference even though they refer to the same underlying service. | |
| * <p> | |
| * Clients should call this method to determine if two services are | |
| * referring to the same underlying service. | |
| * <p> | |
| * Services must implement this method and return {@code true} only if the | |
| * service objects being compared may be used interchangeably by the client. | |
| * Services are free to return the same object reference to an underlying | |
| * service if that, but clients must not depend on equality of reference. | |
| * | |
| * @param obj the reference object with which to compare | |
| * @return {@code true} if this service is the same as the obj argument, | |
| * {@code false} otherwise | |
| */ | |
| public boolean equals(Object obj); | |
| /** | |
| * This method should be implemented consistently with | |
| * {@code equals(Object)}. | |
| * | |
| * @return hash code of this object | |
| */ | |
| public int hashCode(); | |
| } |