javax.print package

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 {@link javax.print.PrintServiceLookup 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 {@link javax.print.attribute} and {@link 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 capabilites, such as: resolution, copies, media sizes, job priority, and page ranges.

### Document Type Specification

The {@link javax.print.DocFlavor 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 {@link javax.print.Doc 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 {@link javax.print.DocPrintJob 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