Module java.desktop

# Package javax.print

Provides the principal classes and interfaces for the JavaTM Print Service API.

See: Description

Interface Summary
AttributeException: Interface AttributeException is a mixin interface which a subclass of `PrintException` can implement to report an error condition involving one or more printing attributes that a particular Print Service instance does not support.
CancelablePrintJob: This interface is used by a printing application to cancel a print job.
Doc: Interface Doc specifies the interface for an object that supplies one piece of print data for a Print Job.
DocPrintJob: This interface represents a print job that can print a specified document with a set of job attributes.
FlavorException: Interface FlavorException is a mixin interface which a subclass of `PrintException` can implement to report an error condition involving a doc flavor or flavors (class `DocFlavor`).
MultiDoc: Interface MultiDoc specifies the interface for an object that supplies more than one piece of print data for a Print Job.
MultiDocPrintJob: Obtained from a MultiDocPrintService, a MultiDocPrintJob can print a specified collection of documents as a single print job with a set of job attributes.
MultiDocPrintService: Interface MultiPrintService is the factory for a MultiDocPrintJob.
PrintService: Interface PrintService is the factory for a DocPrintJob.
URIException: Interface URIException is a mixin interface which a subclass of `PrintException` can implement to report an error condition involving a URI address.

Class Summary
DocFlavor: Class `DocFlavor` encapsulates an object that specifies the format in which print data is supplied to a `DocPrintJob`.
DocFlavor.BYTE_ARRAY: Class DocFlavor.BYTE_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a byte array (`byte[]`) as the print data representation class.
DocFlavor.CHAR_ARRAY: Class DocFlavor.CHAR_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a character array (`char[]`) as the print data representation class.
DocFlavor.INPUT_STREAM: Class DocFlavor.INPUT_STREAM provides predefined static constant DocFlavor objects for example doc flavors using a byte stream (`java.io.InputStream`) as the print data representation class.
DocFlavor.READER: Class DocFlavor.READER provides predefined static constant DocFlavor objects for example doc flavors using a character stream (`java.io.Reader`) as the print data representation class.
DocFlavor.SERVICE_FORMATTED: Class DocFlavor.SERVICE_FORMATTED provides predefined static constant DocFlavor objects for example doc flavors for service formatted print data.
DocFlavor.STRING: Class DocFlavor.STRING provides predefined static constant DocFlavor objects for example doc flavors using a string (`java.lang.String`) as the print data representation class.
DocFlavor.URL: Class DocFlavor.URL provides predefined static constant DocFlavor objects.
PrintServiceLookup: Implementations of this class provide lookup services for print services (typically equivalent to printers) of a particular type.
ServiceUI: This class is a collection of UI convenience methods which provide a graphical user dialog for browsing print services looked up through the Java Print Service API.
ServiceUIFactory: Services may optionally provide UIs which allow different styles of interaction in different roles.
SimpleDoc: This class is an implementation of interface `Doc` that can be used in many common printing requests.
StreamPrintService: This class extends `PrintService` and represents a print service that prints data in different formats to a client-provided output stream.
StreamPrintServiceFactory: A `StreamPrintServiceFactory` is the factory for `StreamPrintService` instances, which can print to an output stream in a particular document format described as a mime type.

Exception Summary
PrintException: Class PrintException encapsulates a printing-related error condition that occurred while using a Print Service instance.

## Package javax.print Description

Provides the principal classes and interfaces for the JavaTM Print Service API. The Java Print Service API enables client and server applications to:

- Discover and select print services based on their capabilities
- Specify the format of print data
- Submit print jobs to services that support the document type to be printed.

### Print Service Discovery

An application invokes the static methods of the abstract class `PrintServiceLookup` to locate print services that have the capabilities to satisfy the application's print request. For example, to print a double-sided document, the application first needs to find printers that have the double-sided printing capability.

The JDK includes `PrintServiceLookup` implementations that can locate the standard platform printers. To locate other types of printers, such as IPP printers or JINI printers, a print-service provider can write implementations of `PrintServiceLookup`. The print-service provider can dynamically install these `PrintServiceLookup` implementations using the SPI JAR file specification.

### Attribute Definitions

The `javax.print.attribute` and `javax.print.attribute.standard` packages define print attributes, which describe the capabilities of a print service, specify the requirements of a print job, and track the progress of a print job.

The `javax.print.attribute` package describes the types of attributes and how they can be collected into sets. The `javax.print.attribute.standard` package enumerates all of the standard attributes supported by the API, most of which are implementations of attributes specified in the IETF Specification, RFC 2911 Internet Printing Protocol, 1.1: Model and Semantics, dated September 2000. The attributes specified in `javax.print.attribute.standard` include common capabilities, such as: resolution, copies, media sizes, job priority, and page ranges.

### Document Type Specification

The `DocFlavor` class represents the print data format, such as JPEG or PostScript. A `DocFlavor` object consists of a MIME type, which describes the format, and a document representation class name that indicates how the document is delivered to the printer or output stream. An application uses the `DocFlavor` and an attribute set to find printers that can print the document type specified by the `DocFlavor` and have the capabilities specified by the attribute set.

### Using the API

A typical application using the Java Print Service API performs these steps to process a print request:

1. Chooses a `DocFlavor`.
2. Creates a set of attributes.
3. Locates a print service that can handle the print request as specified by the `DocFlavor` and the attribute set.
4. Creates a `Doc` object encapsulating the `DocFlavor` and the actual print data, which can take many forms including: a Postscript file, a JPEG image, a URL, or plain text.
5. Gets a print job, represented by `DocPrintJob`, from the print service.
6. Calls the print method of the print job.

The following code sample demonstrates a typical use of the Java Print Service API: locating printers that can print five double-sided copies of a Postscript document on size A4 paper, creating a print job from one of the returned print services, and calling print.

>     FileInputStream psStream;
>     try {
>        psStream = new FileInputStream("file.ps");
>     } catch (FileNotFoundException ffne) {
>     }
>     if (psStream == null) {
>         return;
>     }

>     DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
>     Doc myDoc = new SimpleDoc(psStream, psInFormat, null);
>     PrintRequestAttributeSet aset =
>             new HashPrintRequestAttributeSet();
>     aset.add(new Copies(5));
>     aset.add(MediaSize.A4);
>     aset.add(Sides.DUPLEX);
>     PrintService[] services =
>       PrintServiceLookup.lookupPrintServices(psInFormat, aset);
>     if (services.length > 0) {
>        DocPrintJob job = services[0].createPrintJob();
>        try {
>             job.print(myDoc, aset);
>        } catch (PrintException pe) {}
>     }

Please note: In the javax.print APIs, a null reference parameter to methods is incorrect unless explicitly documented on the method as having a meaningful interpretation. Usage to the contrary is incorrect coding and may result in a run time exception either immediately or at some later time. IllegalArgumentException and NullPointerException are examples of typical and acceptable run time exceptions for such cases.

Since:
  1.4