Changeset 2834b9a

Timestamp:

Jan 22, 2012, 1:12:53 AM (12 years ago)

Author:

Jessica B. Hamrick <jhamrick@…>

Branches:

no-cups

Children:

410ad69

Parents:

97f20dd

git-author:

Jessica B. Hamrick <jhamrick@…> (01/22/12 01:12:53)

git-committer:

Jessica B. Hamrick <jhamrick@…> (01/22/12 01:12:53)

Message:

Add documentation to the state attribute in job.py

File:

• server/lib/gutenbach/server/job.py (modified) (1 diff)

server/lib/gutenbach/server/job.py

@@ -231 +231 @@
     @property
     def state(self):
-        """State status codes (these are equivalent to the IPP
-        job-state status codes).  State transitions are as follows:
-        
-            HELD ---> PENDING ---> PROCESSING <--> STOPPED (aka paused)
-                         ^              |---> CANCELED
-                         |              |---> ABORTED
-                         |              |---> COMPLETE ---|
-                         |--------------------------------|
-                     
-        """
+        """RFC 2911: 4.3.7 job-state (type1 enum)
+
+        'pending': The job is a candidate to start processing, but is
+            not yet processing.
+
+        'pending-held': The job is not a candidate for processing for
+            any number of reasons but will return to the 'pending'
+            state as soon as the reasons are no longer present. The
+            job's 'job-state-reason' attribute MUST indicate why the
+            job is no longer a candidate for processing.
+
+        'processing': One or more of:
+        
+            1. the job is using, or is attempting to use, one or more
+               purely software processes that are analyzing, creating,
+               or interpreting a PDL, etc.,
+            2. the job is using, or is attempting to use, one or more
+               hardware devices that are interpreting a PDL, making
+               marks on a medium, and/or performing finishing, such as
+               stapling, etc.,
+            3. the Printer object has made the job ready for printing,
+               but the output device is not yet printing it, either
+               because the job hasn't reached the output device or
+               because the job is queued in the output device or some
+               other spooler, awaiting the output device to print it.
+
+            When the job is in the 'processing' state, the entire job
+            state includes the detailed status represented in the
+            Printer object's 'printer-state', 'printer-state-
+            reasons', and 'printer-state-message' attributes.
+
+            Implementations MAY, though they NEED NOT, include
+            additional values in the job's 'job-state-reasons'
+            attribute to indicate the progress of the job, such as
+            adding the 'job-printing' value to indicate when the
+            output device is actually making marks on paper and/or the
+            'processing-to-stop-point' value to indicate that the IPP
+            object is in the process of canceling or aborting the
+            job. Most implementations won't bother with this nuance.
+
+        'processing-stopped': The job has stopped while processing for
+            any number of reasons and will return to the 'processing'
+            state as soon as the reasons are no longer present.
+
+            The job's 'job-state-reason' attribute MAY indicate why
+            the job has stopped processing. For example, if the output
+            device is stopped, the 'printer-stopped' value MAY be
+            included in the job's 'job-state-reasons' attribute.
+
+            Note: When an output device is stopped, the device usually
+            indicates its condition in human readable form locally at
+            the device. A client can obtain more complete device
+            status remotely by querying the Printer object's
+            'printer-state', 'printer-state-reasons' and 'printer-
+            state-message' attributes.
+
+        'canceled': The job has been canceled by a Cancel-Job
+            operation and the Printer object has completed canceling
+            the job and all job status attributes have reached their
+            final values for the job. While the Printer object is
+            canceling the job, the job remains in its current state,
+            but the job's 'job-state-reasons' attribute SHOULD contain
+            the 'processing-to-stop-point' value and one of the
+            'canceled-by-user', 'canceled-by-operator', or
+            'canceled-at-device' value. When the job moves to the
+            'canceled' state, the 'processing-to-stop-point' value, if
+            present, MUST be removed, but the 'canceled-by-xxx', if
+            present, MUST remain.
+
+        'aborted': The job has been aborted by the system, usually
+            while the job was in the 'processing' or 'processing-
+            stopped' state and the Printer has completed aborting the
+            job and all job status attributes have reached their final
+            values for the job. While the Printer object is aborting
+            the job, the job remains in its current state, but the
+            job's 'job-state-reasons' attribute SHOULD contain the
+            'processing-to-stop-point' and 'aborted-by- system'
+            values. When the job moves to the 'aborted' state, the
+            'processing-to-stop-point' value, if present, MUST be
+            removed, but the 'aborted-by-system' value, if present,
+            MUST remain.
+
+        'completed': The job has completed successfully or with
+            warnings or errors after processing and all of the job
+            media sheets have been successfully stacked in the
+            appropriate output bin(s) and all job status attributes
+            have reached their final values for the job. The job's
+            'job-state-reasons' attribute SHOULD contain one of:
+            'completed-successfully', 'completed-with-warnings', or
+            'completed-with-errors' values.
+
+        The final value for this attribute MUST be one of:
+        'completed', 'canceled', or 'aborted' before the Printer
+        removes the job altogether. The length of time that jobs
+        remain in the 'canceled', 'aborted', and 'completed' states
+        depends on implementation. See section 4.3.7.2.
+
+        The following figure shows the normal job state transitions.
+        
+                                                           +----> canceled
+                                                          /
+            +----> pending --------> processing ---------+------> completed
+            |         ^                   ^               \
+        --->+         |                   |                +----> aborted
+            |         v                   v               /
+            +----> pending-held    processing-stopped ---+
+
+        Normally a job progresses from left to right. Other state
+        transitions are unlikely, but are not forbidden. Not shown are
+        the transitions to the 'canceled' state from the 'pending',
+        'pending- held', and 'processing-stopped' states.
+
+        Jobs reach one of the three terminal states: 'completed',
+        'canceled', or 'aborted', after the jobs have completed all
+        activity, including stacking output media, after the jobs have
+        completed all activity, and all job status attributes have
+        reached their final values for the job.
+
+        """
+
+        # XXX verify that these transitions are correct!
 
         if self.is_ready: