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 PrintJob(@onNull PrintJobInfo info, @NonNull PrintManager printManager)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 */ getId()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 */ getInfo()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 */ cancel()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 */ restart()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 */ isQueued()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 */ isStarted()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 */ isBlocked()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 */ isCompleted()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 */ isFailed()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 */ isCancelled()176 public boolean isCancelled() { 177 return getInfo().getState() == PrintJobInfo.STATE_CANCELED; 178 } 179 isInImmutableState()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 equals(Object obj)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 hashCode()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