/*
* @(#)PrinterJob.java 1.36 04/01/28
*
* Copyright 2004 Sun Microsystems, Inc. All rights reserved.
* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*/
package java.awt.print;
import java.awt.AWTError;
import java.awt.HeadlessException;
import java.util.Enumeration;
import javax.print.DocFlavor;
import javax.print.PrintService;
import javax.print.PrintServiceLookup;
import javax.print.StreamPrintServiceFactory;
import javax.print.attribute.PrintRequestAttributeSet;
import sun.security.action.GetPropertyAction;
/**
* The PrinterJob
class is the principal class that controls
* printing. An application calls methods in this class to set up a job,
* optionally to invoke a print dialog with the user, and then to print
* the pages of the job.
*/
public abstract class PrinterJob {
/* Public Class Methods */
/**
* Creates and returns a PrinterJob
which is initially
* associated with the default printer.
* If no printers are available on the system, a PrinterJob will still
* be returned from this method, but getPrintService()
* will return null
, and calling
* {@link #print() print} with this PrinterJob
might
* generate an exception. Applications that need to determine if
* there are suitable printers before creating a PrinterJob
* should ensure that the array returned from
* {@link #lookupPrintServices() lookupPrintServices} is not empty.
* @return a new PrinterJob
.
*/
public static PrinterJob getPrinterJob() {
SecurityManager security = System.getSecurityManager();
if (security != null) {
security.checkPrintJobAccess();
}
return (PrinterJob) java.security.AccessController.doPrivileged(
new java.security.PrivilegedAction() {
public Object run() {
String nm = System.getProperty("java.awt.printerjob", null);
try {
return (PrinterJob)Class.forName(nm).newInstance();
} catch (ClassNotFoundException e) {
throw new AWTError("PrinterJob not found: " + nm);
} catch (InstantiationException e) {
throw new AWTError("Could not instantiate PrinterJob: " + nm);
} catch (IllegalAccessException e) {
throw new AWTError("Could not access PrinterJob: " + nm);
}
}
});
}
/**
* A convenience method which looks up 2D print services.
* Services returned from this method may be installed on
* PrinterJob
s which support print services.
* Calling this method is equivalent to calling
* {@link javax.print.PrintServiceLookup#lookupPrintServices(
* DocFlavor, AttributeSet)
* PrintServiceLookup.lookupPrintServices()
}
* and specifying a Pageable DocFlavor.
* @return a possibly empty array of 2D print services.
* @since 1.4
*/
public static PrintService[] lookupPrintServices() {
return PrintServiceLookup.
lookupPrintServices(DocFlavor.SERVICE_FORMATTED.PAGEABLE, null);
}
/**
* A convenience method which locates factories for stream print
* services which can image 2D graphics.
* Sample usage :
*
* FileOutputStream outstream; * StreamPrintService psPrinter; * String psMimeType = "application/postscript"; * * StreamPrintServiceFactory[] factories = * PrinterJob.lookupStreamPrintServices(psMimeType); * if (factories.length > 0) { * try { * outstream = new File("out.ps"); * psPrinter = factories[0].getPrintService(fos); * // psPrinter can now be set as the service on a PrinterJob * } catch (FileNotFoundException e) { * } * } ** Services returned from this method may be installed on *
PrinterJob
instances which support print services.
* Calling this method is equivalent to calling
* {@link javax.print.StreamPrintServiceFactory#lookupStreamPrintServiceFactories(DocFlavor, String)
* StreamPrintServiceFactory.lookupStreamPrintServiceFactories()
*
} and specifying a Pageable DocFlavor.
*
* @param mimeType the required output format, or null to mean any format.
* @return a possibly empty array of 2D stream print service factories.
* @since 1.4
*/
public static StreamPrintServiceFactory[]
lookupStreamPrintServices(String mimeType) {
return StreamPrintServiceFactory.lookupStreamPrintServiceFactories(
DocFlavor.SERVICE_FORMATTED.PAGEABLE,
mimeType);
}
/* Public Methods */
/**
* A PrinterJob
object should be created using the
* static {@link #getPrinterJob() getPrinterJob
} method.
*/
public PrinterJob() {
}
/**
* Returns the service (printer) for this printer job.
* Implementations of this class which do not support print services
* may return null;
* @return the service for this printer job.
* @see #setPrintService(PrintService)
* @since 1.4
*/
public PrintService getPrintService() {
return null;
}
/**
* Associate this PrinterJob with a new PrintService.
* This method is overridden by subclasses which support
* specifying a Print Service.
*
* Throws PrinterException
if the specified service
* cannot support the Pageable
and
* Printable
interfaces necessary to support 2D printing.
* @param service a print service that supports 2D printing
* @exception PrinterException if the specified service does not support
* 2D printing, or this PrinterJob class does not support
* setting a 2D print service, or the specified service is
* otherwise not a valid print service.
* @see #getPrintService
* @since 1.4
*/
public void setPrintService(PrintService service)
throws PrinterException {
throw new PrinterException(
"Setting a service is not supported on this class");
}
/**
* Calls painter
to render the pages. The pages in the
* document to be printed by this
* PrinterJob
are rendered by the {@link Printable}
* object, painter
. The {@link PageFormat} for each page
* is the default page format.
* @param painter the Printable
that renders each page of
* the document.
*/
public abstract void setPrintable(Printable painter);
/**
* Calls painter
to render the pages in the specified
* format
. The pages in the document to be printed by
* this PrinterJob
are rendered by the
* Printable
object, painter
. The
* PageFormat
of each page is format
.
* @param painter the Printable
called to render
* each page of the document
* @param format the size and orientation of each page to
* be printed
*/
public abstract void setPrintable(Printable painter, PageFormat format);
/**
* Queries document
for the number of pages and
* the PageFormat
and Printable
for each
* page held in the Pageable
instance,
* document
.
* @param document the pages to be printed. It can not be
* null
.
* @exception NullPointerException the Pageable
passed in
* was null
.
* @see PageFormat
* @see Printable
*/
public abstract void setPageable(Pageable document)
throws NullPointerException;
/**
* Presents a dialog to the user for changing the properties of
* the print job.
* This method will display a native dialog if a native print
* service is selected, and user choice of printers will be restricted
* to these native print services.
* To present the cross platform print dialog for all services,
* including native ones instead use
* printDialog(PrintRequestAttributeSet)
.
*
* PrinterJob implementations which can use PrintService's will update
* the PrintService for this PrinterJob to reflect the new service
* selected by the user.
* @return true
if the user does not cancel the dialog;
* false
otherwise.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
*/
public abstract boolean printDialog() throws HeadlessException;
/**
* A convenience method which displays a cross-platform print dialog
* for all services which are capable of printing 2D graphics using the
* Pageable
interface. The selected printer when the
* dialog is initially displayed will reflect the print service currently
* attached to this print job.
* If the user changes the print service, the PrinterJob will be
* updated to reflect this, unless the user cancels the dialog.
* As well as allowing the user to select the destination printer,
* the user can also select values of various print request attributes.
*
* The attributes parameter on input will reflect the applications * required initial selections in the user dialog. Attributes not * specified display using the default for the service. On return it * will reflect the user's choices. Selections may be updated by * the implementation to be consistent with the supported values * for the currently selected print service. *
* As the user scrolls to a new print service selection, the values * copied are based on the settings for the previous service, together * with any user changes. The values are not based on the original * settings supplied by the client. *
* With the exception of selected printer, the PrinterJob state is
* not updated to reflect the user's changes.
* For the selections to affect a printer job, the attributes must
* be specified in the call to the
* print(PrintRequestAttributeSet)
method. If using
* the Pageable interface, clients which intend to use media selected
* by the user must create a PageFormat derived from the user's
* selections.
* If the user cancels the dialog, the attributes will not reflect
* any changes made by the user.
* @param attributes on input is application supplied attributes,
* on output the contents are updated to reflect user choices.
* This parameter may not be null.
* @return true
if the user does not cancel the dialog;
* false
otherwise.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @exception NullPointerException if attributes
parameter
* is null.
* @see java.awt.GraphicsEnvironment#isHeadless
* @since 1.4
*
*/
public boolean printDialog(PrintRequestAttributeSet attributes)
throws HeadlessException {
if (attributes == null) {
throw new NullPointerException("attributes");
}
return printDialog();
}
/**
* Displays a dialog that allows modification of a
* PageFormat
instance.
* The page
argument is used to initialize controls
* in the page setup dialog.
* If the user cancels the dialog then this method returns the
* original page
object unmodified.
* If the user okays the dialog then this method returns a new
* PageFormat
object with the indicated changes.
* In either case, the original page
object is
* not modified.
* @param page the default PageFormat
presented to the
* user for modification
* @return the original page
object if the dialog
* is cancelled; a new PageFormat
object
* containing the format indicated by the user if the
* dialog is acknowledged.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
* @since 1.2
*/
public abstract PageFormat pageDialog(PageFormat page)
throws HeadlessException;
/**
* A convenience method which displays a cross-platform page setup dialog.
* The choices available will reflect the print service currently
* set on this PrinterJob.
*
* The attributes parameter on input will reflect the client's * required initial selections in the user dialog. Attributes which are * not specified display using the default for the service. On return it * will reflect the user's choices. Selections may be updated by * the implementation to be consistent with the supported values * for the currently selected print service. *
* The return value will be a PageFormat equivalent to the
* selections in the PrintRequestAttributeSet.
* If the user cancels the dialog, the attributes will not reflect
* any changes made by the user, and the return value will be null.
* @param attributes on input is application supplied attributes,
* on output the contents are updated to reflect user choices.
* This parameter may not be null.
* @return a page format if the user does not cancel the dialog;
* null
otherwise.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @exception NullPointerException if attributes
parameter
* is null.
* @see java.awt.GraphicsEnvironment#isHeadless
* @since 1.4
*
*/
public PageFormat pageDialog(PrintRequestAttributeSet attributes)
throws HeadlessException {
if (attributes == null) {
throw new NullPointerException("attributes");
}
return pageDialog(defaultPage());
}
/**
* Clones the PageFormat
argument and alters the
* clone to describe a default page size and orientation.
* @param page the PageFormat
to be cloned and altered
* @return clone of page
, altered to describe a default
* PageFormat
.
*/
public abstract PageFormat defaultPage(PageFormat page);
/**
* Creates a new PageFormat
instance and
* sets it to a default size and orientation.
* @return a PageFormat
set to a default size and
* orientation.
*/
public PageFormat defaultPage() {
return defaultPage(new PageFormat());
}
/**
* Returns the clone of page
with its settings
* adjusted to be compatible with the current printer of this
* PrinterJob
. For example, the returned
* PageFormat
could have its imageable area
* adjusted to fit within the physical area of the paper that
* is used by the current printer.
* @param page the PageFormat
that is cloned and
* whose settings are changed to be compatible with
* the current printer
* @return a PageFormat
that is cloned from
* page
and whose settings are changed
* to conform with this PrinterJob
.
*/
public abstract PageFormat validatePage(PageFormat page);
/**
* Prints a set of pages.
* @exception PrinterException an error in the print system
* caused the job to be aborted.
* @see Book
* @see Pageable
* @see Printable
*/
public abstract void print() throws PrinterException;
/**
* Prints a set of pages using the settings in the attribute
* set. The default implementation ignores the attribute set.
*
* Note that some attributes may be set directly on the PrinterJob
* by equivalent method calls, (for example), copies:
* setcopies(int)
, job name: setJobName(String)
* and specifying media size and orientation though the
* PageFormat
object.
*
* If a supported attribute-value is specified in this attribute set,
* it will take precedence over the API settings for this print()
* operation only.
* The following behaviour is specified for PageFormat:
* If a client uses the Printable interface, then the
* attributes
parameter to this method is examined
* for attributes which specify media (by size), orientation, and
* imageable area, and those are used to construct a new PageFormat
* which is passed to the Printable object's print() method.
* See {@link Printable} for an explanation of the required
* behaviour of a Printable to ensure optimal printing via PrinterJob.
* For clients of the Pageable interface, the PageFormat will always
* be as supplied by that interface, on a per page basis.
*
* These behaviours allow an application to directly pass the
* user settings returned from
* printDialog(PrintRequestAttributeSet attributes
to
* this print() method.
*
*
* @param attributes a set of attributes for the job
* @exception PrinterException an error in the print system
* caused the job to be aborted.
* @see Book
* @see Pageable
* @see Printable
*/
public void print(PrintRequestAttributeSet attributes)
throws PrinterException {
print();
}
/**
* Sets the number of copies to be printed.
* @param copies the number of copies to be printed
* @see #getCopies
*/
public abstract void setCopies(int copies);
/**
* Gets the number of copies to be printed.
* @return the number of copies to be printed.
* @see #setCopies
*/
public abstract int getCopies();
/**
* Gets the name of the printing user.
* @return the name of the printing user
*/
public abstract String getUserName();
/**
* Sets the name of the document to be printed.
* The document name can not be null
.
* @param jobName the name of the document to be printed
* @see #getJobName
*/
public abstract void setJobName(String jobName);
/**
* Gets the name of the document to be printed.
* @return the name of the document to be printed.
* @see #setJobName
*/
public abstract String getJobName();
/**
* Cancels a print job that is in progress. If
* {@link #print() print} has been called but has not
* returned then this method signals
* that the job should be cancelled at the next
* chance. If there is no print job in progress then
* this call does nothing.
*/
public abstract void cancel();
/**
* Returns true
if a print job is
* in progress, but is going to be cancelled
* at the next opportunity; otherwise returns
* false
.
* @return true
if the job in progress
* is going to be cancelled; false
otherwise.
*/
public abstract boolean isCancelled();
}