< prev index next >
src/java.desktop/share/classes/javax/print/PrintService.java
Print this page
@@ -1,7 +1,7 @@
/*
- * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
+ * 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,26 +23,23 @@
* 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>
+ * 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
+ * <pre>{@code
* DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
* PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
* aset.add(MediaSizeName.ISO_A4);
* PrintService[] pservices =
* PrintServiceLookup.lookupPrintServices(flavor, aset);
@@ -54,435 +51,387 @@
* pj.print(doc, aset);
* } catch (FileNotFoundException fe) {
* } catch (PrintException e) {
* }
* }
- * }</PRE>
+ * }</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.
+ /**
+ * 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
+ * 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 PrintService.
- * @param listener a PrintServiceAttributeListener, which
- * monitors the status of a print service
+ * 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 PrintServiceAttributeListener object
+ * 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.
+ * 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.
+ * @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.
+ * 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
+ * @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 javax.print.attribute.PrintServiceAttribute PrintServiceAttribute}.
+ * {@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 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.
+ * 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.
- * @exception NullPointerException
- * (unchecked exception) Thrown if {@code flavor} is null.
+ * 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
+ * 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
+ * {@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 java.lang.Class
- * Class} that implements interface {@link
- * javax.print.attribute.Attribute Attribute}.
- * The array is empty if no categories are supported.
+ * @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 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
+ * 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 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
+ * <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}.
+ * {@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 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
+ * 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 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}.
+ * <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
+ * 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}
+ * {@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,
+ * <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.
+ * <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 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
+ * 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 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.
+ * 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 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
+ * 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 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.
+ * 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 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.
+ * 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.
+ * 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 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 true if this service is the same as the obj argument,
- * false otherwise.
+ *
+ * @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.
+ *
+ * @return hash code of this object
*/
public int hashCode();
-
}
< prev index next >