+ * Interface {@code PrintService} is the factory for a {@code DocPrintJob}. A + * {@code PrintService} describes the capabilities of a printer and can be + * queried regarding a printer's supported attributes. + *
* Example: - *
{@code
+ * {@code
* DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
* PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
* aset.add(MediaSizeName.ISO_A4);
@@ -56,299 +53,263 @@
* } catch (PrintException e) {
* }
* }
- * }
+ * }
*/
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 not 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
+ * not 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.
- * @param - * 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. + *
+ * 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()}. - *
- * 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()}. + *
+ * 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 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 {@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 + * 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 + * {@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 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 {@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 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 {@code DocFlavor}). Use one of the methods which include a + * {@code DocFlavor} to validate the request before submitting it, such as * {@code getSupportedAttributeValues(..)}. - *
- * 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}. + *
+ * 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 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. - *
- * 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. + *
+ * 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(..)}. - *
- * 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}. + *
+ * 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 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}. - *
- * 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. - *
- * 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. - *
- * {@code DocAttribute}s which are to be specified on the - * {@code 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 {@link - * javax.print.attribute.standard javax.print.attribute.standard} + * {@link Attribute Attribute}. + *
+ * 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. + *
+ * 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}. + *
+ * {@code DocAttribute}s which are to be specified on the {@code Doc} must + * be included in this set to accurately represent the context. + *
+ * 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: - *
- * 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}. + *
+ * 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. - *
- * Also if DocFlavor is not null it must be a flavor supported by this - * PrintService, else IllegalArgumentException will be thrown. - *
- * {@code DocAttribute}s which are to be specified on the - * {@code 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 - * {@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. + *
+ * Also if {@code DocFlavor} is not {@code null} it must be a flavor + * supported by this {@code PrintService}, else + * {@code IllegalArgumentException} will be thrown. + *
+ * {@code DocAttribute}s which are to be specified on the {@code 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 {@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. - *
- * {@code DocAttribute}s which are to be specified on the - * {@code 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 + * 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. + *
+ * {@code DocAttribute}s which are to be specified on the {@code Doc} must + * be included in this set to accurately represent the context. + *
+ * 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. *
- * 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 {@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. + *
+ * 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 {@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. *
* 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 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(); - }