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
22import 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 */
33public 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