< prev index next >

src/java.desktop/share/classes/javax/print/PrintService.java

Print this page

        

*** 1,7 **** /* ! * Copyright (c) 2000, 2014, 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 --- 1,7 ---- /* ! * 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
*** 23,48 **** * questions. */ package javax.print; - import java.util.Locale; - 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 PrintService is the factory for a DocPrintJob. A 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); --- 23,45 ---- * 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 {@code 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);
*** 54,488 **** * 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 PrintJob capable of handling data from ! * any of the supported document flavors. ! * @return a DocPrintJob object */ public DocPrintJob createPrintJob(); /** ! * Registers a listener for events on this 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 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 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 PrintServiceAttribute supported ! * by this service - may not be null. ! * @return the value of the supported attribute or null if the ! * attribute is not supported by this service. ! * @exception NullPointerException if the category is null. ! * @exception IllegalArgumentException ! * (unchecked exception) if {@code category} is not a * {@code Class} that implements interface ! *{@link javax.print.attribute.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 javax.print.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. ! * @exception NullPointerException ! * (unchecked exception) Thrown if {@code flavor} is 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 javax.print.attribute.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 java.lang.Class ! * Class} that implements interface {@link ! * javax.print.attribute.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 javax.print.attribute.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 javax.print.attribute.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. ! * ! * @exception NullPointerException ! * (unchecked exception) Thrown if {@code category} is null. ! * @exception IllegalArgumentException ! * (unchecked exception) Thrown if {@code category} is not a * {@code Class} that implements interface ! * {@link javax.print.attribute.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 javax.print.attribute.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 defaultvalue for {@code RequestingUser} ! * i.e. a 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 ! * java.lang.Class Class} that implements interface ! * {@link javax.print.attribute.Attribute ! * Attribute}. ! * ! * @return Default attribute value for {@code category}, or 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. ! * ! * @exception NullPointerException ! * (unchecked exception) Thrown if {@code category} is null. ! * @exception IllegalArgumentException ! * (unchecked exception) Thrown if {@code category} is not a ! * {@link java.lang.Class Class} that implements interface {@link ! * javax.print.attribute.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 javax.print.attribute.Attribute Attribute}. ! * <P> ! * If {@code flavor} is null and {@code attributes} is 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 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 null return value may indicate that specifying this attribute ! * is incompatible with the specified DocFlavor. ! * Also if DocFlavor is not null it must be a flavor supported by this ! * PrintService, else IllegalArgumentException will be thrown. ! * <P> ! * If the {@code attributes} parameter contains an Attribute whose ! * category is the same as the {@code category} parameter, the service ! * must ignore this attribute in the 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 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 java.lang.Class Class} that implements ! * interface {@link ! * javax.print.attribute.Attribute Attribute}. ! * @param flavor Doc flavor for a supposed job, or null. ! * @param attributes Set of printing attributes for a supposed job ! * (both job-level attributes and document-level ! * attributes), or null. ! * ! * @return Object indicating supported values for {@code category}, ! * or null if this Print Service does not support specifying a ! * doc-level or job-level attribute in {@code category} in ! * a Print Request. ! * ! * @exception NullPointerException ! * (unchecked exception) Thrown if {@code category} is null. ! * @exception IllegalArgumentException ! * (unchecked exception) Thrown if {@code category} is not a ! * {@link java.lang.Class Class} that implements interface {@link ! * javax.print.attribute.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 javax.print.attribute.Attribute Attribute}. ! * <P> ! * If {@code flavor} is null and {@code attributes} is 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 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 DocFlavor is not null it must be a flavor supported by this ! * PrintService, else 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 null. ! * @param attributes Set of printing attributes for a supposed job ! * (both job-level attributes and document-level ! * attributes), or null. ! * ! * @return True if this Print Service supports specifying ! * {@code attrval} as a doc-level or job-level attribute in a ! * Print Request, false if it doesn't. ! * ! * @exception NullPointerException ! * (unchecked exception) if {@code attrval} is null. ! * @exception IllegalArgumentException if flavor is not supported by ! * this 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 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 DocFlavor or an ! * IllegalArgumentException will be thrown. If the ! * return value from this method is 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 non-null, all attributes in the returned ! * set are unsupported with this 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 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 DocFlavor ! * is supported before calling this method. ! * ! * @param flavor Doc flavor to test, or null ! * @param attributes Set of printing attributes for a supposed job ! * (both job-level attributes and document-level ! * attributes), or null. ! * ! * @return null if this Print Service supports the print request ! * specification, else the unsupported attributes. ! * ! * @exception IllegalArgumentException if {@code flavor} is ! * not supported by this 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 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 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 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 true if this service is the same as the obj argument, ! * 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(); - } --- 51,437 ---- * 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(); }
< prev index next >