Merge "Print APIs documentation update"

12 files changed, 80 insertions, 71 deletions

diff --git a/Android.mk b/Android.mk
index 618f40433b18..603f5c3644e1 100644
--- a/Android.mk
+++ b/Android.mk
@@ -160,7 +160,7 @@ LOCAL_SRC_FILES += \
 	core/java/android/print/IPrinterDiscoveryObserver.aidl \
 	core/java/android/print/IPrintAdapter.aidl \
 	core/java/android/print/IPrintClient.aidl \
-	core/java/android/print/IPrintProgressListener.aidl \
+	core/java/android/print/IPrintResultCallback.aidl \
 	core/java/android/print/IPrintManager.aidl \
 	core/java/android/print/IPrintSpoolerService.aidl \
 	core/java/android/print/IPrintSpoolerServiceCallbacks.aidl \
diff --git a/api/current.txt b/api/current.txt
index 4debd4daf64d..a6f2cf5ac95f 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -18404,12 +18404,12 @@ package android.print {
     ctor public PrintAdapter();
     method public abstract android.print.PrintAdapterInfo getInfo();
     method public void onFinish();
-    method public abstract void onPrint(java.util.List<android.print.PageRange>, java.io.FileDescriptor, android.os.CancellationSignal, android.print.PrintAdapter.PrintProgressCallback);
+    method public abstract void onPrint(java.util.List<android.print.PageRange>, java.io.FileDescriptor, android.os.CancellationSignal, android.print.PrintAdapter.PrintResultCallback);
     method public boolean onPrintAttributesChanged(android.print.PrintAttributes);
     method public void onStart();
   }
 
-  public static abstract class PrintAdapter.PrintProgressCallback {
+  public static abstract class PrintAdapter.PrintResultCallback {
     method public void onPrintFailed(java.lang.CharSequence);
     method public void onPrintFinished(java.util.List<android.print.PageRange>);
   }
diff --git a/core/java/android/print/IPrintAdapter.aidl b/core/java/android/print/IPrintAdapter.aidl
index a9b4fb7c3734..f3ff8c4d0ce8 100644
--- a/core/java/android/print/IPrintAdapter.aidl
+++ b/core/java/android/print/IPrintAdapter.aidl
@@ -17,7 +17,7 @@
 package android.print;
 
 import android.os.ParcelFileDescriptor;
-import android.print.IPrintProgressListener;
+import android.print.IPrintResultCallback;
 import android.print.PageRange;
 import android.print.PrintAttributes;
 
@@ -30,6 +30,6 @@ oneway interface IPrintAdapter {
     void start();
     void printAttributesChanged(in PrintAttributes attributes);
     void print(in List<PageRange> pages, in ParcelFileDescriptor fd,
-            IPrintProgressListener progressListener);
+            IPrintResultCallback callback);
     void finish();
 }
diff --git a/core/java/android/print/IPrintProgressListener.aidl b/core/java/android/print/IPrintResultCallback.aidl
index 2c0d607bd8ee..838377ea4a96 100644
--- a/core/java/android/print/IPrintProgressListener.aidl
+++ b/core/java/android/print/IPrintResultCallback.aidl
@@ -26,8 +26,8 @@ import android.print.PrintAdapterInfo;
  *
  * @hide
  */
-oneway interface IPrintProgressListener {
-    void onWriteStarted(in PrintAdapterInfo info, ICancellationSignal cancellationSignal);
-    void onWriteFinished(in List<PageRange> pages);
-    void onWriteFailed(CharSequence error);
+oneway interface IPrintResultCallback {
+    void onPrintStarted(in PrintAdapterInfo info, ICancellationSignal cancellationSignal);
+    void onPrintFinished(in List<PageRange> pages);
+    void onPrintFailed(CharSequence error);
 }
diff --git a/core/java/android/print/PageRange.java b/core/java/android/print/PageRange.java
index 044a71568cfd..60e62296da3c 100644
--- a/core/java/android/print/PageRange.java
+++ b/core/java/android/print/PageRange.java
@@ -21,7 +21,7 @@ import android.os.Parcelable;
 
 /**
  * Represents a range of pages. The start and end page indices of
- * the range are zero based and are inclusive.
+ * the range are zero based and inclusive.
  */
 public final class PageRange implements Parcelable {
 
diff --git a/core/java/android/print/PrintAdapter.java b/core/java/android/print/PrintAdapter.java
index a7f809bd801d..6547c55e1d1a 100644
--- a/core/java/android/print/PrintAdapter.java
+++ b/core/java/android/print/PrintAdapter.java
@@ -16,12 +16,11 @@
 
 package android.print;
 
+import android.os.CancellationSignal;
+
 import java.io.FileDescriptor;
-import java.io.IOException;
 import java.util.List;
 
-import android.os.CancellationSignal;
-
 /**
  * Base class that provides data to be printed.
  *
@@ -33,19 +32,23 @@ import android.os.CancellationSignal;
  * This callback can be used to allocate resources.
  * </li>
  * <li>
- * Next you will get one or more calls to the pair
- *  {@link #onPrintAttributesChanged(PrintAttributes)} and {@link #onPrint(List,
- * FileDescriptor, CancellationSignal, PrintProgressCallback)}. The first callback
- * informs you that the print attributes (page size, density, etc) changed giving
- * you an opportunity to re-layout the content. The second method asks you to write
- * a PDF file with the content for specific pages.
+ * Next you will get one or more calls to {@link #onPrintAttributesChanged(
+ * PrintAttributes) to informs you that the print attributes (page size, density,
+ * etc) changed giving you an opportunity to re-layout the content.
+ * </li>
+ * <li>
+ * After every {@link #onPrintAttributesChanged(PrintAttributes) you will receive
+ * one or more calls to {@link #onPrint(List, FileDescriptor, CancellationSignal,
+ * PrintResultCallback)} asking you to write a PDF file with the content for
+ * specific pages.
  * </li>
  * <li>
  * Finally, you will receive a call on {@link #onFinish()} right after printing.
  * You can use this callback to release resources.
  * </li>
  * <li>
- * You can receive calls to {@link #getInfo()} at any point which should return
+ * You can receive calls to {@link #getInfo()} at any point after a call to
+ * {@link #onPrintAttributesChanged(PrintAttributes)} which should return
  * a {@link PrintAdapterInfo} describing your {@link PrintAdapter}.
  * </li>
  * </ul>
@@ -83,29 +86,28 @@ public abstract class PrintAdapter {
     /**
      * Called when specific pages of the content have to be printed in the from of
      * a PDF file to the given file descriptor. You should <strong>not</strong>
-     * close the file descriptor instead you have to invoke {@link PrintProgressCallback
-     * #onWriteFinished()} or {@link PrintProgressCallback#onPrintFailed(CharSequence)}.
+     * close the file descriptor instead you have to invoke {@link PrintResultCallback
+     * #onPrintFinished()} or {@link PrintResultCallback#onPrintFailed(CharSequence)}.
      * <p>
      * <strong>Note:</strong> If the printed content is large, it is a  good
      * practice to schedule writing it on a dedicated thread and register a
-     * callback in the provided {@link CancellationSignal} upon which to stop
-     * writing data. The cancellation callback will not be made on the main
-     * thread.
+     * callback in the provided {@link CancellationSignal} upon invocation of
+     * which you should stop writing data. The cancellation callback will not
+     * be made on the main thread.
      * </p>
      * <p>
      * <strong>Note:</strong> Invoked on the main thread.
      * </p>
-     * <p>
      *
-     * @param pages The pages whose content to write.
+     * @param pages The pages whose content to print.
      * @param destination The destination file descriptor to which to start writing.
-     * @param cancellationSignal Signal for observing cancel write requests.
+     * @param cancellationSignal Signal for observing cancel print requests.
      * @param progressListener Callback to inform the system with the write progress.
      *
      * @see CancellationSignal
      */
     public abstract void onPrint(List<PageRange> pages, FileDescriptor destination,
-            CancellationSignal cancellationSignal, PrintProgressCallback progressListener);
+            CancellationSignal cancellationSignal, PrintResultCallback progressListener);
 
     /**
      * Called when printing finished. You can use this callback to release
@@ -132,12 +134,12 @@ public abstract class PrintAdapter {
     public abstract PrintAdapterInfo getInfo();
 
     /**
-     * Base class for implementing a listener for the printing progress
+     * Base class for implementing a listener for the print result
      * of a {@link PrintAdapter}.
      */
-    public static abstract class PrintProgressCallback {
+    public static abstract class PrintResultCallback {
 
-        PrintProgressCallback() {
+        PrintResultCallback() {
             /* do nothing - hide constructor */
         }
 
diff --git a/core/java/android/print/PrintFileAdapter.java b/core/java/android/print/PrintFileAdapter.java
index bbfc394a08a0..dab964846552 100644
--- a/core/java/android/print/PrintFileAdapter.java
+++ b/core/java/android/print/PrintFileAdapter.java
@@ -53,9 +53,9 @@ class PrintFileAdapter extends PrintAdapter {
 
     @Override
     public void onPrint(List<PageRange> pages, FileDescriptor destination,
-            CancellationSignal cancellationSignal, PrintProgressCallback progressListener) {
+            CancellationSignal cancellationSignal, PrintResultCallback callback) {
         mWriteFileAsyncTask = new WriteFileAsyncTask(mFile, destination, cancellationSignal,
-                progressListener);
+                callback);
         mWriteFileAsyncTask.executeOnExecutor(AsyncTask.THREAD_POOL_EXECUTOR,
                 (Void[]) null);
         
@@ -73,15 +73,15 @@ class PrintFileAdapter extends PrintAdapter {
 
         private final FileDescriptor mDestination;
 
-        private final PrintProgressCallback mProgressListener;
+        private final PrintResultCallback mResultCallback;
 
         private final CancellationSignal mCancellationSignal;
 
         public WriteFileAsyncTask(File source, FileDescriptor destination,
-                CancellationSignal cancellationSignal, PrintProgressCallback progressListener) {
+                CancellationSignal cancellationSignal, PrintResultCallback callback) {
             mSource = source;
             mDestination = destination;
-            mProgressListener = progressListener;
+            mResultCallback = callback;
             mCancellationSignal = cancellationSignal; 
             mCancellationSignal.setOnCancelListener(new OnCancelListener() {
                 @Override
@@ -113,9 +113,9 @@ class PrintFileAdapter extends PrintAdapter {
                 if (!isCancelled()) {
                     List<PageRange> pages = new ArrayList<PageRange>();
                     pages.add(PageRange.ALL_PAGES);
-                    mProgressListener.onPrintFinished(pages);
+                    mResultCallback.onPrintFinished(pages);
                 } else {
-                    mProgressListener.onPrintFailed("Cancelled");
+                    mResultCallback.onPrintFailed("Cancelled");
                 }
             }
             return null;
diff --git a/core/java/android/print/PrintManager.java b/core/java/android/print/PrintManager.java
index 32a0f5a0a360..be9b59658c7b 100644
--- a/core/java/android/print/PrintManager.java
+++ b/core/java/android/print/PrintManager.java
@@ -26,7 +26,7 @@ import android.os.Looper;
 import android.os.Message;
 import android.os.ParcelFileDescriptor;
 import android.os.RemoteException;
-import android.print.PrintAdapter.PrintProgressCallback;
+import android.print.PrintAdapter.PrintResultCallback;
 import android.util.Log;
 
 import com.android.internal.os.SomeArgs;
@@ -162,6 +162,8 @@ public final class PrintManager {
      * @param pdfFile The PDF file to print.
      * @param attributes The default print job attributes.
      * @return The created print job.
+     *
+     * @see PrintJob
      */
     public PrintJob print(String printJobName, File pdfFile, PrintAttributes attributes) {
         PrintFileAdapter printable = new PrintFileAdapter(pdfFile);
@@ -176,6 +178,8 @@ public final class PrintManager {
      * @param printAdapter The printable adapter to print.
      * @param attributes The default print job attributes.
      * @return The created print job.
+     *
+     * @see PrintJob
      */
     public PrintJob print(String printJobName, PrintAdapter printAdapter,
             PrintAttributes attributes) {
@@ -252,7 +256,7 @@ public final class PrintManager {
 
         @Override
         public void print(List<PageRange> pages, ParcelFileDescriptor fd,
-                IPrintProgressListener progressListener) {
+                IPrintResultCallback callback) {
             synchronized (mLock) {
                 if (isFinishedLocked()) {
                     return;
@@ -261,7 +265,7 @@ public final class PrintManager {
                 args.arg1 = mPrintAdapter;
                 args.arg2 = pages;
                 args.arg3 = fd.getFileDescriptor();
-                args.arg4 = progressListener;
+                args.arg4 = callback;
                 mHandler.obtainMessage(MyHandler.MESSAGE_PRINT, args).sendToTarget();
             }
         }
@@ -318,16 +322,16 @@ public final class PrintManager {
                         @SuppressWarnings("unchecked")
                         List<PageRange> pages = (List<PageRange>) args.arg2;
                         final FileDescriptor fd = (FileDescriptor) args.arg3;
-                        IPrintProgressListener listener = (IPrintProgressListener) args.arg4;
+                        IPrintResultCallback callback = (IPrintResultCallback) args.arg4;
                         args.recycle();
                         try {
                             ICancellationSignal remoteSignal = CancellationSignal.createTransport();
-                            listener.onWriteStarted(adapter.getInfo(), remoteSignal);
+                            callback.onPrintStarted(adapter.getInfo(), remoteSignal);
 
                             CancellationSignal localSignal = CancellationSignal.fromTransport(
                                     remoteSignal);
                             adapter.onPrint(pages, fd, localSignal,
-                                    new PrintProgressListenerWrapper(listener) {
+                                    new PrintResultCallbackWrapper(callback) {
                                         @Override
                                         public void onPrintFinished(List<PageRange> pages) {
                                             IoUtils.closeQuietly(fd);
@@ -363,29 +367,29 @@ public final class PrintManager {
         }
     }
 
-    private static abstract class PrintProgressListenerWrapper extends PrintProgressCallback {
+    private static abstract class PrintResultCallbackWrapper extends PrintResultCallback {
 
-        private final IPrintProgressListener mWrappedListener;
+        private final IPrintResultCallback mWrappedCallback;
 
-        public PrintProgressListenerWrapper(IPrintProgressListener listener) {
-            mWrappedListener = listener;
+        public PrintResultCallbackWrapper(IPrintResultCallback callback) {
+            mWrappedCallback = callback;
         }
 
         @Override
         public void onPrintFinished(List<PageRange> pages) {
             try {
-                mWrappedListener.onWriteFinished(pages);
+                mWrappedCallback.onPrintFinished(pages);
             } catch (RemoteException re) {
-                Log.e(LOG_TAG, "Error calling onWriteFinished", re);
+                Log.e(LOG_TAG, "Error calling onPrintFinished", re);
             }
         }
 
         @Override
         public void onPrintFailed(CharSequence error) {
             try {
-                mWrappedListener.onWriteFailed(error);
+                mWrappedCallback.onPrintFailed(error);
             } catch (RemoteException re) {
-                Log.e(LOG_TAG, "Error calling onWriteFailed", re);
+                Log.e(LOG_TAG, "Error calling onPrintFailed", re);
             }
         }
     }
diff --git a/core/java/android/print/pdf/PdfDocument.java b/core/java/android/print/pdf/PdfDocument.java
index 7fb170e212e9..7ce036d57a9f 100644
--- a/core/java/android/print/pdf/PdfDocument.java
+++ b/core/java/android/print/pdf/PdfDocument.java
@@ -105,7 +105,7 @@ public final class PdfDocument {
      * is created you can draw arbitrary content on the page's canvas which
      * you can get by calling {@link Page#getCanvas()}. After you are done
      * drawing the content you should finish the page by calling
-     * {@link #finishPage(Page). After the page is finished you should
+     * {@link #finishPage(Page)}. After the page is finished you should
      * no longer access the page or its canvas.
      * <p>
      * <strong>Note:</strong> Do not call this method after {@link #close()}.
diff --git a/core/java/android/printservice/PrintJob.java b/core/java/android/printservice/PrintJob.java
index 9688761e1d1a..f490f911936f 100644
--- a/core/java/android/printservice/PrintJob.java
+++ b/core/java/android/printservice/PrintJob.java
@@ -62,7 +62,7 @@ public final class PrintJob {
      * <p>
      * <strong>Node:</strong>The returned info object is a snapshot of the
      * current print job state. Every call to this method returns a fresh
-     * info object that reflects the current print jobs state.
+     * info object that reflects the current print job state.
      * </p>
      *
      * @return The print job info.
@@ -100,7 +100,7 @@ public final class PrintJob {
      *
      * @see #complete()
      * @see #cancel()
-     * @see #fail()
+     * @see #fail(CharSequence)
      */
     public boolean isStarted() {
         return  getInfo().getState() == PrintJobInfo.STATE_STARTED;
@@ -140,7 +140,8 @@ public final class PrintJob {
      * Fails the print job. You should call this method if {@link
      * #isStarted()} returns true you filed while printing.
      *
-     * @return Whether the job as failed.
+     * @param error The reason for the failure.
+     * @return Whether the job was failed.
      *
      * @see #isStarted()
      */
@@ -191,6 +192,9 @@ public final class PrintJob {
      * Gets the data associated with this print job. It is a responsibility of
      * the print service to open a stream to the returned file descriptor
      * and fully read the content.
+     * <p>
+     * <strong>Note:</strong> It is your responsibility to close the file descriptor.
+     * </p>
      *
      * @return A file descriptor for reading the data or <code>null</code>.
      */
diff --git a/core/java/android/printservice/PrintService.java b/core/java/android/printservice/PrintService.java
index d5cadc025244..92569661138d 100644
--- a/core/java/android/printservice/PrintService.java
+++ b/core/java/android/printservice/PrintService.java
@@ -52,7 +52,7 @@ import java.util.List;
  * Calls to {@link #addDiscoveredPrinters(List)} and
  * {@link #removeDiscoveredPrinters(List)} before a call to
  * {@link #onStartPrinterDiscovery()} and after a call to
- * {@link #onStopPrinterDiscovery()} is a no-op.
+ * {@link #onStopPrinterDiscovery()} are a no-op.
  * </p>
  * <p>
  * For every printer discovery period all printers have to be added. Each
@@ -68,7 +68,7 @@ import java.util.List;
  * service may handle it immediately or schedule that for an appropriate
  * time in the future. The list of all print jobs for this service
  * are be available by calling {@link #getPrintJobs()}. A queued print
- * job is in a {@link PrintJobInfo#STATE_QUEUED} state.
+ * job is one whose {@link PrintJob#isQueued()} return true.
  * </p>
  * <p>
  * A print service is responsible for setting the print job state as
@@ -200,7 +200,7 @@ public abstract class PrintService extends Service {
     /**
      * Callback requesting from this service to start printer discovery.
      * At the end of the printer discovery period the system will call
-     * {@link #onStopPrinterDiscovery(). Discovered printers should be
+     * {@link #onStopPrinterDiscovery()}. Discovered printers should be
      * reported by calling #addDiscoveredPrinters(List) and reported ones
      * that disappear should be reported by calling
      * {@link #removeDiscoveredPrinters(List)}.
@@ -299,8 +299,7 @@ public abstract class PrintService extends Service {
     /**
      * Called when canceling of a print job is requested. The service
      * should do best effort to fulfill the request. After the print
-     * job is canceled it state has to be set to
-     * {@link PrintJobInfo#STATE_CANCELED}.
+     * job is canceled by calling {@link PrintJob#cancel()}.
      *
      * @param printJob The print job to be canceled.
      */
diff --git a/packages/PrintSpooler/src/com/android/printspooler/RemotePrintAdapter.java b/packages/PrintSpooler/src/com/android/printspooler/RemotePrintAdapter.java
index 753721854a06..c81b00c6b167 100644
--- a/packages/PrintSpooler/src/com/android/printspooler/RemotePrintAdapter.java
+++ b/packages/PrintSpooler/src/com/android/printspooler/RemotePrintAdapter.java
@@ -20,7 +20,7 @@ import android.os.ICancellationSignal;
 import android.os.ParcelFileDescriptor;
 import android.os.RemoteException;
 import android.print.IPrintAdapter;
-import android.print.IPrintProgressListener;
+import android.print.IPrintResultCallback;
 import android.print.PageRange;
 import android.print.PrintAdapterInfo;
 import android.print.PrintAttributes;
@@ -50,7 +50,7 @@ final class RemotePrintAdapter {
 
     private final File mFile;
 
-    private final IPrintProgressListener mIPrintProgressListener;
+    private final IPrintResultCallback mIPrintProgressListener;
 
     private PrintAdapterInfo mInfo;
 
@@ -61,12 +61,12 @@ final class RemotePrintAdapter {
     public RemotePrintAdapter(IPrintAdapter printAdatper, File file) {
         mRemoteInterface = printAdatper;
         mFile = file;
-        mIPrintProgressListener = new IPrintProgressListener.Stub() {
+        mIPrintProgressListener = new IPrintResultCallback.Stub() {
             @Override
-            public void onWriteStarted(PrintAdapterInfo info,
+            public void onPrintStarted(PrintAdapterInfo info,
                     ICancellationSignal cancellationSignal) {
                 if (DEBUG) {
-                    Log.i(LOG_TAG, "IPrintProgressListener#onWriteStarted()");
+                    Log.i(LOG_TAG, "IPrintProgressListener#onPrintStarted()");
                 }
                 synchronized (mLock) {
                     mInfo = info;
@@ -75,9 +75,9 @@ final class RemotePrintAdapter {
             }
 
             @Override
-            public void onWriteFinished(List<PageRange> pages) {
+            public void onPrintFinished(List<PageRange> pages) {
                 if (DEBUG) {
-                    Log.i(LOG_TAG, "IPrintProgressListener#onWriteFinished(" + pages + ")");
+                    Log.i(LOG_TAG, "IPrintProgressListener#onPrintFinished(" + pages + ")");
                 }
                 synchronized (mLock) {
                     if (isPrintingLocked()) {
@@ -88,9 +88,9 @@ final class RemotePrintAdapter {
             }
 
             @Override
-            public void onWriteFailed(CharSequence error) {
+            public void onPrintFailed(CharSequence error) {
                 if (DEBUG) {
-                    Log.i(LOG_TAG, "IPrintProgressListener#onWriteFailed(" + error + ")");
+                    Log.i(LOG_TAG, "IPrintProgressListener#onPrintFailed(" + error + ")");
                 }
                 synchronized (mLock) {
                     if (isPrintingLocked()) {