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