PrintJob.java revision c43639c3067dda5df189fb3cbf14f256c17e677d
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 17package android.print; 18 19import android.annotation.NonNull; 20import android.annotation.Nullable; 21 22/** 23 * This class represents a print job from the perspective of an 24 * application. It contains behavior methods for performing operations 25 * on it as well as methods for querying its state. A snapshot of the 26 * print job state is represented by the {@link PrintJobInfo} class. 27 * The state of a print job may change over time. An application receives 28 * instances of this class when creating a print job or querying for 29 * its print jobs. 30 */ 31public final class PrintJob { 32 33 private final PrintManager mPrintManager; 34 35 private PrintJobInfo mCachedInfo; 36 37 PrintJob(PrintJobInfo info, PrintManager printManager) { 38 mCachedInfo = info; 39 mPrintManager = printManager; 40 } 41 42 /** 43 * Gets the unique print job id. 44 * 45 * @return The id. 46 */ 47 public @NonNull PrintJobId getId() { 48 return mCachedInfo.getId(); 49 } 50 51 /** 52 * Gets the {@link PrintJobInfo} that describes this job. 53 * <p> 54 * <strong>Node:</strong>The returned info object is a snapshot of the 55 * current print job state. Every call to this method returns a fresh 56 * info object that reflects the current print job state. 57 * </p> 58 * 59 * @return The print job info. 60 */ 61 public @Nullable PrintJobInfo getInfo() { 62 if (isInImmutableState()) { 63 return mCachedInfo; 64 } 65 PrintJobInfo info = mPrintManager.getPrintJobInfo(mCachedInfo.getId()); 66 if (info != null) { 67 mCachedInfo = info; 68 } 69 return mCachedInfo; 70 } 71 72 /** 73 * Cancels this print job. You can request cancellation of a 74 * queued, started, blocked, or failed print job. 75 * 76 * @see #isQueued() 77 * @see #isStarted() 78 * @see #isBlocked() 79 * @see #isFailed() 80 */ 81 public void cancel() { 82 final int state = getInfo().getState(); 83 if (state == PrintJobInfo.STATE_QUEUED 84 || state == PrintJobInfo.STATE_STARTED 85 || state == PrintJobInfo.STATE_BLOCKED 86 || state == PrintJobInfo.STATE_FAILED) { 87 mPrintManager.cancelPrintJob(mCachedInfo.getId()); 88 } 89 } 90 91 /** 92 * Restarts this print job. You can request restart of a failed 93 * print job. 94 * 95 * @see #isFailed() 96 */ 97 public void restart() { 98 if (isFailed()) { 99 mPrintManager.restartPrintJob(mCachedInfo.getId()); 100 } 101 } 102 103 /** 104 * Gets whether this print job is queued. Such a print job is 105 * ready to be printed. You can request a cancellation via 106 * {@link #cancel()}. 107 * 108 * @return Whether the print job is queued. 109 * 110 * @see #cancel() 111 */ 112 public boolean isQueued() { 113 return getInfo().getState() == PrintJobInfo.STATE_QUEUED; 114 } 115 116 /** 117 * Gets whether this print job is started. Such a print job is 118 * being printed. You can request a cancellation via 119 * {@link #cancel()}. 120 * 121 * @return Whether the print job is started. 122 * 123 * @see #cancel() 124 */ 125 public boolean isStarted() { 126 return getInfo().getState() == PrintJobInfo.STATE_STARTED; 127 } 128 129 /** 130 * Gets whether this print job is blocked. Such a print job is halted 131 * due to an abnormal condition. You can request a cancellation via 132 * {@link #cancel()}. 133 * 134 * @return Whether the print job is blocked. 135 * 136 * @see #cancel() 137 */ 138 public boolean isBlocked() { 139 return getInfo().getState() == PrintJobInfo.STATE_BLOCKED; 140 } 141 142 /** 143 * Gets whether this print job is completed. Such a print job 144 * is successfully printed. You can neither cancel nor restart 145 * such a print job. 146 * 147 * @return Whether the print job is completed. 148 */ 149 public boolean isCompleted() { 150 return getInfo().getState() == PrintJobInfo.STATE_COMPLETED; 151 } 152 153 /** 154 * Gets whether this print job is failed. Such a print job is 155 * not successfully printed due to an error. You can request 156 * a restart via {@link #restart()} or cancel via {@link #cancel()}. 157 * 158 * @return Whether the print job is failed. 159 * 160 * @see #restart() 161 * @see #cancel() 162 */ 163 public boolean isFailed() { 164 return getInfo().getState() == PrintJobInfo.STATE_FAILED; 165 } 166 167 /** 168 * Gets whether this print job is cancelled. Such a print job was 169 * cancelled as a result of a user request. This is a final state. 170 * You cannot restart such a print job. 171 * 172 * @return Whether the print job is cancelled. 173 */ 174 public boolean isCancelled() { 175 return getInfo().getState() == PrintJobInfo.STATE_CANCELED; 176 } 177 178 private boolean isInImmutableState() { 179 final int state = mCachedInfo.getState(); 180 return state == PrintJobInfo.STATE_COMPLETED 181 || state == PrintJobInfo.STATE_CANCELED; 182 } 183 184 @Override 185 public boolean equals(Object obj) { 186 if (this == obj) { 187 return true; 188 } 189 if (obj == null) { 190 return false; 191 } 192 if (getClass() != obj.getClass()) { 193 return false; 194 } 195 PrintJob other = (PrintJob) obj; 196 return mCachedInfo.getId().equals(other.mCachedInfo.getId()); 197 } 198 199 @Override 200 public int hashCode() { 201 return mCachedInfo.getId().hashCode(); 202 } 203} 204