1 /*
   2  * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package javax.print.attribute.standard;
  26 
  27 import javax.print.attribute.EnumSyntax;
  28 import javax.print.attribute.Attribute;
  29 
  30 /**
  31  * Class JobStateReason is a printing attribute class, an enumeration, that
  32  * provides additional information about the job's current state, i.e.,
  33  * information that augments the value of the job's {@link JobState JobState}
  34  * attribute. Class JobStateReason defines standard job state reason values. A
  35  * Print Service implementation only needs to report those job state
  36  * reasons which are appropriate for the particular implementation; it does not
  37  * have to report every defined job state reason.
  38  * <P>
  39  * Instances of JobStateReason do not appear in a Print Job's attribute set
  40  * directly. Rather, a {@link JobStateReasons JobStateReasons} attribute appears
  41  * in the Print Job's attribute set. The {@link JobStateReasons JobStateReasons}
  42  * attribute contains zero, one, or more than one JobStateReason objects which
  43  * pertain to the Print Job's status. The printer adds a JobStateReason object
  44  * to the Print Job's {@link JobStateReasons JobStateReasons} attribute when the
  45  * corresponding condition becomes true of the Print Job, and the printer
  46  * removes the JobStateReason object again when the corresponding condition
  47  * becomes false, regardless of whether the Print Job's overall {@link JobState
  48  * JobState} also changed.
  49  * <P>
  50  * <B>IPP Compatibility:</B> The category name returned by
  51  * <CODE>getName()</CODE> is the IPP attribute name.  The enumeration's
  52  * integer value is the IPP enum value.  The <code>toString()</code> method
  53  * returns the IPP string representation of the attribute value.
  54  * <P>
  55  *
  56  * @author  Alan Kaminsky
  57  */
  58 public class JobStateReason extends EnumSyntax implements Attribute {
  59 
  60     private static final long serialVersionUID = -8765894420449009168L;
  61 
  62     /**
  63      * The printer has created the Print Job, but the printer has not finished
  64      * accessing or accepting all the print data yet.
  65      */
  66     public static final JobStateReason
  67         JOB_INCOMING = new JobStateReason(0);
  68 
  69     /**
  70      * The printer has created the Print Job, but the printer is expecting
  71      * additional print data before it can move the job into the PROCESSING
  72      * state. If a printer starts processing before it has received all data,
  73      * the printer removes the JOB_DATA_INSUFFICIENT reason, but the
  74      * JOB_INCOMING reason remains. If a printer starts processing after it
  75      * has received all data, the printer removes the JOB_DATA_INSUFFICIENT
  76      * and JOB_INCOMING reasons at the same time.
  77      */
  78     public static final JobStateReason
  79         JOB_DATA_INSUFFICIENT = new JobStateReason(1);
  80 
  81     /**
  82      * The Printer could not access one or more documents passed by reference
  83      * (i.e., the print data representation object is a URL). This reason is
  84      * intended to cover any file access problem,including file does not exist
  85      * and access denied because of an access control problem. Whether the
  86      * printer aborts the job and moves the job to the ABORTED job state or
  87      * prints all documents that are accessible and moves the job to the
  88      * COMPLETED job state and adds the COMPLETED_WITH_ERRORS reason to the
  89      * job's {@link JobStateReasons JobStateReasons} attribute depends on
  90      * implementation and/or site policy. This value should be supported if
  91      * the printer supports doc flavors with URL print data representation
  92      * objects.
  93      */
  94     public static final JobStateReason
  95         DOCUMENT_ACCESS_ERROR = new JobStateReason(2);
  96 
  97     /**
  98      * The job was not completely submitted for some unforeseen reason.
  99      * Possibilities include (1) the printer has crashed before the job was
 100      * fully submitted by the client, (2) the printer or the document transfer
 101      * method has crashed in some non-recoverable way before the document data
 102      * was entirely transferred to the printer, (3) the client crashed before
 103      * the job was fully submitted.
 104      */
 105     public static final JobStateReason
 106         SUBMISSION_INTERRUPTED = new JobStateReason(3);
 107 
 108     /**
 109      * The printer is transmitting the job to the output device.
 110      */
 111     public static final JobStateReason
 112         JOB_OUTGOING = new JobStateReason(4);
 113 
 114     /**
 115      * The value of the job's {@link JobHoldUntil JobHoldUntil} attribute was
 116      * specified with a date-time that is still in the future. The job must
 117      * not be a candidate for processing until this reason is removed and
 118      * there are
 119      * no other reasons to hold the job. This value should be supported if the
 120      * {@link JobHoldUntil JobHoldUntil} job template attribute is supported.
 121      */
 122     public static final JobStateReason
 123         JOB_HOLD_UNTIL_SPECIFIED = new JobStateReason(5);
 124 
 125     /**
 126      * At least one of the resources needed by the job, such as media, fonts,
 127      * resource objects, etc., is not ready on any of the physical printers
 128      * for which the job is a candidate. This condition may be detected
 129      * when the job is accepted, or subsequently while the job is pending
 130      * or processing, depending on implementation.
 131      * The job may remain in its current state or
 132      * be moved to the PENDING_HELD state, depending on implementation and/or
 133      * job scheduling policy.
 134      */
 135     public static final JobStateReason
 136         RESOURCES_ARE_NOT_READY = new JobStateReason(6);
 137 
 138     /**
 139      * The value of the printer's {@link PrinterStateReasons
 140      * PrinterStateReasons} attribute contains a {@link PrinterStateReason
 141      * PrinterStateReason} value of STOPPED_PARTLY.
 142      */
 143     public static final JobStateReason
 144         PRINTER_STOPPED_PARTLY = new JobStateReason(7);
 145 
 146     /**
 147      * The value of the printer's {@link PrinterState PrinterState} attribute
 148      * ia STOPPED.
 149      */
 150     public static final JobStateReason
 151         PRINTER_STOPPED = new JobStateReason(8);
 152 
 153     /**
 154      * The job is in the PROCESSING state, but more specifically, the printer
 155      * ia interpreting the document data.
 156      */
 157     public static final JobStateReason
 158         JOB_INTERPRETING = new JobStateReason(9);
 159 
 160     /**
 161      * The job is in the PROCESSING state, but more specifically, the printer
 162      * has queued the document data.
 163      */
 164     public static final JobStateReason JOB_QUEUED = new JobStateReason(10);
 165 
 166     /**
 167      * The job is in the PROCESSING state, but more specifically, the printer
 168      * is interpreting document data and producing another electronic
 169      * representation.
 170      */
 171     public static final JobStateReason
 172         JOB_TRANSFORMING = new JobStateReason(11);
 173 
 174     /**
 175      * The job is in the PENDING_HELD, PENDING, or PROCESSING state, but more
 176      * specifically, the printer has completed enough processing of the document
 177      * to be able to start marking and the job is waiting for the marker.
 178      * Systems that require human intervention to release jobs put the job into
 179      * the PENDING_HELD job state. Systems that automatically select a job to
 180      * use the marker put the job into the PENDING job state or keep the job
 181      * in the PROCESSING job state while waiting for the marker, depending on
 182      * implementation. All implementations put the job into (or back into) the
 183      * PROCESSING state when marking does begin.
 184      */
 185     public static final JobStateReason
 186         JOB_QUEUED_FOR_MARKER = new JobStateReason(12);
 187 
 188     /**
 189      * The output device is marking media. This value is useful for printers
 190      * which spend a great deal of time processing (1) when no marking is
 191      * happening and then want to show that marking is now happening or (2) when
 192      * the job is in the process of being canceled or aborted while the job
 193      * remains in the PROCESSING state, but the marking has not yet stopped so
 194      * that impression or sheet counts are still increasing for the job.
 195      */
 196     public static final JobStateReason
 197         JOB_PRINTING = new JobStateReason(13);
 198 
 199     /**
 200      * The job was canceled by the owner of the job, i.e., by a user whose
 201      * authenticated identity is the same as the value of the originating user
 202      * that created the Print Job, or by some other authorized end-user, such as
 203      * a member of the job owner's security group. This value should be
 204      * supported.
 205      */
 206     public static final JobStateReason
 207         JOB_CANCELED_BY_USER = new JobStateReason(14);
 208 
 209     /**
 210      * The job was canceled by the operator, i.e., by a user who has been
 211      * authenticated as having operator privileges (whether local or remote). If
 212      * the security policy is to allow anyone to cancel anyone's job, then this
 213      * value may be used when the job is canceled by someone other than the
 214      * owner of the job. For such a security policy, in effect, everyone is an
 215      * operator as far as canceling jobs is concerned. This value should be
 216      * supported if the implementation permits canceling by someone other than
 217      * the owner of the job.
 218      */
 219     public static final JobStateReason
 220         JOB_CANCELED_BY_OPERATOR = new JobStateReason(15);
 221 
 222     /**
 223      * The job was canceled by an unidentified local user, i.e., a user at a
 224      * console at the device. This value should be supported if the
 225      * implementation supports canceling jobs at the console.
 226      */
 227     public static final JobStateReason
 228         JOB_CANCELED_AT_DEVICE = new JobStateReason(16);
 229 
 230     /**
 231      * The job was aborted by the system. Either the job (1) is in the process
 232      * of being aborted, (2) has been aborted by the system and placed in the
 233      * ABORTED state, or (3) has been aborted by the system and placed in the
 234      * PENDING_HELD state, so that a user or operator can manually try the job
 235      * again. This value should be supported.
 236      */
 237     public static final JobStateReason
 238         ABORTED_BY_SYSTEM = new JobStateReason(17);
 239 
 240     /**
 241      * The job was aborted by the system because the printer determined while
 242      * attempting to decompress the document's data that the compression is
 243      * actually not among those supported by the printer. This value must be
 244      * supported, since {@link Compression Compression} is a required doc
 245      * description attribute.
 246      */
 247     public static final JobStateReason
 248         UNSUPPORTED_COMPRESSION = new JobStateReason(18);
 249 
 250     /**
 251      * The job was aborted by the system because the printer encountered an
 252      * error in the document data while decompressing it. If the printer posts
 253      * this reason, the document data has already passed any tests that would
 254      * have led to the UNSUPPORTED_COMPRESSION job state reason.
 255      */
 256     public static final JobStateReason
 257         COMPRESSION_ERROR = new JobStateReason(19);
 258 
 259     /**
 260      * The job was aborted by the system because the document data's document
 261      * format (doc flavor) is not among those supported by the printer. If the
 262      * client specifies a doc flavor with a MIME type of
 263      * <CODE>"application/octet-stream"</CODE>, the printer may abort the job if
 264      * the printer cannot determine the document data's actual format through
 265      * auto-sensing (even if the printer supports the document format if
 266      * specified explicitly). This value must be supported, since a doc flavor
 267      * is required to be specified for each doc.
 268      */
 269     public static final JobStateReason
 270         UNSUPPORTED_DOCUMENT_FORMAT = new JobStateReason(20);
 271 
 272     /**
 273      * The job was aborted by the system because the printer encountered an
 274      * error in the document data while processing it. If the printer posts this
 275      * reason, the document data has already passed any tests that would have
 276      * led to the UNSUPPORTED_DOCUMENT_FORMAT job state reason.
 277      */
 278     public static final JobStateReason
 279         DOCUMENT_FORMAT_ERROR = new JobStateReason(21);
 280 
 281     /**
 282      * The requester has canceled the job or the printer has aborted the job,
 283      * but the printer is still performing some actions on the job until a
 284      * specified stop point occurs or job termination/cleanup is completed.
 285      * <P>
 286      * If the implementation requires some measurable time to cancel the job in
 287      * the PROCESSING or PROCESSING_STOPPED job states, the printer must use
 288      * this reason to indicate that the printer is still performing some actions
 289      * on the job while the job remains in the PROCESSING or PROCESSING_STOPPED
 290      * state. After all the job's job description attributes have stopped
 291      * incrementing, the printer moves the job from the PROCESSING state to the
 292      * CANCELED or ABORTED job states.
 293      */
 294     public static final JobStateReason
 295         PROCESSING_TO_STOP_POINT = new JobStateReason(22);
 296 
 297     /**
 298      * The printer is off-line and accepting no jobs. All PENDING jobs are put
 299      * into the PENDING_HELD state. This situation could be true if the
 300      * service's or document transform's input is impaired or broken.
 301      */
 302     public static final JobStateReason
 303         SERVICE_OFF_LINE = new JobStateReason(23);
 304 
 305     /**
 306      * The job completed successfully. This value should be supported.
 307      */
 308     public static final JobStateReason
 309         JOB_COMPLETED_SUCCESSFULLY = new JobStateReason(24);
 310 
 311     /**
 312      * The job completed with warnings. This value should be supported if the
 313      * implementation detects warnings.
 314      */
 315     public static final JobStateReason
 316         JOB_COMPLETED_WITH_WARNINGS = new JobStateReason(25);
 317 
 318     /**
 319      * The job completed with errors (and possibly warnings too). This value
 320      * should be supported if the implementation detects errors.
 321      */
 322     public static final JobStateReason
 323         JOB_COMPLETED_WITH_ERRORS = new JobStateReason(26);
 324 
 325     /**
 326      * This job is retained and is currently able to be restarted. If
 327      * JOB_RESTARTABLE is contained in the job's {@link JobStateReasons
 328      * JobStateReasons} attribute, then the printer must accept a request to
 329      * restart that job. This value should be supported if restarting jobs is
 330      * supported. <I>[The capability for restarting jobs is not in the Java
 331      * Print Service API at present.]</I>
 332      */
 333     public static final JobStateReason
 334         JOB_RESTARTABLE = new JobStateReason(27);
 335 
 336     /**
 337      * The job has been forwarded to a device or print system that is unable to
 338      * send back status. The printer sets the job's {@link JobState JobState}
 339      * attribute to COMPLETED and adds the QUEUED_IN_DEVICE reason to the job's
 340      * {@link JobStateReasons JobStateReasons} attribute to indicate that the
 341      * printer has no additional information about the job and never will have
 342      * any better information.
 343      */
 344     public static final JobStateReason
 345         QUEUED_IN_DEVICE = new JobStateReason(28);
 346 
 347     /**
 348      * Construct a new job state reason enumeration value with the given
 349      * integer  value.
 350      *
 351      * @param  value  Integer value.
 352      */
 353     protected JobStateReason(int value) {
 354         super (value);
 355     }
 356 
 357     private static final String[] myStringTable = {
 358         "job-incoming",
 359         "job-data-insufficient",
 360         "document-access-error",
 361         "submission-interrupted",
 362         "job-outgoing",
 363         "job-hold-until-specified",
 364         "resources-are-not-ready",
 365         "printer-stopped-partly",
 366         "printer-stopped",
 367         "job-interpreting",
 368         "job-queued",
 369         "job-transforming",
 370         "job-queued-for-marker",
 371         "job-printing",
 372         "job-canceled-by-user",
 373         "job-canceled-by-operator",
 374         "job-canceled-at-device",
 375         "aborted-by-system",
 376         "unsupported-compression",
 377         "compression-error",
 378         "unsupported-document-format",
 379         "document-format-error",
 380         "processing-to-stop-point",
 381         "service-off-line",
 382         "job-completed-successfully",
 383         "job-completed-with-warnings",
 384         "job-completed-with-errors",
 385         "job-restartable",
 386         "queued-in-device"};
 387 
 388     private static final JobStateReason[] myEnumValueTable = {
 389         JOB_INCOMING,
 390         JOB_DATA_INSUFFICIENT,
 391         DOCUMENT_ACCESS_ERROR,
 392         SUBMISSION_INTERRUPTED,
 393         JOB_OUTGOING,
 394         JOB_HOLD_UNTIL_SPECIFIED,
 395         RESOURCES_ARE_NOT_READY,
 396         PRINTER_STOPPED_PARTLY,
 397         PRINTER_STOPPED,
 398         JOB_INTERPRETING,
 399         JOB_QUEUED,
 400         JOB_TRANSFORMING,
 401         JOB_QUEUED_FOR_MARKER,
 402         JOB_PRINTING,
 403         JOB_CANCELED_BY_USER,
 404         JOB_CANCELED_BY_OPERATOR,
 405         JOB_CANCELED_AT_DEVICE,
 406         ABORTED_BY_SYSTEM,
 407         UNSUPPORTED_COMPRESSION,
 408         COMPRESSION_ERROR,
 409         UNSUPPORTED_DOCUMENT_FORMAT,
 410         DOCUMENT_FORMAT_ERROR,
 411         PROCESSING_TO_STOP_POINT,
 412         SERVICE_OFF_LINE,
 413         JOB_COMPLETED_SUCCESSFULLY,
 414         JOB_COMPLETED_WITH_WARNINGS,
 415         JOB_COMPLETED_WITH_ERRORS,
 416         JOB_RESTARTABLE,
 417         QUEUED_IN_DEVICE};
 418 
 419     /**
 420      * Returns the string table for class JobStateReason.
 421      */
 422     protected String[] getStringTable() {
 423         return (String[])myStringTable.clone();
 424     }
 425 
 426     /**
 427      * Returns the enumeration value table for class JobStateReason.
 428      */
 429     protected EnumSyntax[] getEnumValueTable() {
 430         return (EnumSyntax[])myEnumValueTable.clone();
 431     }
 432 
 433 
 434     /**
 435      * Get the printing attribute class which is to be used as the "category"
 436      * for this printing attribute value.
 437      * <P>
 438      * For class JobStateReason and any vendor-defined subclasses, the
 439      * category  is class JobStateReason itself.
 440      *
 441      * @return  Printing attribute class (category), an instance of class
 442      *          {@link java.lang.Class java.lang.Class}.
 443      */
 444     public final Class<? extends Attribute> getCategory() {
 445         return JobStateReason.class;
 446     }
 447 
 448     /**
 449      * Get the name of the category of which this attribute value is an
 450      * instance.
 451      * <P>
 452      * For class JobStateReason and any vendor-defined subclasses, the
 453      * category name is <CODE>"job-state-reason"</CODE>.
 454      *
 455      * @return  Attribute category name.
 456      */
 457     public final String getName() {
 458         return "job-state-reason";
 459     }
 460 
 461 }