1 /*
   2  * Copyright (c) 2000, 2019, 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 
  26 package javax.print.attribute.standard;
  27 
  28 import javax.print.attribute.Attribute;
  29 import javax.print.attribute.DocAttribute;
  30 import javax.print.attribute.EnumSyntax;
  31 import javax.print.attribute.PrintJobAttribute;
  32 import javax.print.attribute.PrintRequestAttribute;
  33 
  34 /**
  35  * Class {@code Finishings} is a printing attribute class, an enumeration, that
  36  * identifies whether the printer applies a finishing operation of some kind of
  37  * binding to each copy of each printed document in the job. For multidoc print
  38  * jobs (jobs with multiple documents), the
  39  * {@link MultipleDocumentHandling MultipleDocumentHandling} attribute
  40  * determines what constitutes a "copy" for purposes of finishing.
  41  * <p>
  42  * Standard Finishings values are:
  43  * <ul>
  44  *   <li>{@link #NONE NONE}
  45  *   <li>{@link #STAPLE STAPLE}
  46  *   <li>{@link #EDGE_STITCH EDGE_STITCH}
  47  *   <li>{@link #BIND BIND}
  48  *   <li>{@link #SADDLE_STITCH SADDLE_STITCH}
  49  *   <li>{@link #COVER COVER}
  50  * </ul>
  51  * <p>
  52  * The following {@code Finishings} values are more specific; they indicate a
  53  * corner or an edge as if the document were a portrait document:
  54  * <ul>
  55  *   <li>{@link #STAPLE_TOP_LEFT STAPLE_TOP_LEFT}
  56  *   <li>{@link #EDGE_STITCH_LEFT EDGE_STITCH_LEFT}
  57  *   <li>{@link #STAPLE_DUAL_LEFT STAPLE_DUAL_LEFT}
  58  *   <li>{@link #STAPLE_BOTTOM_LEFT STAPLE_BOTTOM_LEFT}
  59  *   <li>{@link #EDGE_STITCH_TOP EDGE_STITCH_TOP}
  60  *   <li>{@link #STAPLE_DUAL_TOP STAPLE_DUAL_TOP}
  61  *   <li>{@link #STAPLE_TOP_RIGHT STAPLE_TOP_RIGHT}
  62  *   <li>{@link #EDGE_STITCH_RIGHT EDGE_STITCH_RIGHT}
  63  *   <li>{@link #STAPLE_DUAL_RIGHT STAPLE_DUAL_RIGHT}
  64  *   <li>{@link #STAPLE_BOTTOM_RIGHT STAPLE_BOTTOM_RIGHT}
  65  *   <li>{@link #EDGE_STITCH_BOTTOM EDGE_STITCH_BOTTOM}
  66  *   <li>{@link #STAPLE_DUAL_BOTTOM STAPLE_DUAL_BOTTOM}
  67  * </ul>
  68  * <p>
  69  * The STAPLE_<i>XXX</i> values are specified with respect to the document as if
  70  * the document were a portrait document. If the document is actually a
  71  * landscape or a reverse-landscape document, the client supplies the
  72  * appropriate transformed value. For example, to position a staple in the upper
  73  * left hand corner of a landscape document when held for reading, the client
  74  * supplies the {@code STAPLE_BOTTOM_LEFT} value (since landscape is defined as
  75  * a +90 degree rotation from portrait, i.e., anti-clockwise). On the other
  76  * hand, to position a staple in the upper left hand corner of a
  77  * reverse-landscape document when held for reading, the client supplies the
  78  * {@code STAPLE_TOP_RIGHT} value (since reverse-landscape is defined as a -90
  79  * degree rotation from portrait, i.e., clockwise).
  80  * <p>
  81  * The angle (vertical, horizontal, angled) of each staple with respect to the
  82  * document depends on the implementation which may in turn depend on the value
  83  * of the attribute.
  84  * <p>
  85  * The effect of a {@code Finishings} attribute on a multidoc print job (a job
  86  * with multiple documents) depends on whether all the docs have the same
  87  * binding specified or whether different docs have different bindings
  88  * specified, and on the (perhaps defaulted) value of the
  89  * {@link MultipleDocumentHandling MultipleDocumentHandling} attribute.
  90  * <ul>
  91  *   <li>If all the docs have the same binding specified, then any value of
  92  *   {@link MultipleDocumentHandling MultipleDocumentHandling} makes sense, and
  93  *   the printer's processing depends on the
  94  *   {@link MultipleDocumentHandling MultipleDocumentHandling} value:
  95  *   <ul>
  96  *     <li>{@code SINGLE_DOCUMENT} -- All the input docs will be bound together
  97  *     as one output document with the specified binding.
  98  *     <li>{@code SINGLE_DOCUMENT_NEW_SHEET} -- All the input docs will be bound
  99  *     together as one output document with the specified binding, and the first
 100  *     impression of each input doc will always start on a new media sheet.
 101  *     <li>{@code SEPARATE_DOCUMENTS_UNCOLLATED_COPIES} -- Each input doc will
 102  *     be bound separately with the specified binding.
 103  *     <li>{@code SEPARATE_DOCUMENTS_COLLATED_COPIES} -- Each input doc will be
 104  *     bound separately with the specified binding.
 105  *   </ul>
 106  *   <li>If different docs have different bindings specified, then only two
 107  *   values of {@link MultipleDocumentHandling MultipleDocumentHandling} make
 108  *   sense, and the printer reports an error when the job is submitted if any
 109  *   other value is specified:
 110  *   <ul>
 111  *     <li>{@code SEPARATE_DOCUMENTS_UNCOLLATED_COPIES} -- Each input doc will
 112  *     be bound separately with its own specified binding.
 113  *     <li>{@code SEPARATE_DOCUMENTS_COLLATED_COPIES} -- Each input doc will be
 114  *     bound separately with its own specified binding.
 115  *   </ul>
 116  * </ul>
 117  * <p>
 118  * <b>IPP Compatibility:</b> Class Finishings encapsulates some of the IPP enum
 119  * values that can be included in an IPP "finishings" attribute, which is a set
 120  * of enums. The category name returned by {@code getName()} is the IPP
 121  * attribute name. The enumeration's integer value is the IPP enum value. The
 122  * {@code toString()} method returns the IPP string representation of the
 123  * attribute value. In IPP Finishings is a multi-value attribute, this API
 124  * currently allows only one binding to be specified.
 125  *
 126  * @author Alan Kaminsky
 127  */
 128 public class Finishings extends EnumSyntax
 129     implements DocAttribute, PrintRequestAttribute, PrintJobAttribute {
 130 
 131     /**
 132      * Use serialVersionUID from JDK 1.4 for interoperability.
 133      */
 134     private static final long serialVersionUID = -627840419548391754L;
 135 
 136     /**
 137      * Perform no binding.
 138      */
 139     public static final Finishings NONE = new Finishings(3);
 140 
 141     /**
 142      * Bind the document(s) with one or more staples. The exact number and
 143      * placement of the staples is site-defined.
 144      */
 145     public static final Finishings STAPLE = new Finishings(4);
 146 
 147     /**
 148      * This value is specified when it is desired to select a non-printed (or
 149      * pre-printed) cover for the document. This does not supplant the
 150      * specification of a printed cover (on cover stock medium) by the document
 151      * itself.
 152      */
 153     public static final Finishings COVER = new Finishings(6);
 154 
 155     /**
 156      * This value indicates that a binding is to be applied to the document; the
 157      * type and placement of the binding is site-defined.
 158      */
 159     public static final Finishings BIND = new Finishings(7);
 160 
 161     /**
 162      * Bind the document(s) with one or more staples (wire stitches) along the
 163      * middle fold. The exact number and placement of the staples and the middle
 164      * fold is implementation- and/or site-defined.
 165      */
 166     public static final Finishings SADDLE_STITCH =
 167         new Finishings(8);
 168 
 169     /**
 170      * Bind the document(s) with one or more staples (wire stitches) along one
 171      * edge. The exact number and placement of the staples is implementation-
 172      * and/or site- defined.
 173      */
 174     public static final Finishings EDGE_STITCH =
 175         new Finishings(9);
 176 
 177     /**
 178      * Bind the document(s) with one or more staples in the top left corner.
 179      */
 180     public static final Finishings STAPLE_TOP_LEFT =
 181         new Finishings(20);
 182 
 183     /**
 184      * Bind the document(s) with one or more staples in the bottom left corner.
 185      */
 186     public static final Finishings STAPLE_BOTTOM_LEFT =
 187         new Finishings(21);
 188 
 189     /**
 190      * Bind the document(s) with one or more staples in the top right corner.
 191      */
 192     public static final Finishings STAPLE_TOP_RIGHT =
 193         new Finishings(22);
 194 
 195     /**
 196      * Bind the document(s) with one or more staples in the bottom right corner.
 197      */
 198     public static final Finishings STAPLE_BOTTOM_RIGHT =
 199         new Finishings(23);
 200 
 201     /**
 202      * Bind the document(s) with one or more staples (wire stitches) along the
 203      * left edge. The exact number and placement of the staples is
 204      * implementation- and/or site-defined.
 205      */
 206     public static final Finishings EDGE_STITCH_LEFT =
 207         new Finishings(24);
 208 
 209     /**
 210      * Bind the document(s) with one or more staples (wire stitches) along the
 211      * top edge. The exact number and placement of the staples is
 212      * implementation- and/or site-defined.
 213      */
 214     public static final Finishings EDGE_STITCH_TOP =
 215         new Finishings(25);
 216 
 217     /**
 218      * Bind the document(s) with one or more staples (wire stitches) along the
 219      * right edge. The exact number and placement of the staples is
 220      * implementation- and/or site-defined.
 221      */
 222     public static final Finishings EDGE_STITCH_RIGHT =
 223         new Finishings(26);
 224 
 225     /**
 226      * Bind the document(s) with one or more staples (wire stitches) along the
 227      * bottom edge. The exact number and placement of the staples is
 228      * implementation- and/or site-defined.
 229      */
 230     public static final Finishings EDGE_STITCH_BOTTOM =
 231         new Finishings(27);
 232 
 233     /**
 234      * Bind the document(s) with two staples (wire stitches) along the left edge
 235      * assuming a portrait document (see above).
 236      */
 237     public static final Finishings STAPLE_DUAL_LEFT =
 238         new Finishings(28);
 239 
 240     /**
 241      * Bind the document(s) with two staples (wire stitches) along the top edge
 242      * assuming a portrait document (see above).
 243      */
 244     public static final Finishings STAPLE_DUAL_TOP =
 245         new Finishings(29);
 246 
 247     /**
 248      * Bind the document(s) with two staples (wire stitches) along the right
 249      * edge assuming a portrait document (see above).
 250      */
 251     public static final Finishings STAPLE_DUAL_RIGHT =
 252         new Finishings(30);
 253 
 254     /**
 255      * Bind the document(s) with two staples (wire stitches) along the bottom
 256      * edge assuming a portrait document (see above).
 257      */
 258     public static final Finishings STAPLE_DUAL_BOTTOM =
 259         new Finishings(31);
 260 
 261     /**
 262      * Construct a new finishings binding enumeration value with the given
 263      * integer value.
 264      *
 265      * @param  value Integer value
 266      */
 267     protected Finishings(int value) {
 268         super(value);
 269     }
 270 
 271     /**
 272      * The string table for class {@code Finishings}.
 273      */
 274     private static final String[] myStringTable =
 275                 {"none",
 276                  "staple",
 277                  null,
 278                  "cover",
 279                  "bind",
 280                  "saddle-stitch",
 281                  "edge-stitch",
 282                  null, // The next ten enum values are reserved.
 283                  null,
 284                  null,
 285                  null,
 286                  null,
 287                  null,
 288                  null,
 289                  null,
 290                  null,
 291                  null,
 292                  "staple-top-left",
 293                  "staple-bottom-left",
 294                  "staple-top-right",
 295                  "staple-bottom-right",
 296                  "edge-stitch-left",
 297                  "edge-stitch-top",
 298                  "edge-stitch-right",
 299                  "edge-stitch-bottom",
 300                  "staple-dual-left",
 301                  "staple-dual-top",
 302                  "staple-dual-right",
 303                  "staple-dual-bottom"
 304                 };
 305 
 306     /**
 307      * The enumeration value table for class {@code Finishings}.
 308      */
 309     private static final Finishings[] myEnumValueTable =
 310                 {NONE,
 311                  STAPLE,
 312                  null,
 313                  COVER,
 314                  BIND,
 315                  SADDLE_STITCH,
 316                  EDGE_STITCH,
 317                  null, // The next ten enum values are reserved.
 318                  null,
 319                  null,
 320                  null,
 321                  null,
 322                  null,
 323                  null,
 324                  null,
 325                  null,
 326                  null,
 327                  STAPLE_TOP_LEFT,
 328                  STAPLE_BOTTOM_LEFT,
 329                  STAPLE_TOP_RIGHT,
 330                  STAPLE_BOTTOM_RIGHT,
 331                  EDGE_STITCH_LEFT,
 332                  EDGE_STITCH_TOP,
 333                  EDGE_STITCH_RIGHT,
 334                  EDGE_STITCH_BOTTOM,
 335                  STAPLE_DUAL_LEFT,
 336                  STAPLE_DUAL_TOP,
 337                  STAPLE_DUAL_RIGHT,
 338                  STAPLE_DUAL_BOTTOM
 339                 };
 340 
 341     /**
 342      * Returns the string table for class {@code Finishings}.
 343      */
 344     protected String[] getStringTable() {
 345         return myStringTable.clone();
 346     }
 347 
 348     /**
 349      * Returns the enumeration value table for class {@code Finishings}.
 350      */
 351     protected EnumSyntax[] getEnumValueTable() {
 352         return (EnumSyntax[])myEnumValueTable.clone();
 353     }
 354 
 355     /**
 356      * Returns the lowest integer value used by class {@code Finishings}.
 357      */
 358     protected int getOffset() {
 359         return 3;
 360     }
 361 
 362     /**
 363      * Get the printing attribute class which is to be used as the "category"
 364      * for this printing attribute value.
 365      * <p>
 366      * For class {@code Finishings} and any vendor-defined subclasses, the
 367      * category is class {@code Finishings} itself.
 368      *
 369      * @return printing attribute class (category), an instance of class
 370      *         {@link Class java.lang.Class}
 371      */
 372     public final Class<? extends Attribute> getCategory() {
 373         return Finishings.class;
 374     }
 375 
 376     /**
 377      * Get the name of the category of which this attribute value is an
 378      * instance.
 379      * <p>
 380      * For class {@code Finishings} and any vendor-defined subclasses, the
 381      * category name is {@code "finishings"}.
 382      *
 383      * @return attribute category name
 384      */
 385     public final String getName() {
 386         return "finishings";
 387     }
 388 }