Home | History | Annotate | Download | only in print 
      1 /*
      2  * Copyright (C) 2013 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package android.print;
     18 
     19 import android.annotation.NonNull;
     20 import android.annotation.Nullable;
     21 
     22 import java.util.Objects;
     23 
     24 /**
     25  * This class represents a print job from the perspective of an
     26  * application. It contains behavior methods for performing operations
     27  * on it as well as methods for querying its state. A snapshot of the
     28  * print job state is represented by the {@link PrintJobInfo} class.
     29  * The state of a print job may change over time. An application receives
     30  * instances of this class when creating a print job or querying for
     31  * its print jobs.
     32  */
     33 public final class PrintJob {
     34 
     35     private final @NonNull PrintManager mPrintManager;
     36 
     37     private @NonNull PrintJobInfo mCachedInfo;
     38 
     39     PrintJob(@NonNull PrintJobInfo info, @NonNull PrintManager printManager) {
     40         mCachedInfo = info;
     41         mPrintManager = printManager;
     42     }
     43 
     44     /**
     45      * Gets the unique print job id.
     46      *
     47      * @return The id.
     48      */
     49     public @Nullable PrintJobId getId() {
     50         return mCachedInfo.getId();
     51     }
     52 
     53     /**
     54      * Gets the {@link PrintJobInfo} that describes this job.
     55      * <p>
     56      * <strong>Node:</strong>The returned info object is a snapshot of the
     57      * current print job state. Every call to this method returns a fresh
     58      * info object that reflects the current print job state.
     59      * </p>
     60      *
     61      * @return The print job info.
     62      */
     63     public @NonNull PrintJobInfo getInfo() {
     64         if (isInImmutableState()) {
     65             return mCachedInfo;
     66         }
     67         PrintJobInfo info = mPrintManager.getPrintJobInfo(mCachedInfo.getId());
     68         if (info != null) {
     69             mCachedInfo = info;
     70         }
     71         return mCachedInfo;
     72     }
     73 
     74     /**
     75      * Cancels this print job. You can request cancellation of a
     76      * queued, started, blocked, or failed print job.
     77      *
     78      * @see #isQueued()
     79      * @see #isStarted()
     80      * @see #isBlocked()
     81      * @see #isFailed()
     82      */
     83     public void cancel() {
     84         final int state = getInfo().getState();
     85         if (state == PrintJobInfo.STATE_QUEUED
     86                 || state == PrintJobInfo.STATE_STARTED
     87                 || state == PrintJobInfo.STATE_BLOCKED
     88                 || state == PrintJobInfo.STATE_FAILED) {
     89             mPrintManager.cancelPrintJob(mCachedInfo.getId());
     90         }
     91     }
     92 
     93     /**
     94      * Restarts this print job. You can request restart of a failed
     95      * print job.
     96      *
     97      * @see #isFailed()
     98      */
     99     public void restart() {
    100         if (isFailed()) {
    101             mPrintManager.restartPrintJob(mCachedInfo.getId());
    102         }
    103     }
    104 
    105     /**
    106      * Gets whether this print job is queued. Such a print job is
    107      * ready to be printed. You can request a cancellation via
    108      * {@link #cancel()}.
    109      *
    110      * @return Whether the print job is queued.
    111      *
    112      * @see #cancel()
    113      */
    114     public boolean isQueued() {
    115         return getInfo().getState() == PrintJobInfo.STATE_QUEUED;
    116     }
    117 
    118     /**
    119      * Gets whether this print job is started. Such a print job is
    120      * being printed. You can request a cancellation via
    121      * {@link #cancel()}.
    122      *
    123      * @return Whether the print job is started.
    124      *
    125      * @see #cancel()
    126      */
    127     public boolean isStarted() {
    128         return getInfo().getState() == PrintJobInfo.STATE_STARTED;
    129     }
    130 
    131     /**
    132      * Gets whether this print job is blocked. Such a print job is halted
    133      * due to an abnormal condition. You can request a cancellation via
    134      * {@link #cancel()}.
    135      *
    136      * @return Whether the print job is blocked.
    137      *
    138      * @see #cancel()
    139      */
    140     public boolean isBlocked() {
    141         return getInfo().getState() == PrintJobInfo.STATE_BLOCKED;
    142     }
    143 
    144     /**
    145      * Gets whether this print job is completed. Such a print job
    146      * is successfully printed. You can neither cancel nor restart
    147      * such a print job.
    148      *
    149      * @return Whether the print job is completed.
    150      */
    151     public boolean isCompleted() {
    152         return getInfo().getState() == PrintJobInfo.STATE_COMPLETED;
    153     }
    154 
    155     /**
    156      * Gets whether this print job is failed. Such a print job is
    157      * not successfully printed due to an error. You can request
    158      * a restart via {@link #restart()} or cancel via {@link #cancel()}.
    159      *
    160      * @return Whether the print job is failed.
    161      *
    162      * @see #restart()
    163      * @see #cancel()
    164      */
    165     public boolean isFailed() {
    166         return getInfo().getState() == PrintJobInfo.STATE_FAILED;
    167     }
    168 
    169     /**
    170      * Gets whether this print job is cancelled. Such a print job was
    171      * cancelled as a result of a user request. This is a final state.
    172      * You cannot restart such a print job.
    173      *
    174      * @return Whether the print job is cancelled.
    175      */
    176     public boolean isCancelled() {
    177         return getInfo().getState() == PrintJobInfo.STATE_CANCELED;
    178     }
    179 
    180     private boolean isInImmutableState() {
    181         final int state = mCachedInfo.getState();
    182         return state == PrintJobInfo.STATE_COMPLETED
    183                 || state == PrintJobInfo.STATE_CANCELED;
    184     }
    185 
    186     @Override
    187     public boolean equals(Object obj) {
    188         if (this == obj) {
    189             return true;
    190         }
    191         if (obj == null) {
    192             return false;
    193         }
    194         if (getClass() != obj.getClass()) {
    195             return false;
    196         }
    197         PrintJob other = (PrintJob) obj;
    198         return Objects.equals(mCachedInfo.getId(), other.mCachedInfo.getId());
    199     }
    200 
    201     @Override
    202     public int hashCode() {
    203         PrintJobId printJobId = mCachedInfo.getId();
    204 
    205         if (printJobId == null) {
    206             return 0;
    207         } else {
    208             return printJobId.hashCode();
    209         }
    210     }
    211 }
    212