1 /*
   2  * Copyright (c) 2000, 2013, 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.Attribute;
  28 import javax.print.attribute.IntegerSyntax;
  29 import javax.print.attribute.PrintRequestAttribute;
  30 import javax.print.attribute.PrintJobAttribute;
  31 
  32 /**
  33  * Class JobKOctets is an integer valued printing attribute class that specifies
  34  * the total size of the document(s) in K octets, i.e., in units of 1024 octets
  35  * requested to be processed in the job. The value must be rounded up, so that a
  36  * job between 1 and 1024 octets must be indicated as being 1K octets, 1025 to
  37  * 2048 must be 2K octets, etc. For a multidoc print job (a job with multiple
  38  * documents), the JobKOctets value is computed by adding up the individual
  39  * documents' sizes in octets, then rounding up to the next K octets value.
  40  * <P>
  41  * The JobKOctets attribute describes the size of the job. This attribute is not
  42  * intended to be a counter; it is intended to be useful routing and scheduling
  43  * information if known. The printer may try to compute the JobKOctets
  44  * attribute's value if it is not supplied in the Print Request. Even if the
  45  * client does supply a value for the JobKOctets attribute in the Print Request,
  46  * the printer may choose to change the value if the printer is able to compute
  47  * a value which is more accurate than the client supplied value. The printer
  48  * may be able to determine the correct value for the JobKOctets attribute
  49  * either right at job submission time or at any later point in time.
  50  * <P>
  51  * The JobKOctets value must not include the multiplicative factors contributed
  52  * by the number of copies specified by the {@link Copies Copies} attribute,
  53  * independent of whether the device can process multiple copies without making
  54  * multiple passes over the job or document data and independent of whether the
  55  * output is collated or not. Thus the value is independent of the
  56  * implementation and indicates the size of the document(s) measured in K octets
  57  * independent of the number of copies.
  58  * <P>
  59  * The JobKOctets value must also not include the multiplicative factor due to a
  60  * copies instruction embedded in the document data. If the document data
  61  * actually includes replications of the document data, this value will include
  62  * such replication. In other words, this value is always the size of the source
  63  * document data, rather than a measure of the hardcopy output to be produced.
  64  * <P>
  65  * The size of a doc is computed based on the print data representation class as
  66  * specified by the doc's {@link javax.print.DocFlavor DocFlavor}, as
  67  * shown in the table below.
  68  *
  69  * <TABLE BORDER=1 CELLPADDING=2 CELLSPACING=1 SUMMARY="Table showing computation of doc sizes">
  70  * <TR>
  71  * <TH>Representation Class</TH>
  72  * <TH>Document Size</TH>
  73  * </TR>
  74  * <TR>
  75  * <TD>byte[]</TD>
  76  * <TD>Length of the byte array</TD>
  77  * </TR>
  78  * <TR>
  79  * <TD>java.io.InputStream</TD>
  80  * <TD>Number of bytes read from the stream</TD>
  81  * </TR>
  82  * <TR>
  83  * <TD>char[]</TD>
  84  * <TD>Length of the character array x 2</TD>
  85  * </TR>
  86  * <TR>
  87  * <TD>java.lang.String</TD>
  88  * <TD>Length of the string x 2</TD>
  89  * </TR>
  90  * <TR>
  91  * <TD>java.io.Reader</TD>
  92  * <TD>Number of characters read from the stream x 2</TD>
  93  * </TR>
  94  * <TR>
  95  * <TD>java.net.URL</TD>
  96  * <TD>Number of bytes read from the file at the given URL address</TD>
  97  * </TR>
  98  * <TR>
  99  * <TD>java.awt.image.renderable.RenderableImage</TD>
 100  * <TD>Implementation dependent*</TD>
 101  * </TR>
 102  * <TR>
 103  * <TD>java.awt.print.Printable</TD>
 104  * <TD>Implementation dependent*</TD>
 105  * </TR>
 106  * <TR>
 107  * <TD>java.awt.print.Pageable</TD>
 108  * <TD>Implementation dependent*</TD>
 109  * </TR>
 110  * </TABLE>
 111  * <P>
 112  * * In these cases the Print Service itself generates the print data sent
 113  * to the printer. If the Print Service supports the JobKOctets attribute, for
 114  * these cases the Print Service itself must calculate the size of the print
 115  * data, replacing any JobKOctets value the client specified.
 116  * <P>
 117  * <B>IPP Compatibility:</B> The integer value gives the IPP integer value. The
 118  * category name returned by <CODE>getName()</CODE> gives the IPP attribute
 119  * name.
 120  *
 121  * @see JobKOctetsSupported
 122  * @see JobKOctetsProcessed
 123  * @see JobImpressions
 124  * @see JobMediaSheets
 125  *
 126  * @author  Alan Kaminsky
 127  */
 128 public final class JobKOctets   extends IntegerSyntax
 129         implements PrintRequestAttribute, PrintJobAttribute {
 130 
 131     private static final long serialVersionUID = -8959710146498202869L;
 132 
 133     /**
 134      * Construct a new job K octets attribute with the given integer value.
 135      *
 136      * @param  value  Integer value.
 137      *
 138      * @exception  IllegalArgumentException
 139      *  (Unchecked exception) Thrown if <CODE>value</CODE> is less than 0.
 140      */
 141     public JobKOctets(int value) {
 142         super (value, 0, Integer.MAX_VALUE);
 143     }
 144 
 145     /**
 146      * Returns whether this job K octets attribute is equivalent to the passed
 147      * in object. To be equivalent, all of the following conditions must be
 148      * true:
 149      * <OL TYPE=1>
 150      * <LI>
 151      * <CODE>object</CODE> is not null.
 152      * <LI>
 153      * <CODE>object</CODE> is an instance of class JobKOctets.
 154      * <LI>
 155      * This job K octets attribute's value and <CODE>object</CODE>'s value
 156      * are equal.
 157      * </OL>
 158      *
 159      * @param  object  Object to compare to.
 160      *
 161      * @return  True if <CODE>object</CODE> is equivalent to this job K
 162      *          octets attribute, false otherwise.
 163      */
 164     public boolean equals(Object object) {
 165         return super.equals(object) && object instanceof JobKOctets;
 166     }
 167 
 168     /**
 169      * Get the printing attribute class which is to be used as the "category"
 170      * for this printing attribute value.
 171      * <P>
 172      * For class JobKOctets, the category is class JobKOctets itself.
 173      *
 174      * @return  Printing attribute class (category), an instance of class
 175      *          {@link java.lang.Class java.lang.Class}.
 176      */
 177     public final Class<? extends Attribute> getCategory() {
 178         return JobKOctets.class;
 179     }
 180 
 181     /**
 182      * Get the name of the category of which this attribute value is an
 183      * instance.
 184      * <P>
 185      * For class JobKOctets, the category name is <CODE>"job-k-octets"</CODE>.
 186      *
 187      * @return  Attribute category name.
 188      */
 189     public final String getName() {
 190         return "job-k-octets";
 191     }
 192 
 193 }