2006-01-24 Wolfgang Baer <WBaer@gmx.de>

	* javax/print/PrintService.java,
	* javax/print/DocPrintJob.java,
	* javax/print/CancelablePrintJob.java:
	Added and enhanced api documentation for class and methods.

3 files changed, 196 insertions, 69 deletions

diff --git a/javax/print/CancelablePrintJob.java b/javax/print/CancelablePrintJob.java
index 94e9475e5..39a25440e 100644
--- a/javax/print/CancelablePrintJob.java
+++ b/javax/print/CancelablePrintJob.java
@@ -1,5 +1,5 @@
 /* CancelablePrintJob.java --
-   Copyright (C) 2004 Free Software Foundation, Inc.
+   Copyright (C) 2004, 2006 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,14 +39,29 @@ exception statement from your version. */
 package javax.print;
 
 /**
+ * <code>CancelablePrintJob</code> represents a print job which can be 
+ * canceled.
+ * <p>
+ * It is implemented by <code>DocPrintJob</code>s which support to cancel 
+ * a print job during processing. Clients need to explicitly test if a given 
+ * <code>DocPrintJob</code> object from a print service implementes this 
+ * interface and therefore supports cancelling.
+ * </p><p>
+ * Implementor of java print services should implement this interface if
+ * cancelling is supported by the underlying print system. If implemented the
+ * corresponding print job event 
+ * {@link javax.print.event.PrintJobEvent#JOB_CANCELED} should be delivered to 
+ * registered clients. Implementations have to be thread-safe.
+ * </p>
+ *
  * @author Michael Koch (konqueror@gmx.de)
  */
 public interface CancelablePrintJob extends DocPrintJob
 {
   /**
-   * Cancel print job.
+   * Cancel the print job.
    *
-   * @exception PrintException if an error occured
+   * @exception PrintException if an error during cancellation occurs.
    */
   void cancel() throws PrintException;
 }
diff --git a/javax/print/DocPrintJob.java b/javax/print/DocPrintJob.java
index f7d361594..eec4e2afc 100644
--- a/javax/print/DocPrintJob.java
+++ b/javax/print/DocPrintJob.java
@@ -1,5 +1,5 @@
 /* DocPrintJob.java --
-   Copyright (C) 2004 Free Software Foundation, Inc.
+   Copyright (C) 2004, 2006 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -44,61 +44,105 @@ import javax.print.event.PrintJobAttributeListener;
 import javax.print.event.PrintJobListener;
 
 /**
+ * <code>DocPrintJob</code> represents a print job which supports printing 
+ * of a single document. 
+ * <p>
+ * An instance can be obtained from every <code>PrintService</code> available 
+ * by calling the {@link javax.print.PrintService#createPrintJob()} method. 
+ * A print job is bound to the print service it is created from.
+ * </p>
+ *  
  * @author Michael Koch (konqueror@gmx.de)
  */
 public interface DocPrintJob
 {
   /**
-   * Registers a listener for changes in the specified attributes.
+   * Registers a listener for changes in the specified attribute set
+   * during processing of this print job.
+   * <p>
+   * If the given attribute set is empty no changes will be reported.
+   * If the set is <code>null</code> all attributes are monitored.
+   * </p>
    * 
-   * @param listener the listener to add
-   * @param attributes the attributes to observe
+   * @param listener the listener to register.
+   * @param attributes the attributes to observe.
+   * 
+   * @see #removePrintJobAttributeListener(PrintJobAttributeListener)
    */
   void addPrintJobAttributeListener(PrintJobAttributeListener listener,
 				    PrintJobAttributeSet attributes);
 
   /**
-   * Registers a listener for events occuring during this print job.
+   * Registers a listener for events occuring during processing
+   * of this print job.
+   * 
+   * @param listener the listener to add, if <code>null</code> nothing is done.
    * 
-   * @param listener the listener to add
+   * @see #removePrintJobListener(PrintJobListener)
    */
   void addPrintJobListener(PrintJobListener listener);
 
   /**
-   * Returns the print job's attributes.
+   * Returns the print job's attributes. 
+   * <p>
+   * The returned set of attributes is a snapshot at the time of calling this 
+   * method and will not be updated if changes to the print job's attributes
+   * happens. To monitor changes register a print job listener.
+   * </p>
    * 
-   * @return the attributes of this print job
+   * @return The attributes of this print job, 
+   * may be empty but never <code>null</code>.
    */
   PrintJobAttributeSet getAttributes();
 
   /**
    * Returns the <code>PrintService</code> object this print job is bound to.
    * 
-   * @return the print service
+   * @return The print service.
    */
   PrintService getPrintService();
 
   /**
    * Prints a document with the specified print job attributes.
    * 
+   * <p>
+   * If the doc flavor provided by the <code>Doc</code> implementation is 
+   * not supported by this print service a <code>PrintException</code> 
+   * implementing the <code>FlavorException</code> interface will be thrown.
+   * </p>
+   * 
    * @param doc the document to print
-   * @param attributes the attributes to use
+   * @param attributes the job attributes to use. If <code>null</code> the 
+   * default attribute values of the print service will be used.
+   * 
+   * @throws PrintException if an error occurs. The thrown exception may 
+   * implement refining print exception interface to provide more detail of 
+   * the error.
    * 
-   * @throws PrintException if an error occurs
+   * @see AttributeException
+   * @see FlavorException
    */
   void print(Doc doc, PrintRequestAttributeSet attributes) throws PrintException;
 
   /**
-   * De-registers an attribute listener.
+   * Removes the given listener from the listeners registered for changes
+   * in their provided attribute set during processing of this print job.
    * 
-   * @param listener the listener to remove
-   */
+   * @param listener the listener to remove, if <code>null</code> or not
+   * registered nothing will be done.
+   * 
+   * @see #addPrintJobAttributeListener(PrintJobAttributeListener, PrintJobAttributeSet)
+   */  
   void removePrintJobAttributeListener(PrintJobAttributeListener listener);
 
   /**
-   * De-registers a print job listener.
+   * Removes the given listener from the listeners registered for events 
+   * occuring during processing of this print job.
+   * 
+   * @param listener the listener to remove, if <code>null</code> or not
+   * registered nothing will be done.
    * 
-   * @param listener the listener to remove
+   * @see #addPrintJobListener(PrintJobListener)
    */
   void removePrintJobListener(PrintJobListener listener);
 }
\ No newline at end of file
diff --git a/javax/print/PrintService.java b/javax/print/PrintService.java
index d34fde843..b5fe004a7 100644
--- a/javax/print/PrintService.java
+++ b/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);