diff options
Diffstat (limited to 'libjava/classpath/javax/print/PrintService.java')
| -rw-r--r-- | libjava/classpath/javax/print/PrintService.java | 168 |
1 files changed, 118 insertions, 50 deletions
diff --git a/libjava/classpath/javax/print/PrintService.java b/libjava/classpath/javax/print/PrintService.java index d34fde843f0..b5fe004a730 100644 --- a/libjava/classpath/javax/print/PrintService.java +++ b/libjava/classpath/javax/print/PrintService.java @@ -1,5 +1,5 @@ /* PrintService.java -- - Copyright (C) 2004 Free Software Foundation, Inc. + Copyright (C) 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -45,14 +45,25 @@ import javax.print.attribute.PrintServiceAttributeSet; import javax.print.event.PrintServiceAttributeListener; /** + * A <code>PrintService</code> represents a printer available for printing. + * <p> + * The print service hereby may be a real physical printer device, a printer + * group with same capabilities or a logical print service (like for example + * a PDF writer). The print service is used to query the capabilities of the + * represented printer instance. If a suitable print service is found it is + * used to create a print job for the actual printing process. + * </p> + * @see javax.print.DocPrintJob + * * @author Michael Koch (konqueror@gmx.de) */ public interface PrintService { /** - * Returns a new print job capable to handle all supported document flavors. + * Creates and returns a new print job which is capable to handle all + * the document flavors supported by this print service. * - * @return the new print job + * @return The created print job object. */ DocPrintJob createPrintJob(); @@ -61,39 +72,54 @@ public interface PrintService * * @param obj the service to check against * - * @return <code>true</code> if both services refer to the sam underlying - * service, <code>false</code> otherwise + * @return <code>true</code> if both services refer to the same underlying + * service, <code>false</code> otherwise. */ boolean equals(Object obj); /** - * Returns the value of a single specified attribute. + * Returns the value of the single specified attribute. * * @param category the category of a <code>PrintServiceAttribute</code> * - * @return the value of the attribute + * @return The value of the attribute, or <code>null</code> if the attribute + * category is not supported by this print service implementation. * - * @throws NullPointerException if category is null + * @throws NullPointerException if category is <code>null</code>. * @throws IllegalArgumentException if category is not a class that - * implements <code>PrintServiceAttribute</code> + * implements <code>PrintServiceAttribute</code>. */ PrintServiceAttribute getAttribute(Class category); /** - * Returns all attributes of this printer service - * - * @return all attributes of this print service + * Returns the attributes describing this print service. The returned + * attributes set is unmodifiable and represents the current state of + * the print service. As some print service attributes may change + * (depends on the print service implementation) a subsequent call to + * this method may return a different set. To monitor changes a + * <code>PrintServiceAttributeListener</code> may be registered. + * + * @return All the description attributes of this print service. + * @see #addPrintServiceAttributeListener(PrintServiceAttributeListener) */ PrintServiceAttributeSet getAttributes(); /** - * Returns the service's default value for a given attribute. + * Determines and returns the default value for a given attribute category + * of this print service. + * <p> + * A return value of <code>null</code> means either that the print service + * does not support the attribute category or there is no default value + * available for this category. To distinguish these two case one can test + * with {@link #isAttributeCategorySupported(Class)} if the category is + * supported. + * </p> * * @param category the category of the attribute * - * @return the default value + * @return The default value, or <code>null</code>. * - * @throws NullPointerException if <code>category</code> is null + * @throws NullPointerException if <code>category</code> is <code>null</code> * @throws IllegalArgumentException if <code>category</code> is a class * not implementing <code>Attribute</code> */ @@ -101,36 +127,50 @@ public interface PrintService /** * Returns the name of this print service. + * This may be the value of the <code>PrinterName</code> attribute. * - * @return the name + * @return The print service name. */ String getName(); /** - * Returns a factory for UI components. + * Returns a factory for UI components if supported by the print service. * - * @return the factory + * @return A factory for UI components or <code>null</code>. */ ServiceUIFactory getServiceUIFactory(); /** * Returns all supported attribute categories. * - * @return an array of all supported attribute categories + * @return The class array of all supported attribute categories. */ Class[] getSupportedAttributeCategories(); /** - * Returns all supported attribute values a client can use when setting up - * a print job with this service. + * Determines and returns all supported attribute values of a given + * attribute category a client can use when setting up a print job + * for this print service. + * <p> + * The returned object may be one of the following types: + * <ul> + * <li>A single instance of the attribute category to indicate that any + * value will be supported.</li> + * <li>An array of the same type as the attribute category to test, + * containing all the supported values for this category.</li> + * <li>A single object (of any other type than the attribute category) + * which indicates bounds on the supported values.</li> + * </ul> + * </p> * * @param category the attribute category to test - * @param flavor the document flavor to use, or null - * @param attributes set of printing attributes for a supposed job, or null + * @param flavor the document flavor to use, or <code>null</code> + * @param attributes set of attributes for a supposed job, + * or <code>null</code> * - * @return object indicating supported values for <code>category</code>, - * or null if this print service doesnt support specifying doc-level or - * job-level attribute in a print request. + * @return A object (as defined above) indicating the supported values + * for the given attribute category, or <code>null</code> if this print + * service doesn't support the given attribute category at all. * * @throws NullPointerException if <code>category</code> is null * @throws IllegalArgumentException if <code>category</code> is a class not @@ -140,73 +180,101 @@ public interface PrintService Object getSupportedAttributeValues(Class category, DocFlavor flavor, AttributeSet attributes); /** - * Returns an array of all supproted document flavors. - * - * @return the supported document flavors + * Determines and returns an array of all supported document flavors which + * can be used to supply print data to this print service. + * <p> + * The supported attribute categories may differ between the supported + * document flavors. To test for supported attributes one can use the + * {@link #getUnsupportedAttributes(DocFlavor, AttributeSet)} method with + * the specific doc flavor and attributes set. + * </p> + * + * @return The supported document flavors. */ DocFlavor[] getSupportedDocFlavors(); /** - * Returns all attributes that are unsupported for a print request in the - * context of a particular document flavor. - * - * @param flavor document flavor to test, or null + * Identifies all the unsupported attributes of the given set of attributes + * in the context of the specified document flavor. + * <p> + * The given flavor has to be supported by the print service (use + * {@link #isDocFlavorSupported(DocFlavor)} to verify). The method will + * return <code>null</code> if all given attributes are supported. Otherwise + * a set of unsupported attributes are returned. The attributes in the + * returned set may be completely unsupported or only the specific requested + * value. If flavor is <code>null</code> the default document flavor of the + * print service is used in the identification process. + * </p> + * + * @param flavor document flavor to test, or <code>null</code>. * @param attributes set of printing attributes for a supposed job * - * @return null if this <code>PrintService</code> supports the print request - * specification, else the unsupported attributes + * @return <code>null</code> if this print service supports all the given + * attributes for the specified doc flavor. Otherwise the set of unsupported + * attributes are returned. * * @throws IllegalArgumentException if <code>flavor</code> is unsupported */ AttributeSet getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes); + /** - * Returns a hashcode for this printer service. + * Returns a hashcode for this print service. * - * @return the hashcode + * @return The hashcode. */ int hashCode(); /** - * Determines a given attribute category is supported or not. + * Determines a given attribute category is supported by this + * print service implementation. This only tests for the category + * not for any specific values of this category nor in the context + * of a specific document flavor. * * @param category the category to check * * @return <code>true</code> if <code>category</code> is supported, - * <code>false</code> otherwise + * <code>false</code> otherwise. * - * @throws NullPointerException if <code>category</code> is null + * @throws NullPointerException if <code>category</code> is <code>null</code> * @throws IllegalArgumentException if <code>category</code> is a class not * implementing <code>Attribute</code>. */ boolean isAttributeCategorySupported(Class category); /** - * Determines a given attribute value is supported when creating a print job - * for this print service. + * Determines if a given attribute value is supported when creating a print + * job for this print service. + * <p> + * If either the document flavor or the provided attributes are + * <code>null</code> it is determined if the given attribute value is + * supported in some combination of the available document flavors and + * attributes of the print service. Otherwise it is checked for the + * specific context of the given document flavor/attributes set. + * </p> * * @param attrval the attribute value to check - * @param flavor the document flavor to use, or null - * @param attributes set of printing attributes to use, or null + * @param flavor the document flavor to use, or <code>null</code>. + * @param attributes set of attributes to use, or <code>null</code>. * - * @return <code>true</code> if the attribute value is supported, - * <code>false</code> otherwise + * @return <code>true</code> if the attribute value is supported in the + * requested context, <code>false</code> otherwise. * - * @throws NullPointerException if <code>attrval</code> is null + * @throws NullPointerException if <code>attrval</code> is <code>null</code>. * @throws IllegalArgumentException if <code>flavor</code> is not supported * by this print service */ boolean isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes); /** - * Determines a given document flavor is supported or not. + * Determines if a given document flavor is supported or not. * * @param flavor the document flavor to check * * @return <code>true</code> if <code>flavor</code> is supported, - * <code>false</code> otherwise + * <code>false</code> otherwise. * - * @throws NullPointerException if <code>flavor</code> is null + * @throws NullPointerException if <code>flavor</code> is null. */ boolean isDocFlavorSupported(DocFlavor flavor); |