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      *

   550      * @param attributes a set of attributes for the job

   551      * @exception PrinterException an error in the print system

   552      *            caused the job to be aborted.

   553      * @see Book

   554      * @see Pageable

   555      * @see Printable

   556      * @since 1.4

   557      */

   558     public void print(PrintRequestAttributeSet attributes)

   559         throws PrinterException {

   560         print();

   561     }

   562 

   563     /**

   564      * Sets the number of copies to be printed.

   565      * @param copies the number of copies to be printed

   566      * @see #getCopies

   567      */

   568     public abstract void setCopies(int copies);

   569 

   570     /**

   571      * Gets the number of copies to be printed.

   572      * @return the number of copies to be printed.

   573      * @see #setCopies

   574      */

   575     public abstract int getCopies();

   576 

   577     /**

   578      * Gets the name of the printing user.

   579      * @return the name of the printing user

   580      */

   581     public abstract String getUserName();

   582 

   583     /**

   584      * Sets the name of the document to be printed.

   585      * The document name can not be <code>null</code>.

   586      * @param jobName the name of the document to be printed

   587      * @see #getJobName

   588      */

   589     public abstract void setJobName(String jobName);

   590 

   591     /**

   592      * Gets the name of the document to be printed.

   593      * @return the name of the document to be printed.

   594      * @see #setJobName

   595      */

   596     public abstract String getJobName();

   597 

   598     /**

   599      * Cancels a print job that is in progress.  If

   600      * {@link #print() print} has been called but has not

   601      * returned then this method signals

   602      * that the job should be cancelled at the next

   603      * chance. If there is no print job in progress then

   604      * this call does nothing.

   605      */

   606     public abstract void cancel();

   607 

   608     /**

   609      * Returns <code>true</code> if a print job is

   610      * in progress, but is going to be cancelled

   611      * at the next opportunity; otherwise returns

   612      * <code>false</code>.

   613      * @return <code>true</code> if the job in progress

   614      * is going to be cancelled; <code>false</code> otherwise.

   615      */

   616     public abstract boolean isCancelled();

   617 

   618 }