< 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 >