Module java.desktop

# Package javax.print

Provides the principal classes and interfaces for the Java™ 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 `ServiceLoader` facility.

## 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(MediaSizeName.ISO_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

Interface Summary
Interface | Description
--- | ---
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
Class | Description
--- | ---
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
Exception | Description
--- | ---
PrintException | Class `PrintException` encapsulates a printing-related error condition that occurred while using a Print Service instance.