1 /*
   2  * Copyright (c) 1997, 2014, 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 java.awt.print;
  27 
  28 import java.awt.AWTError;
  29 import java.awt.HeadlessException;
  30 import java.util.Enumeration;
  31 
  32 import javax.print.DocFlavor;
  33 import javax.print.PrintService;
  34 import javax.print.PrintServiceLookup;
  35 import javax.print.StreamPrintServiceFactory;
  36 import javax.print.attribute.PrintRequestAttributeSet;
  37 import javax.print.attribute.standard.Media;
  38 import javax.print.attribute.standard.MediaPrintableArea;
  39 import javax.print.attribute.standard.MediaSize;
  40 import javax.print.attribute.standard.MediaSizeName;
  41 import javax.print.attribute.standard.OrientationRequested;
  42 
  43 import sun.security.action.GetPropertyAction;
  44 
  45 /**
  46  * The <code>PrinterJob</code> class is the principal class that controls
  47  * printing. An application calls methods in this class to set up a job,
  48  * optionally to invoke a print dialog with the user, and then to print
  49  * the pages of the job.
  50  */
  51 public abstract class PrinterJob {
  52 
  53  /* Public Class Methods */
  54 
  55     /**
  56      * Creates and returns a <code>PrinterJob</code> which is initially
  57      * associated with the default printer.
  58      * If no printers are available on the system, a PrinterJob will still
  59      * be returned from this method, but <code>getPrintService()</code>
  60      * will return <code>null</code>, and calling
  61      * {@link #print() print} with this <code>PrinterJob</code> might
  62      * generate an exception.  Applications that need to determine if
  63      * there are suitable printers before creating a <code>PrinterJob</code>
  64      * should ensure that the array returned from
  65      * {@link #lookupPrintServices() lookupPrintServices} is not empty.
  66      * @return a new <code>PrinterJob</code>.
  67      *
  68      * @throws  SecurityException if a security manager exists and its
  69      *          {@link java.lang.SecurityManager#checkPrintJobAccess}
  70      *          method disallows this thread from creating a print job request
  71      */
  72     public static PrinterJob getPrinterJob() {
  73         SecurityManager security = System.getSecurityManager();
  74         if (security != null) {
  75             security.checkPrintJobAccess();
  76         }
  77         return java.security.AccessController.doPrivileged(
  78             new java.security.PrivilegedAction<PrinterJob>() {
  79             public PrinterJob run() {
  80                 String nm = System.getProperty("java.awt.printerjob", null);
  81                 try {
  82                     return (PrinterJob)Class.forName(nm).newInstance();
  83                 } catch (ClassNotFoundException e) {
  84                     throw new AWTError("PrinterJob not found: " + nm);
  85                 } catch (InstantiationException e) {
  86                  throw new AWTError("Could not instantiate PrinterJob: " + nm);
  87                 } catch (IllegalAccessException e) {
  88                     throw new AWTError("Could not access PrinterJob: " + nm);
  89                 }
  90             }
  91         });
  92     }
  93 
  94     /**
  95      * A convenience method which looks up 2D print services.
  96      * Services returned from this method may be installed on
  97      * <code>PrinterJob</code>s which support print services.
  98      * Calling this method is equivalent to calling
  99      * {@link javax.print.PrintServiceLookup#lookupPrintServices(
 100      * DocFlavor, AttributeSet)
 101      * PrintServiceLookup.lookupPrintServices()}
 102      * and specifying a Pageable DocFlavor.
 103      * @return a possibly empty array of 2D print services.
 104      * @since     1.4
 105      */
 106     public static PrintService[] lookupPrintServices() {
 107         return PrintServiceLookup.
 108             lookupPrintServices(DocFlavor.SERVICE_FORMATTED.PAGEABLE, null);
 109     }
 110 
 111 
 112     /**
 113      * A convenience method which locates factories for stream print
 114      * services which can image 2D graphics.
 115      * Sample usage :
 116      * <pre>{@code
 117      * FileOutputStream outstream;
 118      * StreamPrintService psPrinter;
 119      * String psMimeType = "application/postscript";
 120      * PrinterJob pj = PrinterJob.getPrinterJob();
 121      *
 122      * StreamPrintServiceFactory[] factories =
 123      *     PrinterJob.lookupStreamPrintServices(psMimeType);
 124      * if (factories.length > 0) {
 125      *     try {
 126      *         outstream = new File("out.ps");
 127      *         psPrinter =  factories[0].getPrintService(outstream);
 128      *         // psPrinter can now be set as the service on a PrinterJob
 129      *         pj.setPrintService(psPrinter)
 130      *     } catch (Exception e) {
 131      *         e.printStackTrace();
 132      *     }
 133      * }
 134      * }</pre>
 135      * Services returned from this method may be installed on
 136      * <code>PrinterJob</code> instances which support print services.
 137      * Calling this method is equivalent to calling
 138      * {@link javax.print.StreamPrintServiceFactory#lookupStreamPrintServiceFactories(DocFlavor, String)
 139      * StreamPrintServiceFactory.lookupStreamPrintServiceFactories()
 140      * } and specifying a Pageable DocFlavor.
 141      *
 142      * @param mimeType the required output format, or null to mean any format.
 143      * @return a possibly empty array of 2D stream print service factories.
 144      * @since     1.4
 145      */
 146     public static StreamPrintServiceFactory[]
 147         lookupStreamPrintServices(String mimeType) {
 148         return StreamPrintServiceFactory.lookupStreamPrintServiceFactories(
 149                                        DocFlavor.SERVICE_FORMATTED.PAGEABLE,
 150                                        mimeType);
 151     }
 152 
 153 
 154  /* Public Methods */
 155 
 156     /**
 157      * A <code>PrinterJob</code> object should be created using the
 158      * static {@link #getPrinterJob() getPrinterJob} method.
 159      */
 160     public PrinterJob() {
 161     }
 162 
 163     /**
 164      * Returns the service (printer) for this printer job.
 165      * Implementations of this class which do not support print services
 166      * may return null.  null will also be returned if no printers are
 167      * available.
 168      * @return the service for this printer job.
 169      * @see #setPrintService(PrintService)
 170      * @see #getPrinterJob()
 171      * @since     1.4
 172      */
 173     public PrintService getPrintService() {
 174         return null;
 175     }
 176 
 177     /**
 178      * Associate this PrinterJob with a new PrintService.
 179      * This method is overridden by subclasses which support
 180      * specifying a Print Service.
 181      *
 182      * Throws <code>PrinterException</code> if the specified service
 183      * cannot support the <code>Pageable</code> and
 184      * <code>Printable</code> interfaces necessary to support 2D printing.
 185      * @param service a print service that supports 2D printing
 186      * @exception PrinterException if the specified service does not support
 187      * 2D printing, or this PrinterJob class does not support
 188      * setting a 2D print service, or the specified service is
 189      * otherwise not a valid print service.
 190      * @see #getPrintService
 191      * @since     1.4
 192      */
 193     public void setPrintService(PrintService service)
 194         throws PrinterException {
 195             throw new PrinterException(
 196                          "Setting a service is not supported on this class");
 197     }
 198 
 199     /**
 200      * Calls <code>painter</code> to render the pages.  The pages in the
 201      * document to be printed by this
 202      * <code>PrinterJob</code> are rendered by the {@link Printable}
 203      * object, <code>painter</code>.  The {@link PageFormat} for each page
 204      * is the default page format.
 205      * @param painter the <code>Printable</code> that renders each page of
 206      * the document.
 207      */
 208     public abstract void setPrintable(Printable painter);
 209 
 210     /**
 211      * Calls <code>painter</code> to render the pages in the specified
 212      * <code>format</code>.  The pages in the document to be printed by
 213      * this <code>PrinterJob</code> are rendered by the
 214      * <code>Printable</code> object, <code>painter</code>. The
 215      * <code>PageFormat</code> of each page is <code>format</code>.
 216      * @param painter the <code>Printable</code> called to render
 217      *          each page of the document
 218      * @param format the size and orientation of each page to
 219      *                   be printed
 220      */
 221     public abstract void setPrintable(Printable painter, PageFormat format);
 222 
 223     /**
 224      * Queries <code>document</code> for the number of pages and
 225      * the <code>PageFormat</code> and <code>Printable</code> for each
 226      * page held in the <code>Pageable</code> instance,
 227      * <code>document</code>.
 228      * @param document the pages to be printed. It can not be
 229      * <code>null</code>.
 230      * @exception NullPointerException the <code>Pageable</code> passed in
 231      * was <code>null</code>.
 232      * @see PageFormat
 233      * @see Printable
 234      */
 235     public abstract void setPageable(Pageable document)
 236         throws NullPointerException;
 237 
 238     /**
 239      * Presents a dialog to the user for changing the properties of
 240      * the print job.
 241      * This method will display a native dialog if a native print
 242      * service is selected, and user choice of printers will be restricted
 243      * to these native print services.
 244      * To present the cross platform print dialog for all services,
 245      * including native ones instead use
 246      * <code>printDialog(PrintRequestAttributeSet)</code>.
 247      * <p>
 248      * PrinterJob implementations which can use PrintService's will update
 249      * the PrintService for this PrinterJob to reflect the new service
 250      * selected by the user.
 251      * @return <code>true</code> if the user does not cancel the dialog;
 252      * <code>false</code> otherwise.
 253      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
 254      * returns true.
 255      * @see java.awt.GraphicsEnvironment#isHeadless
 256      */
 257     public abstract boolean printDialog() throws HeadlessException;
 258 
 259     /**
 260      * A convenience method which displays a cross-platform print dialog
 261      * for all services which are capable of printing 2D graphics using the
 262      * <code>Pageable</code> interface. The selected printer when the
 263      * dialog is initially displayed will reflect the print service currently
 264      * attached to this print job.
 265      * If the user changes the print service, the PrinterJob will be
 266      * updated to reflect this, unless the user cancels the dialog.
 267      * As well as allowing the user to select the destination printer,
 268      * the user can also select values of various print request attributes.
 269      * <p>
 270      * The attributes parameter on input will reflect the applications
 271      * required initial selections in the user dialog. Attributes not
 272      * specified display using the default for the service. On return it
 273      * will reflect the user's choices. Selections may be updated by
 274      * the implementation to be consistent with the supported values
 275      * for the currently selected print service.
 276      * <p>
 277      * As the user scrolls to a new print service selection, the values
 278      * copied are based on the settings for the previous service, together
 279      * with any user changes. The values are not based on the original
 280      * settings supplied by the client.
 281      * <p>
 282      * With the exception of selected printer, the PrinterJob state is
 283      * not updated to reflect the user's changes.
 284      * For the selections to affect a printer job, the attributes must
 285      * be specified in the call to the
 286      * <code>print(PrintRequestAttributeSet)</code> method. If using
 287      * the Pageable interface, clients which intend to use media selected
 288      * by the user must create a PageFormat derived from the user's
 289      * selections.
 290      * If the user cancels the dialog, the attributes will not reflect
 291      * any changes made by the user.
 292      * @param attributes on input is application supplied attributes,
 293      * on output the contents are updated to reflect user choices.
 294      * This parameter may not be null.
 295      * @return <code>true</code> if the user does not cancel the dialog;
 296      * <code>false</code> otherwise.
 297      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
 298      * returns true.
 299      * @exception NullPointerException if <code>attributes</code> parameter
 300      * is null.
 301      * @see java.awt.GraphicsEnvironment#isHeadless
 302      * @since     1.4
 303      *
 304      */
 305     public boolean printDialog(PrintRequestAttributeSet attributes)
 306         throws HeadlessException {
 307 
 308         if (attributes == null) {
 309             throw new NullPointerException("attributes");
 310         }
 311         return printDialog();
 312     }
 313 
 314     /**
 315      * Displays a dialog that allows modification of a
 316      * <code>PageFormat</code> instance.
 317      * The <code>page</code> argument is used to initialize controls
 318      * in the page setup dialog.
 319      * If the user cancels the dialog then this method returns the
 320      * original <code>page</code> object unmodified.
 321      * If the user okays the dialog then this method returns a new
 322      * <code>PageFormat</code> object with the indicated changes.
 323      * In either case, the original <code>page</code> object is
 324      * not modified.
 325      * @param page the default <code>PageFormat</code> presented to the
 326      *                  user for modification
 327      * @return    the original <code>page</code> object if the dialog
 328      *            is cancelled; a new <code>PageFormat</code> object
 329      *            containing the format indicated by the user if the
 330      *            dialog is acknowledged.
 331      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
 332      * returns true.
 333      * @see java.awt.GraphicsEnvironment#isHeadless
 334      * @since     1.2
 335      */
 336     public abstract PageFormat pageDialog(PageFormat page)
 337         throws HeadlessException;
 338 
 339     /**
 340      * A convenience method which displays a cross-platform page setup dialog.
 341      * The choices available will reflect the print service currently
 342      * set on this PrinterJob.
 343      * <p>
 344      * The attributes parameter on input will reflect the client's
 345      * required initial selections in the user dialog. Attributes which are
 346      * not specified display using the default for the service. On return it
 347      * will reflect the user's choices. Selections may be updated by
 348      * the implementation to be consistent with the supported values
 349      * for the currently selected print service.
 350      * <p>
 351      * The return value will be a PageFormat equivalent to the
 352      * selections in the PrintRequestAttributeSet.
 353      * If the user cancels the dialog, the attributes will not reflect
 354      * any changes made by the user, and the return value will be null.
 355      * @param attributes on input is application supplied attributes,
 356      * on output the contents are updated to reflect user choices.
 357      * This parameter may not be null.
 358      * @return a page format if the user does not cancel the dialog;
 359      * <code>null</code> otherwise.
 360      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
 361      * returns true.
 362      * @exception NullPointerException if <code>attributes</code> parameter
 363      * is null.
 364      * @see java.awt.GraphicsEnvironment#isHeadless
 365      * @since     1.4
 366      *
 367      */
 368     public PageFormat pageDialog(PrintRequestAttributeSet attributes)
 369         throws HeadlessException {
 370 
 371         if (attributes == null) {
 372             throw new NullPointerException("attributes");
 373         }
 374         return pageDialog(defaultPage());
 375     }
 376 
 377     /**
 378      * Clones the <code>PageFormat</code> argument and alters the
 379      * clone to describe a default page size and orientation.
 380      * @param page the <code>PageFormat</code> to be cloned and altered
 381      * @return clone of <code>page</code>, altered to describe a default
 382      *                      <code>PageFormat</code>.
 383      */
 384     public abstract PageFormat defaultPage(PageFormat page);
 385 
 386     /**
 387      * Creates a new <code>PageFormat</code> instance and
 388      * sets it to a default size and orientation.
 389      * @return a <code>PageFormat</code> set to a default size and
 390      *          orientation.
 391      */
 392     public PageFormat defaultPage() {
 393         return defaultPage(new PageFormat());
 394     }
 395 
 396     /**
 397      * Calculates a <code>PageFormat</code> with values consistent with those
 398      * supported by the current <code>PrintService</code> for this job
 399      * (ie the value returned by <code>getPrintService()</code>) and media,
 400      * printable area and orientation contained in <code>attributes</code>.
 401      * <p>
 402      * Calling this method does not update the job.
 403      * It is useful for clients that have a set of attributes obtained from
 404      * <code>printDialog(PrintRequestAttributeSet attributes)</code>
 405      * and need a PageFormat to print a Pageable object.
 406      * @param attributes a set of printing attributes, for example obtained
 407      * from calling printDialog. If <code>attributes</code> is null a default
 408      * PageFormat is returned.
 409      * @return a <code>PageFormat</code> whose settings conform with
 410      * those of the current service and the specified attributes.
 411      * @since 1.6
 412      */
 413     public PageFormat getPageFormat(PrintRequestAttributeSet attributes) {
 414 
 415         PrintService service = getPrintService();
 416         PageFormat pf = defaultPage();
 417 
 418         if (service == null || attributes == null) {
 419             return pf;
 420         }
 421 
 422         Media media = (Media)attributes.get(Media.class);
 423         MediaPrintableArea mpa =
 424             (MediaPrintableArea)attributes.get(MediaPrintableArea.class);
 425         OrientationRequested orientReq =
 426            (OrientationRequested)attributes.get(OrientationRequested.class);
 427 
 428         if (media == null && mpa == null && orientReq == null) {
 429            return pf;
 430         }
 431         Paper paper = pf.getPaper();
 432 
 433         /* If there's a media but no media printable area, we can try
 434          * to retrieve the default value for mpa and use that.
 435          */
 436         if (mpa == null && media != null &&
 437             service.isAttributeCategorySupported(MediaPrintableArea.class)) {
 438             Object mpaVals =
 439                 service.getSupportedAttributeValues(MediaPrintableArea.class,
 440                                                     null, attributes);
 441             if (mpaVals instanceof MediaPrintableArea[] &&
 442                 ((MediaPrintableArea[])mpaVals).length > 0) {
 443                 mpa = ((MediaPrintableArea[])mpaVals)[0];
 444             }
 445         }
 446 
 447         if (media != null &&
 448             service.isAttributeValueSupported(media, null, attributes)) {
 449             if (media instanceof MediaSizeName) {
 450                 MediaSizeName msn = (MediaSizeName)media;
 451                 MediaSize msz = MediaSize.getMediaSizeForName(msn);
 452                 if (msz != null) {
 453                     double inch = 72.0;
 454                     double paperWid = msz.getX(MediaSize.INCH) * inch;
 455                     double paperHgt = msz.getY(MediaSize.INCH) * inch;
 456                     paper.setSize(paperWid, paperHgt);
 457                     if (mpa == null) {
 458                         paper.setImageableArea(inch, inch,
 459                                                paperWid-2*inch,
 460                                                paperHgt-2*inch);
 461                     }
 462                 }
 463             }
 464         }
 465 
 466         if (mpa != null &&
 467             service.isAttributeValueSupported(mpa, null, attributes)) {
 468             float [] printableArea =
 469                 mpa.getPrintableArea(MediaPrintableArea.INCH);
 470             for (int i=0; i < printableArea.length; i++) {
 471                 printableArea[i] = printableArea[i]*72.0f;
 472             }
 473             paper.setImageableArea(printableArea[0], printableArea[1],
 474                                    printableArea[2], printableArea[3]);
 475         }
 476 
 477         if (orientReq != null &&
 478             service.isAttributeValueSupported(orientReq, null, attributes)) {
 479             int orient;
 480             if (orientReq.equals(OrientationRequested.REVERSE_LANDSCAPE)) {
 481                 orient = PageFormat.REVERSE_LANDSCAPE;
 482             } else if (orientReq.equals(OrientationRequested.LANDSCAPE)) {
 483                 orient = PageFormat.LANDSCAPE;
 484             } else {
 485                 orient = PageFormat.PORTRAIT;
 486             }
 487             pf.setOrientation(orient);
 488         }
 489 
 490         pf.setPaper(paper);
 491         pf = validatePage(pf);
 492         return pf;
 493     }
 494 
 495     /**
 496      * Returns the clone of <code>page</code> with its settings
 497      * adjusted to be compatible with the current printer of this
 498      * <code>PrinterJob</code>.  For example, the returned
 499      * <code>PageFormat</code> could have its imageable area
 500      * adjusted to fit within the physical area of the paper that
 501      * is used by the current printer.
 502      * @param page the <code>PageFormat</code> that is cloned and
 503      *          whose settings are changed to be compatible with
 504      *          the current printer
 505      * @return a <code>PageFormat</code> that is cloned from
 506      *          <code>page</code> and whose settings are changed
 507      *          to conform with this <code>PrinterJob</code>.
 508      */
 509     public abstract PageFormat validatePage(PageFormat page);
 510 
 511     /**
 512      * Prints a set of pages.
 513      * @exception PrinterException an error in the print system
 514      *            caused the job to be aborted.
 515      * @see Book
 516      * @see Pageable
 517      * @see Printable
 518      */
 519     public abstract void print() throws PrinterException;
 520 
 521    /**
 522      * Prints a set of pages using the settings in the attribute
 523      * set. The default implementation ignores the attribute set.
 524      * <p>
 525      * Note that some attributes may be set directly on the PrinterJob
 526      * by equivalent method calls, (for example), copies:
 527      * <code>setcopies(int)</code>, job name: <code>setJobName(String)</code>
 528      * and specifying media size and orientation though the
 529      * <code>PageFormat</code> object.
 530      * <p>
 531      * If a supported attribute-value is specified in this attribute set,
 532      * it will take precedence over the API settings for this print()
 533      * operation only.
 534      * The following behaviour is specified for PageFormat:
 535      * If a client uses the Printable interface, then the
 536      * <code>attributes</code> parameter to this method is examined
 537      * for attributes which specify media (by size), orientation, and
 538      * imageable area, and those are used to construct a new PageFormat
 539      * which is passed to the Printable object's print() method.
 540      * See {@link Printable} for an explanation of the required
 541      * behaviour of a Printable to ensure optimal printing via PrinterJob.
 542      * For clients of the Pageable interface, the PageFormat will always
 543      * be as supplied by that interface, on a per page basis.
 544      * <p>
 545      * These behaviours allow an application to directly pass the
 546      * user settings returned from
 547      * <code>printDialog(PrintRequestAttributeSet attributes</code> to
 548      * this print() method.
 549      * <p>
 550      *
 551      * @param attributes a set of attributes for the job
 552      * @exception PrinterException an error in the print system
 553      *            caused the job to be aborted.
 554      * @see Book
 555      * @see Pageable
 556      * @see Printable
 557      * @since 1.4
 558      */
 559     public void print(PrintRequestAttributeSet attributes)
 560         throws PrinterException {
 561         print();
 562     }
 563 
 564     /**
 565      * Sets the number of copies to be printed.
 566      * @param copies the number of copies to be printed
 567      * @see #getCopies
 568      */
 569     public abstract void setCopies(int copies);
 570 
 571     /**
 572      * Gets the number of copies to be printed.
 573      * @return the number of copies to be printed.
 574      * @see #setCopies
 575      */
 576     public abstract int getCopies();
 577 
 578     /**
 579      * Gets the name of the printing user.
 580      * @return the name of the printing user
 581      */
 582     public abstract String getUserName();
 583 
 584     /**
 585      * Sets the name of the document to be printed.
 586      * The document name can not be <code>null</code>.
 587      * @param jobName the name of the document to be printed
 588      * @see #getJobName
 589      */
 590     public abstract void setJobName(String jobName);
 591 
 592     /**
 593      * Gets the name of the document to be printed.
 594      * @return the name of the document to be printed.
 595      * @see #setJobName
 596      */
 597     public abstract String getJobName();
 598 
 599     /**
 600      * Cancels a print job that is in progress.  If
 601      * {@link #print() print} has been called but has not
 602      * returned then this method signals
 603      * that the job should be cancelled at the next
 604      * chance. If there is no print job in progress then
 605      * this call does nothing.
 606      */
 607     public abstract void cancel();
 608 
 609     /**
 610      * Returns <code>true</code> if a print job is
 611      * in progress, but is going to be cancelled
 612      * at the next opportunity; otherwise returns
 613      * <code>false</code>.
 614      * @return <code>true</code> if the job in progress
 615      * is going to be cancelled; <code>false</code> otherwise.
 616      */
 617     public abstract boolean isCancelled();
 618 
 619 }