PrinterJob


1   /*
2    * @(#)PrinterJob.java  1.36 04/01/28
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.awt.print;
9   
10  import java.awt.AWTError  ;
11  import java.awt.HeadlessException  ;
12  import java.util.Enumeration  ;
13  
14  import javax.print.DocFlavor  ;
15  import javax.print.PrintService  ;
16  import javax.print.PrintServiceLookup  ;
17  import javax.print.StreamPrintServiceFactory  ;
18  import javax.print.attribute.PrintRequestAttributeSet  ;
19  
20  import sun.security.action.GetPropertyAction;
21  
22  /**
23   * The <code>PrinterJob</code> class is the principal class that controls
24   * printing. An application calls methods in this class to set up a job,
25   * optionally to invoke a print dialog with the user, and then to print
26   * the pages of the job.
27   */
28  public abstract class PrinterJob {
29  
30   /* Public Class Methods */
31  
32      /**
33       * Creates and returns a <code>PrinterJob</code> which is initially
34       * associated with the default printer.
35       * If no printers are available on the system, a PrinterJob will still
36       * be returned from this method, but <code>getPrintService()</code> 
37       * will return <code>null</code>, and calling 
38       * {@link #print() print} with this <code>PrinterJob</code> might 
39       * generate an exception.  Applications that need to determine if
40       * there are suitable printers before creating a <code>PrinterJob</code> 
41       * should ensure that the array returned from 
42       * {@link #lookupPrintServices() lookupPrintServices} is not empty.
43       * @return a new <code>PrinterJob</code>.
44       */
45      public static PrinterJob   getPrinterJob() {
46      SecurityManager   security = System.getSecurityManager();
47      if (security != null) {
48          security.checkPrintJobAccess();
49      }
50      return (PrinterJob  ) java.security.AccessController.doPrivileged(
51          new java.security.PrivilegedAction  () {
52          public Object   run() {
53          String   nm = System.getProperty("java.awt.printerjob", null);
54          try {
55              return (PrinterJob  )Class.forName(nm).newInstance();
56          } catch (ClassNotFoundException   e) {
57              throw new AWTError  ("PrinterJob not found: " + nm);
58          } catch (InstantiationException   e) {
59           throw new AWTError  ("Could not instantiate PrinterJob: " + nm);
60          } catch (IllegalAccessException   e) {
61              throw new AWTError  ("Could not access PrinterJob: " + nm);
62          }
63          }
64      });
65      }
66      
67      /**
68       * A convenience method which looks up 2D print services.
69       * Services returned from this method may be installed on
70       * <code>PrinterJob</code>s which support print services.
71       * Calling this method is equivalent to calling
72       * {@link javax.print.PrintServiceLookup#lookupPrintServices(
73       * DocFlavor, AttributeSet) 
74       * <code>PrintServiceLookup.lookupPrintServices()</code>}
75       * and specifying a Pageable DocFlavor.
76       * @return a possibly empty array of 2D print services.
77       * @since     1.4
78       */
79      public static PrintService  [] lookupPrintServices() {
80      return PrintServiceLookup.
81          lookupPrintServices(DocFlavor.SERVICE_FORMATTED.PAGEABLE, null);
82      }
83  
84     
85      /**
86       * A convenience method which locates factories for stream print
87       * services which can image 2D graphics.
88       * Sample usage :
89       * <pre>
90       * FileOutputStream outstream;
91       * StreamPrintService psPrinter;
92       * String psMimeType = "application/postscript";
93       *
94       * StreamPrintServiceFactory[] factories =
95       *     PrinterJob.lookupStreamPrintServices(psMimeType);
96       * if (factories.length > 0) {
97       *     try {
98       *         outstream = new File("out.ps");
99       *         psPrinter =  factories[0].getPrintService(fos);
100      *         // psPrinter can now be set as the service on a PrinterJob 
101      *     } catch (FileNotFoundException e) {
102      *     }
103      * }            
104      * </pre>
105      * Services returned from this method may be installed on
106      * <code>PrinterJob</code> instances which support print services.
107      * Calling this method is equivalent to calling
108      * {@link javax.print.StreamPrintServiceFactory#lookupStreamPrintServiceFactories(DocFlavor, String)
109      * <code>StreamPrintServiceFactory.lookupStreamPrintServiceFactories()
110      * </code>} and specifying a Pageable DocFlavor.
111      * 
112      * @param mimeType the required output format, or null to mean any format.
113      * @return a possibly empty array of 2D stream print service factories.
114      * @since     1.4
115      */
116     public static StreamPrintServiceFactory  []
117     lookupStreamPrintServices(String   mimeType) {
118     return StreamPrintServiceFactory.lookupStreamPrintServiceFactories(
119                        DocFlavor.SERVICE_FORMATTED.PAGEABLE,
120                        mimeType);
121     }
122                   
123     
124  /* Public Methods */
125 
126     /**
127      * A <code>PrinterJob</code> object should be created using the
128      * static {@link #getPrinterJob() <code>getPrinterJob</code>} method.
129      */
130     public PrinterJob() {
131     }
132 
133     /**
134      * Returns the service (printer) for this printer job.
135      * Implementations of this class which do not support print services
136      * may return null;
137      * @return the service for this printer job.
138      * @see #setPrintService(PrintService)
139      * @since     1.4
140      */
141     public PrintService   getPrintService() {
142     return null;
143     }
144 
145     /**
146      * Associate this PrinterJob with a new PrintService.
147      * This method is overridden by subclasses which support
148      * specifying a Print Service.
149      *
150      * Throws <code>PrinterException</code> if the specified service
151      * cannot support the <code>Pageable</code> and
152      * <code>Printable</code> interfaces necessary to support 2D printing.
153      * @param service a print service that supports 2D printing
154      * @exception PrinterException if the specified service does not support
155      * 2D printing, or this PrinterJob class does not support
156      * setting a 2D print service, or the specified service is
157      * otherwise not a valid print service.
158      * @see #getPrintService
159      * @since     1.4
160      */
161     public void setPrintService(PrintService   service)
162     throws PrinterException   {
163         throw new PrinterException  (
164              "Setting a service is not supported on this class");
165     }
166      
167     /**
168      * Calls <code>painter</code> to render the pages.  The pages in the
169      * document to be printed by this 
170      * <code>PrinterJob</code> are rendered by the {@link Printable}
171      * object, <code>painter</code>.  The {@link PageFormat} for each page
172      * is the default page format.
173      * @param painter the <code>Printable</code> that renders each page of
174      * the document.
175      */
176     public abstract void setPrintable(Printable   painter);
177 
178     /**
179      * Calls <code>painter</code> to render the pages in the specified
180      * <code>format</code>.  The pages in the document to be printed by
181      * this <code>PrinterJob</code> are rendered by the
182      * <code>Printable</code> object, <code>painter</code>. The
183      * <code>PageFormat</code> of each page is <code>format</code>.
184      * @param painter the <code>Printable</code> called to render
185      *      each page of the document
186      * @param format the size and orientation of each page to
187      *                   be printed
188      */
189     public abstract void setPrintable(Printable   painter, PageFormat   format);
190 
191     /**
192      * Queries <code>document</code> for the number of pages and 
193      * the <code>PageFormat</code> and <code>Printable</code> for each
194      * page held in the <code>Pageable</code> instance,  
195      * <code>document</code>.
196      * @param document the pages to be printed. It can not be
197      * <code>null</code>.
198      * @exception NullPointerException the <code>Pageable</code> passed in
199      * was <code>null</code>.
200      * @see PageFormat
201      * @see Printable
202      */
203     public abstract void setPageable(Pageable   document)
204     throws NullPointerException  ;
205 
206     /**
207      * Presents a dialog to the user for changing the properties of
208      * the print job.
209      * This method will display a native dialog if a native print
210      * service is selected, and user choice of printers will be restricted
211      * to these native print services.
212      * To present the cross platform print dialog for all services,
213      * including native ones instead use
214      * <code>printDialog(PrintRequestAttributeSet)</code>.
215      * <p>
216      * PrinterJob implementations which can use PrintService's will update
217      * the PrintService for this PrinterJob to reflect the new service
218      * selected by the user.
219      * @return <code>true</code> if the user does not cancel the dialog;
220      * <code>false</code> otherwise.
221      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
222      * returns true.
223      * @see java.awt.GraphicsEnvironment#isHeadless
224      */
225     public abstract boolean printDialog() throws HeadlessException  ;
226 
227     /**
228      * A convenience method which displays a cross-platform print dialog
229      * for all services which are capable of printing 2D graphics using the
230      * <code>Pageable</code> interface. The selected printer when the
231      * dialog is initially displayed will reflect the print service currently
232      * attached to this print job.
233      * If the user changes the print service, the PrinterJob will be
234      * updated to reflect this, unless the user cancels the dialog.
235      * As well as allowing the user to select the destination printer,
236      * the user can also select values of various print request attributes.
237      * <p>
238      * The attributes parameter on input will reflect the applications
239      * required initial selections in the user dialog. Attributes not
240      * specified display using the default for the service. On return it
241      * will reflect the user's choices. Selections may be updated by
242      * the implementation to be consistent with the supported values
243      * for the currently selected print service.
244      * <p>
245      * As the user scrolls to a new print service selection, the values
246      * copied are based on the settings for the previous service, together
247      * with any user changes. The values are not based on the original
248      * settings supplied by the client.
249      * <p>
250      * With the exception of selected printer, the PrinterJob state is
251      * not updated to reflect the user's changes.
252      * For the selections to affect a printer job, the attributes must
253      * be specified in the call to the
254      * <code>print(PrintRequestAttributeSet)</code> method. If using
255      * the Pageable interface, clients which intend to use media selected
256      * by the user must create a PageFormat derived from the user's
257      * selections.
258      * If the user cancels the dialog, the attributes will not reflect
259      * any changes made by the user.
260      * @param attributes on input is application supplied attributes,
261      * on output the contents are updated to reflect user choices.
262      * This parameter may not be null.
263      * @return <code>true</code> if the user does not cancel the dialog;
264      * <code>false</code> otherwise.
265      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
266      * returns true.
267      * @exception NullPointerException if <code>attributes</code> parameter
268      * is null.
269      * @see java.awt.GraphicsEnvironment#isHeadless
270      * @since     1.4
271      * 
272      */
273     public boolean printDialog(PrintRequestAttributeSet   attributes)
274     throws HeadlessException   {
275 
276     if (attributes == null) {
277         throw new NullPointerException  ("attributes");
278     }
279     return printDialog();
280     }
281 
282     /**
283      * Displays a dialog that allows modification of a
284      * <code>PageFormat</code> instance.
285      * The <code>page</code> argument is used to initialize controls
286      * in the page setup dialog.
287      * If the user cancels the dialog then this method returns the
288      * original <code>page</code> object unmodified.
289      * If the user okays the dialog then this method returns a new
290      * <code>PageFormat</code> object with the indicated changes.
291      * In either case, the original <code>page</code> object is
292      * not modified.
293      * @param page the default <code>PageFormat</code> presented to the
294      *          user for modification
295      * @return    the original <code>page</code> object if the dialog
296      *            is cancelled; a new <code>PageFormat</code> object
297      *        containing the format indicated by the user if the
298      *        dialog is acknowledged.
299      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
300      * returns true.
301      * @see java.awt.GraphicsEnvironment#isHeadless
302      * @since     1.2
303      */
304     public abstract PageFormat   pageDialog(PageFormat   page)
305         throws HeadlessException  ;
306 
307     /**
308      * A convenience method which displays a cross-platform page setup dialog.
309      * The choices available will reflect the print service currently
310      * set on this PrinterJob.
311      * <p>
312      * The attributes parameter on input will reflect the client's
313      * required initial selections in the user dialog. Attributes which are
314      * not specified display using the default for the service. On return it
315      * will reflect the user's choices. Selections may be updated by
316      * the implementation to be consistent with the supported values
317      * for the currently selected print service.
318      * <p>
319      * The return value will be a PageFormat equivalent to the
320      * selections in the PrintRequestAttributeSet.
321      * If the user cancels the dialog, the attributes will not reflect
322      * any changes made by the user, and the return value will be null.
323      * @param attributes on input is application supplied attributes,
324      * on output the contents are updated to reflect user choices.
325      * This parameter may not be null.
326      * @return a page format if the user does not cancel the dialog;
327      * <code>null</code> otherwise.
328      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
329      * returns true.
330      * @exception NullPointerException if <code>attributes</code> parameter
331      * is null.
332      * @see java.awt.GraphicsEnvironment#isHeadless
333      * @since     1.4
334      * 
335      */
336     public PageFormat   pageDialog(PrintRequestAttributeSet   attributes)
337         throws HeadlessException   {
338 
339     if (attributes == null) {
340         throw new NullPointerException  ("attributes");
341     }
342     return pageDialog(defaultPage());
343     }
344 
345     /**
346      * Clones the <code>PageFormat</code> argument and alters the
347      * clone to describe a default page size and orientation.
348      * @param page the <code>PageFormat</code> to be cloned and altered
349      * @return clone of <code>page</code>, altered to describe a default
350      *                      <code>PageFormat</code>.
351      */
352     public abstract PageFormat   defaultPage(PageFormat   page);
353 
354     /**
355      * Creates a new <code>PageFormat</code> instance and
356      * sets it to a default size and orientation.
357      * @return a <code>PageFormat</code> set to a default size and
358      *      orientation.
359      */
360     public PageFormat   defaultPage() {
361         return defaultPage(new PageFormat  ());
362     }
363 
364     /**
365      * Returns the clone of <code>page</code> with its settings
366      * adjusted to be compatible with the current printer of this
367      * <code>PrinterJob</code>.  For example, the returned 
368      * <code>PageFormat</code> could have its imageable area 
369      * adjusted to fit within the physical area of the paper that
370      * is used by the current printer.
371      * @param page the <code>PageFormat</code> that is cloned and 
372      *      whose settings are changed to be compatible with
373      *      the current printer
374      * @return a <code>PageFormat</code> that is cloned from
375      *      <code>page</code> and whose settings are changed 
376      *      to conform with this <code>PrinterJob</code>.
377      */
378     public abstract PageFormat   validatePage(PageFormat   page);
379 
380     /**
381      * Prints a set of pages.
382      * @exception PrinterException an error in the print system
383      *            caused the job to be aborted.
384      * @see Book
385      * @see Pageable
386      * @see Printable
387      */
388     public abstract void print() throws PrinterException  ;
389 
390    /**
391      * Prints a set of pages using the settings in the attribute
392      * set. The default implementation ignores the attribute set.
393      * <p>
394      * Note that some attributes may be set directly on the PrinterJob
395      * by equivalent method calls, (for example), copies:
396      * <code>setcopies(int)</code>, job name: <code>setJobName(String)</code>
397      * and specifying media size and orientation though the
398      * <code>PageFormat</code> object.
399      * <p>
400      * If a supported attribute-value is specified in this attribute set,
401      * it will take precedence over the API settings for this print()
402      * operation only.
403      * The following behaviour is specified for PageFormat:
404      * If a client uses the Printable interface, then the
405      * <code>attributes</code> parameter to this method is examined
406      * for attributes which specify media (by size), orientation, and
407      * imageable area, and those are used to construct a new PageFormat
408      * which is passed to the Printable object's print() method.
409      * See {@link Printable} for an explanation of the required
410      * behaviour of a Printable to ensure optimal printing via PrinterJob.
411      * For clients of the Pageable interface, the PageFormat will always
412      * be as supplied by that interface, on a per page basis.
413      * <p>
414      * These behaviours allow an application to directly pass the
415      * user settings returned from
416      * <code>printDialog(PrintRequestAttributeSet attributes</code> to
417      * this print() method.
418      * <p>
419      * 
420      * @param attributes a set of attributes for the job
421      * @exception PrinterException an error in the print system
422      *            caused the job to be aborted.
423      * @see Book
424      * @see Pageable
425      * @see Printable
426      */
427     public void print(PrintRequestAttributeSet   attributes)
428     throws PrinterException   {
429     print();
430     }
431 
432     /**
433      * Sets the number of copies to be printed.
434      * @param copies the number of copies to be printed
435      * @see #getCopies
436      */
437     public abstract void setCopies(int copies);
438 
439     /**
440      * Gets the number of copies to be printed.
441      * @return the number of copies to be printed.
442      * @see #setCopies
443      */
444     public abstract int getCopies();
445 
446     /**
447      * Gets the name of the printing user.
448      * @return the name of the printing user
449      */
450     public abstract String   getUserName();
451 
452     /**
453      * Sets the name of the document to be printed.
454      * The document name can not be <code>null</code>.
455      * @param jobName the name of the document to be printed
456      * @see #getJobName
457      */
458     public abstract void setJobName(String   jobName);
459 
460     /**
461      * Gets the name of the document to be printed.
462      * @return the name of the document to be printed.
463      * @see #setJobName
464      */
465     public abstract String   getJobName();
466 
467     /**
468      * Cancels a print job that is in progress.  If 
469      * {@link #print() print} has been called but has not 
470      * returned then this method signals
471      * that the job should be cancelled at the next
472      * chance. If there is no print job in progress then
473      * this call does nothing.
474      */
475     public abstract void cancel();
476 
477     /**
478      * Returns <code>true</code> if a print job is 
479      * in progress, but is going to be cancelled
480      * at the next opportunity; otherwise returns
481      * <code>false</code>.
482      * @return <code>true</code> if the job in progress
483      * is going to be cancelled; <code>false</code> otherwise.
484      */
485     public abstract boolean isCancelled();
486 
487 }
488
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags