https://openjdk.java.net/ 
/*
 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.print;

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


Example:
  

  DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
  PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
  aset.add(MediaSizeName.ISO_A4);
  PrintService[] pservices =
                PrintServiceLookup.lookupPrintServices(flavor, aset);
  if (pservices.length > 0) {
      DocPrintJob pj = pservices[0].createPrintJob();
      try {
          FileInputStream fis = new FileInputStream("test.ps");
          Doc doc = new SimpleDoc(fis, flavor, null);
          pj.print(doc, aset);
       } catch (FileNotFoundException fe) {
       } catch (PrintException e) {
       }
  }
  


/**
 * 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);
 *   if (pservices.length > 0) {
 *       DocPrintJob pj = pservices[0].createPrintJob();
 *       try {
 *           FileInputStream fis = new FileInputStream("test.ps");
 *           Doc doc = new SimpleDoc(fis, flavor, null);
 *           pj.print(doc, aset);
 *        } catch (FileNotFoundException fe) {
 *        } catch (PrintException e) {
 *        }
 *   }
 *   }</PRE>
 */
public interface PrintService {

    
Returns a String name for this print service which may be used by applications to request a particular print service. In a suitable context, such as a name service, this name must be unique. In some environments this unique name may be the same as the user friendly printer name defined as the PrinterName attribute. 
Returns: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.

Returns:a DocPrintJob object
/**
     * 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.

Params:
  • listener –  a PrintServiceAttributeListener, which
       monitors the status of a print service
See Also:
/**
     * 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
PrintService events.

Params:
  • listener –  a PrintServiceAttributeListener object
See Also:
/**
     * Removes the print-service listener from this print service.
     * This means the listener is no longer interested in
     * <code>PrintService</code> 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
getAttributes() method call: that is, the returned
attribute set's contents will not be updated if this print
service's attribute set's contents change in the future. To detect
changes in attribute values, call getAttributes() again
and compare the new attribute set to the previous attribute set;
alternatively, register a listener for print service events.

Returns: Unmodifiable snapshot of this Print Service's attribute set.
         May be empty, but not null.
/**
     * 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()</CODE> 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()</CODE> 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.

Params:
  • category – the category of a PrintServiceAttribute supported
by this service - may not be null.
Throws:
Returns:the value of the supported attribute or null if the
attribute is not supported by this service.
/**
     * 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 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</CODE> is not a
     *     <code>Class</code> 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 PrintService. A print data format is designated by a "doc flavor" (class DocFlavor) consisting of a MIME type plus a print data representation class. 

Note that some doc flavors may not be supported in combination
with all attributes. Use getUnsupportedAttributes(..)
to validate specific combinations.

Returns: 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</code>. 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(..)</code>
     * 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
DocFlavor.  This is a convenience method to determine
if the DocFlavor would be a member of the result of
getSupportedDocFlavors().


Note that some doc flavors may not be supported in combination
with all attributes. Use getUnsupportedAttributes(..)
to validate specific combinations.

Params:
  • flavor – the DocFlavorto query for support.
Throws:
Returns: true if this print service supports the
specified DocFlavor; false otherwise.
/**
     * Determines if this print service supports a specific
     * <code>DocFlavor</code>.  This is a convenience method to determine
     * if the <code>DocFlavor</code> would be a member of the result of
     * <code>getSupportedDocFlavors()</code>.
     * <p>
     * Note that some doc flavors may not be supported in combination
     * with all attributes. Use <code>getUnsupportedAttributes(..)</code>
     * to validate specific combinations.
     *
     * @param flavor the <code>DocFlavor</code>to query for support.
     * @return  <code>true</code> if this print service supports the
     * specified <code>DocFlavor</code>; <code>false</code> otherwise.
     * @exception  NullPointerException
     *     (unchecked exception) Thrown if <CODE>flavor</CODE> 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 Class that implements interface Attribute. This method returns just the attribute categories that are supported; it does not
return the particular attribute values that are supported.


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 DocFlavor).
Use one of the methods that include a DocFlavor to
validate the request before submitting it, such as
getSupportedAttributeValues(..).

Returns: 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 
         Class that implements interface Attribute. The array is empty if no categories are supported.
/**
     * 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</code> 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</code>).
     * Use one of the methods that include a <code>DocFlavor</code> to
     * validate the request before submitting it, such as
     * <code>getSupportedAttributeValues(..)</code>.
     *
     * @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 Class that implements interface 
Attribute. This method tells whether the attribute category is
supported; it does not tell whether a particular attribute value
is supported.


Some categories may not be supported in a particular context (ie
for a particular DocFlavor).
Use one of the methods which include a DocFlavor to
validate the request before submitting it, such as
getSupportedAttributeValues(..).


This is a convenience method to determine if the category
would be a member of the result of
getSupportedAttributeCategories().

Params:
  • category –    Printing attribute category to test. It must be a
                       Class that implements interface Attribute.
Throws:
Returns: true if this print service supports
         specifying a doc-level or
         job-level attribute in category in a Print
         Request; false if it doesn't.
/**
     * 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</code>
     * 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</code>).
     * Use one of the methods which include a <code>DocFlavor</code> to
     * validate the request before submitting it, such as
     * <code>getSupportedAttributeValues(..)</code>.
     * <P>
     * This is a convenience method to determine if the category
     * would be a member of the result of
     * <code>getSupportedAttributeCategories()</code>.
     *
     * @param  category    Printing attribute category to test. It must be a
     *                        <code>Class</code> that implements
     *                        interface
     *                {@link javax.print.attribute.Attribute Attribute}.
     *
     * @return  <code>true</code> if this print service supports
     *          specifying a doc-level or
     *          job-level attribute in <CODE>category</CODE> in a Print
     *          Request; <code>false</code> if it doesn't.
     *
     * @exception  NullPointerException
     *     (unchecked exception) Thrown if <CODE>category</CODE> is null.
     * @exception  IllegalArgumentException
     *     (unchecked exception) Thrown if <CODE>category</CODE> is not a
     *     <code>Class</code> 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 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. 

Some attributes may not be supported in a particular context (ie
for a particular DocFlavor).
Use one of the methods that include a DocFlavor to
validate the request before submitting it, such as
getSupportedAttributeValues(..).


Not all attributes have a default value. For example the
service will not have a defaultvalue for RequestingUser
i.e. a null return for a supported category means there is no
service default value for that category. Use the
isAttributeCategorySupported(Class) method to
distinguish these cases.

Params:
  • category –  Printing attribute category for which the default attribute value is requested. It must be a Class that implements interface 
                       Attribute.
Throws:
Returns: Default attribute value for category, or null
      if this Print Service does not support specifying a doc-level or
         job-level attribute in category in a Print
         Request, or the service does not have a default value
         for this attribute.
/**
     * 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</code>).
     * Use one of the methods that include a <code>DocFlavor</code> to
     * validate the request before submitting it, such as
     * <code>getSupportedAttributeValues(..)</code>.
     * <P>
     * Not all attributes have a default value. For example the
     * service will not have a defaultvalue for <code>RequestingUser</code>
     * i.e. a null return for a supported category means there is no
     * service default value for that category. Use the
     * <code>isAttributeCategorySupported(Class)</code> 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</CODE>, or null
     *       if this Print Service does not support specifying a doc-level or
     *          job-level attribute in <CODE>category</CODE> in a Print
     *          Request, or the service does not have a default value
     *          for this attribute.
     *
     * @exception  NullPointerException
     *     (unchecked exception) Thrown if <CODE>category</CODE> is null.
     * @exception  IllegalArgumentException
     *     (unchecked exception) Thrown if <CODE>category</CODE> 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 Attribute. 

If flavor is null and 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
flavor is not null or 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.


If the attributes parameter contains an Attribute whose
category is the same as the category parameter, the service
must ignore this attribute in the AttributeSet.


DocAttributes which are to be specified on the
Doc must be included in this set to accurately
represent the context.

 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 javax.print.attribute.standard describes how each attribute indicates its supported values. Possible ways of indicating support include: 
    

  • 
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.)

  • 
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
getCategory(Class).

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





Params:
  • category –  Printing attribute category to test. It must be a Class that implements interface Attribute.
  • flavor –      Doc flavor for a supposed job, or null.
  • attributes –  Set of printing attributes for a supposed job
                       (both job-level attributes and document-level
                       attributes), or null.
Throws:
Returns: Object indicating supported values for category,
         or null if this Print Service does not support specifying a
         doc-level or job-level attribute in category in
         a Print Request.
/**
     * 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</CODE> is null and <CODE>attributes</CODE> 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</CODE> is not null or <CODE>attributes</CODE> 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</code> parameter contains an Attribute whose
     * category is the same as the <code>category</code> parameter, the service
     * must ignore this attribute in the AttributeSet.
     * <p>
     * <code>DocAttribute</code>s which are to be specified on the
     * <code>Doc</code> 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)</code>.
     * <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>
     * <P>
     *
     * @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</CODE>,
     *          or null if this Print Service does not support specifying a
     *          doc-level or job-level attribute in <CODE>category</CODE> in
     *          a Print Request.
     *
     * @exception  NullPointerException
     *     (unchecked exception) Thrown if <CODE>category</CODE> is null.
     * @exception  IllegalArgumentException
     *     (unchecked exception) Thrown if <CODE>category</CODE> is not a
     *     {@link java.lang.Class Class} that implements interface {@link
     *     javax.print.attribute.Attribute Attribute}, or
     *     <code>DocFlavor</code> 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 Attribute. 

If flavor is null and 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 flavor is not null or
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.


Also if DocFlavor is not null it must be a flavor supported by this
PrintService, else IllegalArgumentException will be thrown.


DocAttributes which are to be specified on the
Doc must be included in this set to accurately
represent the context.


This is a convenience method to determine if the value
would be a member of the result of
getSupportedAttributeValues(...).

Params:
  • attrval –       Printing attribute value to test.
  • flavor –      Doc flavor for a supposed job, or null.
  • attributes –  Set of printing attributes for a supposed job
                       (both job-level attributes and document-level
                       attributes), or null.
Throws:
Returns: True if this Print Service supports specifying
       attrval as a doc-level or job-level attribute in a
         Print Request, false if it doesn't.
/**
     * 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</CODE> is null and <CODE>attributes</CODE> 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</CODE> is not null or
     * <CODE>attributes</CODE> 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</code>s which are to be specified on the
     * <code>Doc</code> 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(...)</code>.
     *
     * @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</CODE> as a doc-level or job-level attribute in a
     *          Print Request, false if it doesn't.
     *
     * @exception  NullPointerException
     *     (unchecked exception)  if <CODE>attrval</CODE> 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.


DocAttributes which are to be specified on the
Doc must be included in this set to accurately
represent the context.


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.


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.


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.


Use isDocFlavorSupported() to verify that a DocFlavor
is supported before calling this method.

Params:
  • flavor –      Doc flavor to test, or null
  • attributes –  Set of printing attributes for a supposed job
                       (both job-level attributes and document-level
                       attributes), or null.
Throws:
Returns: null if this Print Service supports the print request
specification, else the unsupported 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</code>s which are to be specified on the
     * <code>Doc</code> 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()</code> 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</CODE> 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 ServiceUIFactory for more information.

Returns: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 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</code> 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.


Clients should call this method to determine if two services are
referring to the same underlying service.


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.

Params:
  • obj – the reference object with which to compare.
Returns:true if this service is the same as the obj argument,
false otherwise.
/**
     * 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
equals(Object).

Returns:hash code of this object.
/**
     * This method should be implemented consistently with
     * <code>equals(Object)</code>.
     * @return hash code of this object.
     */
    public int hashCode();

}