Author: ieb
Date: Wed Sep 21 11:01:05 2016
New Revision: 1761717
URL: http://svn.apache.org/viewvc?rev=1761717&view=rev
Log:
Added missing documentation to the MoM Jobs example
Modified:
sling/trunk/contrib/commons/mom/examples/jobs/core/README.md
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobBuilder.java
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobCallback.java
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobManager.java
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobTypeValve.java
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobUpdateBuilder.java
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/Types.java
Modified: sling/trunk/contrib/commons/mom/examples/jobs/core/README.md
URL:
http://svn.apache.org/viewvc/sling/trunk/contrib/commons/mom/examples/jobs/core/README.md?rev=1761717&r1=1761716&r2=1761717&view=diff
==============================================================================
--- sling/trunk/contrib/commons/mom/examples/jobs/core/README.md (original)
+++ sling/trunk/contrib/commons/mom/examples/jobs/core/README.md Wed Sep 21
11:01:05 2016
@@ -4,4 +4,24 @@ This Bundle provides Job processing usin
provide an API that allows interaction with the queue beyond that is supported
by the ISO AMQP standard or the JMS API. Although the
classes here may have similar names to the API in org.apache.sling.egent.jobs,
they are not the same. Methods present
in org.apache.sling.egent.jobs API that are not compatible with a distributed
message queue concept are not included, and the
-API is designed with message passing in mind.
\ No newline at end of file
+API is designed with message passing in mind.
+
+
+# How it works.
+
+MoM Queues transport messages that control the state of a Job taking it
through a lifecycle from creation to distruction. Not all messages
+are required to live that lifecycle, only the create message is required under
normal circumstances.
+
+A MoM QueueReader implemented by the JobQueueConsumerFactory consumes messages
from MoM Queues. This is a OSGi Configuration Factory
+allowing many JobQueueConsumers to dequeue messages from a MoM Queue. When a
message is dequeued and identified correctly as a
+Job related message, it is forward to the JobSubsystem component.
+
+The JobSubsystem component allows JobConsumers to register with it. It
interprets the messages, creating Jobs and managing their lifecycle.
+It will identify JobConsumers that can consume the job and invoke the execute
method on the JobConsumer.
+
+JobConsumers are where the job itself is implemented. Components that
implement this API are registered as services which get
+registered by OSGi DS with the JobSubsystem. Each JobConsumer declares a list
of JobTypes it will consume. There is a special
+JobType of ANY_TYPE for consumers that want to consume any Job. To use the
JobSubsystem you will need to implement your own
+JobConsumers. There are examples of JobConsumers in this source code area.
+
+
\ No newline at end of file
Modified:
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobBuilder.java
URL:
http://svn.apache.org/viewvc/sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobBuilder.java?rev=1761717&r1=1761716&r2=1761717&view=diff
==============================================================================
---
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobBuilder.java
(original)
+++
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobBuilder.java
Wed Sep 21 11:01:05 2016
@@ -22,6 +22,7 @@ import javax.annotation.Nonnull;
import java.util.Map;
/**
+ * A JobBuilder allows users of the JobSystem to modify the properties of the
Job and submit it for processing.
*/
public interface JobBuilder {
Modified:
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobCallback.java
URL:
http://svn.apache.org/viewvc/sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobCallback.java?rev=1761717&r1=1761716&r2=1761717&view=diff
==============================================================================
---
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobCallback.java
(original)
+++
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobCallback.java
Wed Sep 21 11:01:05 2016
@@ -26,5 +26,9 @@ package org.apache.sling.jobs;
*/
public interface JobCallback {
+ /**
+ * Call back with an update job state.
+ * @param finalJobState
+ */
void callback(Job finalJobState);
}
Modified:
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobManager.java
URL:
http://svn.apache.org/viewvc/sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobManager.java?rev=1761717&r1=1761716&r2=1761717&view=diff
==============================================================================
---
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobManager.java
(original)
+++
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobManager.java
Wed Sep 21 11:01:05 2016
@@ -34,8 +34,9 @@ public interface JobManager {
/**
* Fluent API to create, start and schedule new jobs
- * @param queue Required queue
- * @param jobType required job type.
+ * @param queue Required queue. This job will be submitted to the named
queue.
+ * @param jobType required job type. The job will have a job type which
is used to select the Job consumer that can
+ * process the job.
* @return A job builder
*/
@Nonnull
Modified:
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobTypeValve.java
URL:
http://svn.apache.org/viewvc/sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobTypeValve.java?rev=1761717&r1=1761716&r2=1761717&view=diff
==============================================================================
---
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobTypeValve.java
(original)
+++
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobTypeValve.java
Wed Sep 21 11:01:05 2016
@@ -22,6 +22,9 @@ import javax.annotation.Nonnull;
/**
* Created by ieb on 12/04/2016.
+ * An interface to allow a component, normally a JobConsumer to inspect a
JobType and indicate that
+ * it can perform further actions on it. JobTypeValves are used in place of
static JobType declarations.
+ * This interface is only implemented where static declaration of JobTypes
does not satisfy the use cases.
*/
public interface JobTypeValve {
Modified:
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobUpdateBuilder.java
URL:
http://svn.apache.org/viewvc/sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobUpdateBuilder.java?rev=1761717&r1=1761716&r2=1761717&view=diff
==============================================================================
---
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobUpdateBuilder.java
(original)
+++
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/JobUpdateBuilder.java
Wed Sep 21 11:01:05 2016
@@ -25,6 +25,7 @@ import java.util.Map;
/**
* Created by ieb on 14/04/2016.
+ * Create a job update ading properties and building.
*/
public interface JobUpdateBuilder {
Modified:
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/Types.java
URL:
http://svn.apache.org/viewvc/sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/Types.java?rev=1761717&r1=1761716&r2=1761717&view=diff
==============================================================================
---
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/Types.java
(original)
+++
sling/trunk/contrib/commons/mom/examples/jobs/core/src/main/java/org/apache/sling/jobs/Types.java
Wed Sep 21 11:01:05 2016
@@ -31,10 +31,15 @@ public final class Types {
+
private Types() {
}
+ /**
+ * Interface to identify JobQueues. JobQueues have an associated MoM Queue
and a MoM Topic, both of which
+ * are available via this interface. The MoM Queue contains commands, the
the MoM Topic contains status updates.
+ */
public interface JobQueue {
org.apache.sling.mom.Types.QueueName asQueueName();
@@ -42,17 +47,36 @@ public final class Types {
}
+ /**
+ * Interface to identify JobTypes. Jobs are identified by a JobType,
independent of the JobQueue or the underlying
+ * MoM Queue or MoM Topic.
+ */
public interface JobType {
}
+ /**
+ * Create a JobQueue from a string represtnation, normally this us a path
representing the jobQueue, although the path
+ * hierachy may not have any significance depending on the MoM
implementation.
+ * @param jobQueue
+ * @return
+ */
public static JobQueue jobQueue(String jobQueue) {
return new JobQueueImpl(jobQueue);
}
+ /**
+ * Create a JobType from a string representation.
+ * @param jobType
+ * @return
+ */
public static JobType jobType(String jobType) {
return new JobTypeImpl(jobType);
}
+ /**
+ * A special JobQueue that represents any available queue. Normally used
for filtering queue messages. Probably wont
+ * work as a destination queue (broadcast) depending on the MoM
Implementation.
+ */
public static JobQueue ANY_JOB_QUEUE = new AnyJobQueue();
