Skip to content

Commit 3cd7c2d

Browse files
moxie0moxie0
committed
libjobqueue javadoc and scoping.
// FREEBIE
1 parent 5b08791 commit 3cd7c2d

11 files changed

Lines changed: 202 additions & 13 deletions

File tree

‎jobqueue/src/main/java/org/whispersystems/jobqueue/Job.java‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,10 @@
2121
import java.io.Serializable;
2222
import java.util.List;
2323

24+
/**
25+
* An abstract class representing a unit of work that can be scheduled with
26+
* the JobManager. This should be extended to implement tasks.
27+
*/
2428
public abstract class Job implements Serializable {
2529

2630
private final JobParameters parameters;
@@ -80,9 +84,31 @@ public void setRunIteration(int runIteration) {
8084
this.runIteration = runIteration;
8185
}
8286

87+
/**
88+
* Called after a job has been added to the JobManager queue. If it's a persistent job,
89+
* the state has been persisted to disk before this method is called.
90+
*/
8391
public abstract void onAdded();
92+
93+
/**
94+
* Called to actually execute the job.
95+
* @throws Exception
96+
*/
8497
public abstract void onRun() throws Exception;
98+
99+
/**
100+
* If onRun() throws an exception, this method will be called to determine whether the
101+
* job should be retried.
102+
*
103+
* @param exception The exception onRun() threw.
104+
* @return true if onRun() should be called again, false otherwise.
105+
*/
85106
public abstract boolean onShouldRetry(Exception exception);
107+
108+
/**
109+
* Called if a job fails to run (onShouldRetry returned false, or the number of retries exceeded
110+
* the job's configured retry count.
111+
*/
86112
public abstract void onCanceled();
87113

88114

‎jobqueue/src/main/java/org/whispersystems/jobqueue/JobConsumer.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020

2121
import org.whispersystems.jobqueue.persistence.PersistentStorage;
2222

23-
public class JobConsumer extends Thread {
23+
class JobConsumer extends Thread {
2424

2525
private static final String TAG = JobConsumer.class.getSimpleName();
2626

‎jobqueue/src/main/java/org/whispersystems/jobqueue/JobManager.java‎

Lines changed: 65 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,17 @@
2727

2828
import java.io.IOException;
2929
import java.util.Arrays;
30+
import java.util.LinkedList;
3031
import java.util.List;
3132
import java.util.concurrent.Executor;
3233
import java.util.concurrent.Executors;
3334
import java.util.concurrent.atomic.AtomicBoolean;
3435

36+
/**
37+
* A JobManager allows you to enqueue {@link org.whispersystems.jobqueue.Job} tasks
38+
* that are executed once a Job's {@link org.whispersystems.jobqueue.requirements.Requirement}s
39+
* are met.
40+
*/
3541
public class JobManager implements RequirementListener {
3642

3743
private final JobQueue jobQueue = new JobQueue();
@@ -64,15 +70,22 @@ private JobManager(Context context, String name,
6470
}
6571
}
6672

73+
/**
74+
* @param context An Android {@link android.content.Context}.
75+
* @return a {@link org.whispersystems.jobqueue.JobManager.Builder} used to construct a JobManager.
76+
*/
6777
public static Builder newBuilder(Context context) {
6878
return new Builder(context);
6979
}
7080

81+
/**
82+
* Returns a {@link org.whispersystems.jobqueue.requirements.RequirementProvider} registered with
83+
* the JobManager by name.
84+
*
85+
* @param name The name of the registered {@link org.whispersystems.jobqueue.requirements.RequirementProvider}
86+
* @return The RequirementProvider, or null if no provider is registered with that name.
87+
*/
7188
public RequirementProvider getRequirementProvider(String name) {
72-
if (requirementProviders == null || requirementProviders.isEmpty()) {
73-
return null;
74-
}
75-
7689
for (RequirementProvider provider : requirementProviders) {
7790
if (provider.getName().equals(name)) {
7891
return provider;
@@ -88,6 +101,11 @@ public void setEncryptionKeys(EncryptionKeys keys) {
88101
}
89102
}
90103

104+
/**
105+
* Queue a {@link org.whispersystems.jobqueue.Job} to be executed.
106+
*
107+
* @param job The Job to be executed.
108+
*/
91109
public void add(final Job job) {
92110
eventExecutor.execute(new Runnable() {
93111
@Override
@@ -153,36 +171,79 @@ public static class Builder {
153171
this.consumerThreads = 5;
154172
}
155173

174+
/**
175+
* A name for the {@link org.whispersystems.jobqueue.JobManager}. This is a required parameter,
176+
* and is linked to the durable queue used by persistent jobs.
177+
*
178+
* @param name The name for the JobManager to build.
179+
* @return The builder.
180+
*/
156181
public Builder withName(String name) {
157182
this.name = name;
158183
return this;
159184
}
160185

186+
/**
187+
* The {@link org.whispersystems.jobqueue.requirements.RequirementProvider}s to register with this
188+
* JobManager. Optional. Each {@link org.whispersystems.jobqueue.requirements.Requirement} an
189+
* enqueued Job depends on should have a matching RequirementProvider registered here.
190+
*
191+
* @param requirementProviders The RequirementProviders
192+
* @return The builder.
193+
*/
161194
public Builder withRequirementProviders(RequirementProvider... requirementProviders) {
162195
this.requirementProviders = Arrays.asList(requirementProviders);
163196
return this;
164197
}
165198

199+
/**
200+
* The {@link org.whispersystems.jobqueue.dependencies.DependencyInjector} to use for injecting
201+
* dependencies into {@link Job}s. Optional. Injection occurs just before a Job's onAdded() callback, or
202+
* after deserializing a persistent job.
203+
*
204+
* @param dependencyInjector The injector to use.
205+
* @return The builder.
206+
*/
166207
public Builder withDependencyInjector(DependencyInjector dependencyInjector) {
167208
this.dependencyInjector = dependencyInjector;
168209
return this;
169210
}
170211

212+
/**
213+
* The {@link org.whispersystems.jobqueue.persistence.JobSerializer} to use for persistent Jobs.
214+
* Required if persistent Jobs are used.
215+
*
216+
* @param jobSerializer The serializer to use.
217+
* @return The builder.
218+
*/
171219
public Builder withJobSerializer(JobSerializer jobSerializer) {
172220
this.jobSerializer = jobSerializer;
173221
return this;
174222
}
175223

224+
/**
225+
* Set the number of threads dedicated to consuming Jobs from the queue and executing them.
226+
*
227+
* @param consumerThreads The number of threads.
228+
* @return The builder.
229+
*/
176230
public Builder withConsumerThreads(int consumerThreads) {
177231
this.consumerThreads = consumerThreads;
178232
return this;
179233
}
180234

235+
/**
236+
* @return A constructed JobManager.
237+
*/
181238
public JobManager build() {
182239
if (name == null) {
183240
throw new IllegalArgumentException("You must specify a name!");
184241
}
185242

243+
if (requirementProviders == null) {
244+
requirementProviders = new LinkedList<>();
245+
}
246+
186247
return new JobManager(context, name, requirementProviders,
187248
dependencyInjector, jobSerializer,
188249
consumerThreads);

‎jobqueue/src/main/java/org/whispersystems/jobqueue/JobParameters.java‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@
2222
import java.util.LinkedList;
2323
import java.util.List;
2424

25+
/**
26+
* The set of parameters that describe a {@link org.whispersystems.jobqueue.Job}.
27+
*/
2528
public class JobParameters implements Serializable {
2629

2730
private transient EncryptionKeys encryptionKeys;
@@ -63,6 +66,9 @@ public int getRetryCount() {
6366
return retryCount;
6467
}
6568

69+
/**
70+
* @return a builder used to construct JobParameters.
71+
*/
6672
public static Builder newBuilder() {
6773
return new Builder();
6874
}
@@ -78,31 +84,64 @@ public static class Builder {
7884
private int retryCount = 100;
7985
private String groupId = null;
8086

87+
/**
88+
* Specify a {@link org.whispersystems.jobqueue.requirements.Requirement }that must be met
89+
* before the Job is executed. May be called multiple times to register multiple requirements.
90+
* @param requirement The Requirement that must be met.
91+
* @return the builder.
92+
*/
8193
public Builder withRequirement(Requirement requirement) {
8294
this.requirements.add(requirement);
8395
return this;
8496
}
8597

98+
/**
99+
* Specify that the Job should be durably persisted to disk, so that it remains in the queue
100+
* across application restarts.
101+
* @return The builder.
102+
*/
86103
public Builder withPersistence() {
87104
this.isPersistent = true;
88105
return this;
89106
}
90107

108+
/**
109+
* Specify that the job should use encryption when durably persisted to disk.
110+
* @param encryptionKeys The keys to encrypt the serialized job with before persisting.
111+
* @return the builder.
112+
*/
91113
public Builder withEncryption(EncryptionKeys encryptionKeys) {
92114
this.encryptionKeys = encryptionKeys;
93115
return this;
94116
}
95117

118+
/**
119+
* Specify how many times the job should be retried if execution fails but onShouldRetry() returns
120+
* true.
121+
*
122+
* @param retryCount The number of times the job should be retried.
123+
* @return the builder.
124+
*/
96125
public Builder withRetryCount(int retryCount) {
97126
this.retryCount = retryCount;
98127
return this;
99128
}
100129

130+
/**
131+
* Specify a groupId the job should belong to. Jobs with the same groupId are guaranteed to be
132+
* executed serially.
133+
*
134+
* @param groupId The job's groupId.
135+
* @return the builder.
136+
*/
101137
public Builder withGroupId(String groupId) {
102138
this.groupId = groupId;
103139
return this;
104140
}
105141

142+
/**
143+
* @return the JobParameters instance that describes a Job.
144+
*/
106145
public JobParameters create() {
107146
return new JobParameters(requirements, isPersistent, groupId, encryptionKeys, retryCount);
108147
}

‎jobqueue/src/main/java/org/whispersystems/jobqueue/JobQueue.java‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,29 +16,27 @@
1616
*/
1717
package org.whispersystems.jobqueue;
1818

19-
import java.util.HashMap;
2019
import java.util.HashSet;
2120
import java.util.LinkedList;
2221
import java.util.List;
2322
import java.util.ListIterator;
24-
import java.util.Map;
2523
import java.util.Set;
2624

27-
public class JobQueue {
25+
class JobQueue {
2826

2927
private final Set<String> activeGroupIds = new HashSet<>();
3028
private final LinkedList<Job> jobQueue = new LinkedList<>();
3129

32-
public synchronized void onRequirementStatusChanged() {
30+
synchronized void onRequirementStatusChanged() {
3331
notifyAll();
3432
}
3533

36-
public synchronized void add(Job job) {
34+
synchronized void add(Job job) {
3735
jobQueue.add(job);
3836
notifyAll();
3937
}
4038

41-
public synchronized void addAll(List<Job> jobs) {
39+
synchronized void addAll(List<Job> jobs) {
4240
jobQueue.addAll(jobs);
4341
notifyAll();
4442
}
@@ -47,7 +45,7 @@ synchronized void push(Job job) {
4745
jobQueue.push(job);
4846
}
4947

50-
public synchronized Job getNext() {
48+
synchronized Job getNext() {
5149
try {
5250
Job nextAvailableJob;
5351

@@ -61,7 +59,7 @@ public synchronized Job getNext() {
6159
}
6260
}
6361

64-
public synchronized void setGroupIdAvailable(String groupId) {
62+
synchronized void setGroupIdAvailable(String groupId) {
6563
if (groupId != null) {
6664
activeGroupIds.remove(groupId);
6765
notifyAll();

‎jobqueue/src/main/java/org/whispersystems/jobqueue/dependencies/DependencyInjector.java‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,24 @@
1+
/**
2+
* Copyright (C) 2014 Open Whisper Systems
3+
*
4+
* This program is free software: you can redistribute it and/or modify
5+
* it under the terms of the GNU General Public License as published by
6+
* the Free Software Foundation, either version 3 of the License, or
7+
* (at your option) any later version.
8+
*
9+
* This program is distributed in the hope that it will be useful,
10+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
11+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12+
* GNU General Public License for more details.
13+
*
14+
* You should have received a copy of the GNU General Public License
15+
* along with this program. If not, see <http://www.gnu.org/licenses/>.
16+
*/
117
package org.whispersystems.jobqueue.dependencies;
218

19+
/**
20+
* Interface responsible for injecting dependencies into Jobs.
21+
*/
322
public interface DependencyInjector {
423
public void injectDependencies(Object object);
524
}

‎jobqueue/src/main/java/org/whispersystems/jobqueue/persistence/JavaJobSerializer.java‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@
3030
import java.io.ObjectInputStream;
3131
import java.io.ObjectOutputStream;
3232

33+
/**
34+
* An implementation of {@link org.whispersystems.jobqueue.persistence.JobSerializer} that uses
35+
* Java Serialization.
36+
*/
3337
public class JavaJobSerializer implements JobSerializer {
3438

3539
private final Context context;

‎jobqueue/src/main/java/org/whispersystems/jobqueue/persistence/JobSerializer.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,27 @@
2121

2222
import java.io.IOException;
2323

24+
/**
25+
* A JobSerializer is responsible for serializing and deserializing persistent jobs.
26+
*/
2427
public interface JobSerializer {
2528

29+
/**
30+
* Serialize a job object into a string.
31+
* @param job The Job to serialize.
32+
* @return The serialized Job.
33+
* @throws IOException if serialization fails.
34+
*/
2635
public String serialize(Job job) throws IOException;
36+
37+
/**
38+
* Deserialize a String into a Job.
39+
* @param keys Optional encryption keys that could have been used.
40+
* @param encrypted True if the job was encrypted using the encryption keys.
41+
* @param serialized The serialized Job.
42+
* @return The deserialized Job.
43+
* @throws IOException If the Job deserialization fails.
44+
*/
2745
public Job deserialize(EncryptionKeys keys, boolean encrypted, String serialized) throws IOException;
2846

2947
}

‎jobqueue/src/main/java/org/whispersystems/jobqueue/requirements/NetworkRequirement.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@
2222

2323
import org.whispersystems.jobqueue.dependencies.ContextDependent;
2424

25+
/**
26+
* A requirement that is satisfied when a network connection is present.
27+
*/
2528
public class NetworkRequirement implements Requirement, ContextDependent {
2629

2730
private transient Context context;

0 commit comments

Comments
 (0)