Your browser does not support JavaScript and this site utilizes JavaScript to build content and provide links to additional information. You should either enable JavaScript in your browser settings or use a browser that supports JavaScript in order to take full advantage of this site.

1 /*2 * @(#)PrinterJob.java 1.36 04/01/283 *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 importjava.awt.AWTError;11 importjava.awt.HeadlessException;12 importjava.util.Enumeration;13 14 importjavax.print.DocFlavor;15 importjavax.print.PrintService;16 importjavax.print.PrintServiceLookup;17 importjavax.print.StreamPrintServiceFactory;18 importjavax.print.attribute.PrintRequestAttributeSet;19 20 import sun.security.action.GetPropertyAction;21 22 /**23 * The <code>PrinterJob</code> class is the principal class that controls24 * 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 print26 * the pages of the job.27 */28 publicabstractclass PrinterJob {29 30 /* Public Class Methods */31 32 /**33 * Creates and returns a <code>PrinterJob</code> which is initially34 * associated with the default printer.35 * If no printers are available on the system, a PrinterJob will still36 * 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 if40 * 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 publicstaticPrinterJob getPrinterJob() {46 SecurityManager security = System.getSecurityManager();47 if (security != null) {48 security.checkPrintJobAccess();49 }50 return (PrinterJob) java.security.AccessController.doPrivileged(51 newjava.security.PrivilegedAction() {52 publicObject run() {53 String nm = System.getProperty("java.awt.printerjob", null);54 try {55 return (PrinterJob)Class.forName(nm).newInstance();56 } catch (ClassNotFoundException e) {57 thrownewAWTError("PrinterJob not found: " + nm);58 } catch (InstantiationException e) {59 thrownewAWTError("Could not instantiate PrinterJob: " + nm);60 } catch (IllegalAccessException e) {61 thrownewAWTError("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 on70 * <code>PrinterJob</code>s which support print services.71 * Calling this method is equivalent to calling72 * {@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.478 */79 publicstaticPrintService[] lookupPrintServices() {80 return PrintServiceLookup.81 lookupPrintServices(DocFlavor.SERVICE_FORMATTED.PAGEABLE, null);82 }83 84 85 /**86 * A convenience method which locates factories for stream print87 * 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 on106 * <code>PrinterJob</code> instances which support print services.107 * Calling this method is equivalent to calling108 * {@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.4115 */116 publicstaticStreamPrintServiceFactory[]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 the128 * 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 services136 * may return null;137 * @return the service for this printer job.138 * @see #setPrintService(PrintService)139 * @since 1.4140 */141 publicPrintService getPrintService() {142 returnnull;143 }144 145 /**146 * Associate this PrinterJob with a new PrintService.147 * This method is overridden by subclasses which support148 * specifying a Print Service.149 *150 * Throws <code>PrinterException</code> if the specified service151 * cannot support the <code>Pageable</code> and152 * <code>Printable</code> interfaces necessary to support 2D printing.153 * @param service a print service that supports 2D printing154 * @exception PrinterException if the specified service does not support155 * 2D printing, or this PrinterJob class does not support156 * setting a 2D print service, or the specified service is157 * otherwise not a valid print service.158 * @see #getPrintService159 * @since 1.4160 */161 publicvoid setPrintService(PrintService service)162 throwsPrinterException {163 thrownewPrinterException(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 the169 * 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 page172 * is the default page format.173 * @param painter the <code>Printable</code> that renders each page of174 * the document.175 */176 publicabstractvoid setPrintable(Printable painter);177 178 /**179 * Calls <code>painter</code> to render the pages in the specified180 * <code>format</code>. The pages in the document to be printed by181 * this <code>PrinterJob</code> are rendered by the182 * <code>Printable</code> object, <code>painter</code>. The183 * <code>PageFormat</code> of each page is <code>format</code>.184 * @param painter the <code>Printable</code> called to render185 * each page of the document186 * @param format the size and orientation of each page to187 * be printed188 */189 publicabstractvoid 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 each194 * page held in the <code>Pageable</code> instance, 195 * <code>document</code>.196 * @param document the pages to be printed. It can not be197 * <code>null</code>.198 * @exception NullPointerException the <code>Pageable</code> passed in199 * was <code>null</code>.200 * @see PageFormat201 * @see Printable202 */203 publicabstractvoid setPageable(Pageable document)204 throwsNullPointerException;205 206 /**207 * Presents a dialog to the user for changing the properties of208 * the print job.209 * This method will display a native dialog if a native print210 * service is selected, and user choice of printers will be restricted211 * to these native print services.212 * To present the cross platform print dialog for all services,213 * including native ones instead use214 * <code>printDialog(PrintRequestAttributeSet)</code>.215 * <p>216 * PrinterJob implementations which can use PrintService's will update217 * the PrintService for this PrinterJob to reflect the new service218 * 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#isHeadless224 */225 publicabstractboolean printDialog() throwsHeadlessException;226 227 /**228 * A convenience method which displays a cross-platform print dialog229 * for all services which are capable of printing 2D graphics using the230 * <code>Pageable</code> interface. The selected printer when the231 * dialog is initially displayed will reflect the print service currently232 * attached to this print job.233 * If the user changes the print service, the PrinterJob will be234 * 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 applications239 * required initial selections in the user dialog. Attributes not240 * specified display using the default for the service. On return it241 * will reflect the user's choices. Selections may be updated by242 * the implementation to be consistent with the supported values243 * for the currently selected print service.244 * <p>245 * As the user scrolls to a new print service selection, the values246 * copied are based on the settings for the previous service, together247 * with any user changes. The values are not based on the original248 * settings supplied by the client.249 * <p>250 * With the exception of selected printer, the PrinterJob state is251 * not updated to reflect the user's changes.252 * For the selections to affect a printer job, the attributes must253 * be specified in the call to the254 * <code>print(PrintRequestAttributeSet)</code> method. If using255 * the Pageable interface, clients which intend to use media selected256 * by the user must create a PageFormat derived from the user's257 * selections.258 * If the user cancels the dialog, the attributes will not reflect259 * 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> parameter268 * is null.269 * @see java.awt.GraphicsEnvironment#isHeadless270 * @since 1.4271 * 272 */273 publicboolean printDialog(PrintRequestAttributeSet attributes)274 throwsHeadlessException {275 276 if (attributes == null) {277 thrownewNullPointerException("attributes");278 }279 return printDialog();280 }281 282 /**283 * Displays a dialog that allows modification of a284 * <code>PageFormat</code> instance.285 * The <code>page</code> argument is used to initialize controls286 * in the page setup dialog.287 * If the user cancels the dialog then this method returns the288 * original <code>page</code> object unmodified.289 * If the user okays the dialog then this method returns a new290 * <code>PageFormat</code> object with the indicated changes.291 * In either case, the original <code>page</code> object is292 * not modified.293 * @param page the default <code>PageFormat</code> presented to the294 * user for modification295 * @return the original <code>page</code> object if the dialog296 * is cancelled; a new <code>PageFormat</code> object297 * containing the format indicated by the user if the298 * dialog is acknowledged.299 * @exception HeadlessException if GraphicsEnvironment.isHeadless()300 * returns true.301 * @see java.awt.GraphicsEnvironment#isHeadless302 * @since 1.2303 */304 publicabstractPageFormat pageDialog(PageFormat page)305 throwsHeadlessException;306 307 /**308 * A convenience method which displays a cross-platform page setup dialog.309 * The choices available will reflect the print service currently310 * set on this PrinterJob.311 * <p>312 * The attributes parameter on input will reflect the client's313 * required initial selections in the user dialog. Attributes which are314 * not specified display using the default for the service. On return it315 * will reflect the user's choices. Selections may be updated by316 * the implementation to be consistent with the supported values317 * for the currently selected print service.318 * <p>319 * The return value will be a PageFormat equivalent to the320 * selections in the PrintRequestAttributeSet.321 * If the user cancels the dialog, the attributes will not reflect322 * 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> parameter331 * is null.332 * @see java.awt.GraphicsEnvironment#isHeadless333 * @since 1.4334 * 335 */336 publicPageFormat pageDialog(PrintRequestAttributeSet attributes)337 throwsHeadlessException {338 339 if (attributes == null) {340 thrownewNullPointerException("attributes");341 }342 return pageDialog(defaultPage());343 }344 345 /**346 * Clones the <code>PageFormat</code> argument and alters the347 * clone to describe a default page size and orientation.348 * @param page the <code>PageFormat</code> to be cloned and altered349 * @return clone of <code>page</code>, altered to describe a default350 * <code>PageFormat</code>.351 */352 publicabstractPageFormat defaultPage(PageFormat page);353 354 /**355 * Creates a new <code>PageFormat</code> instance and356 * sets it to a default size and orientation.357 * @return a <code>PageFormat</code> set to a default size and358 * orientation.359 */360 publicPageFormat defaultPage() {361 return defaultPage(newPageFormat());362 }363 364 /**365 * Returns the clone of <code>page</code> with its settings366 * adjusted to be compatible with the current printer of this367 * <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 that370 * 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 with373 * the current printer374 * @return a <code>PageFormat</code> that is cloned from375 * <code>page</code> and whose settings are changed 376 * to conform with this <code>PrinterJob</code>.377 */378 publicabstractPageFormat validatePage(PageFormat page);379 380 /**381 * Prints a set of pages.382 * @exception PrinterException an error in the print system383 * caused the job to be aborted.384 * @see Book385 * @see Pageable386 * @see Printable387 */388 publicabstractvoid print() throwsPrinterException;389 390 /**391 * Prints a set of pages using the settings in the attribute392 * set. The default implementation ignores the attribute set.393 * <p>394 * Note that some attributes may be set directly on the PrinterJob395 * 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 the398 * <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 the405 * <code>attributes</code> parameter to this method is examined406 * for attributes which specify media (by size), orientation, and407 * imageable area, and those are used to construct a new PageFormat408 * which is passed to the Printable object's print() method.409 * See {@link Printable} for an explanation of the required410 * behaviour of a Printable to ensure optimal printing via PrinterJob.411 * For clients of the Pageable interface, the PageFormat will always412 * be as supplied by that interface, on a per page basis.413 * <p>414 * These behaviours allow an application to directly pass the415 * user settings returned from416 * <code>printDialog(PrintRequestAttributeSet attributes</code> to417 * this print() method.418 * <p>419 * 420 * @param attributes a set of attributes for the job421 * @exception PrinterException an error in the print system422 * caused the job to be aborted.423 * @see Book424 * @see Pageable425 * @see Printable426 */427 publicvoid print(PrintRequestAttributeSet attributes)428 throwsPrinterException {429 print();430 }431 432 /**433 * Sets the number of copies to be printed.434 * @param copies the number of copies to be printed435 * @see #getCopies436 */437 publicabstractvoid 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 #setCopies443 */444 publicabstractint getCopies();445 446 /**447 * Gets the name of the printing user.448 * @return the name of the printing user449 */450 publicabstractString 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 printed456 * @see #getJobName457 */458 publicabstractvoid 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 #setJobName464 */465 publicabstractString 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 signals471 * that the job should be cancelled at the next472 * chance. If there is no print job in progress then473 * this call does nothing.474 */475 publicabstractvoid cancel();476 477 /**478 * Returns <code>true</code> if a print job is 479 * in progress, but is going to be cancelled480 * at the next opportunity; otherwise returns481 * <code>false</code>.482 * @return <code>true</code> if the job in progress483 * is going to be cancelled; <code>false</code> otherwise.484 */485 publicabstractboolean isCancelled();486 487 }488