Java™ Platform Printing: The Java Print Service API

• Phil Race, Staff Engineer, Java 2D

• Jerry Evans, Distinguished Engineer

• Jennifer Godinez, Java 2D Engineer

  Sun Microsystems, Inc.

Presentation Overview

• Present the latest API developments in printing for the Java™ 2 Platform, Standard Edition (J2SE™):

  • The Java Print Service (JPS) API

• Show how this API addresses many unsatisfied requirements

• Show by developed example how to get started using the new API

• Give pointers to more information

About Today’s Speakers

• Java 2D™ API team

  • Responsible for printing APIs in the J2SE platform
    • java.awt.print packages
    • javax.print packages
  • Through JCP, participated in the development of the JPS API specification
  • Developed the implementation for the J2SE platform

Historical Context

• First Java “1.1” printing API was AWT component-oriented. “1.1” graphics only

• Java 2 platform introduced Java 2D™ technology-oriented API for printing 2D graphics:

  • java.awt.print.PrinterJob
  • More capable than previous 1.1 API
  • But still primarily a page-imaging API

• Many outstanding developer requests for printer discovery, printer capabilities APIs, etc.

Printing Initiatives

• IPP/1.1—Internet Printing Protocol

  • A new industry-standard protocol for distributed printing
  • An IETF project, see RFC 2911: IPP/1.1

• Jini™ network technology, Printing Working Group (PWG)

  • Developed printing API for Jini technology-capable printers
  • Adopted IPP/1.1 as the underlying model for printer discovery and describing printer capabilities

The Java™ Print Service API

• JSR006—Java Specification Request

  • Submitted by Xerox Corp.
  • Unify the Jini technology and Java technology printing APIs
  • API specification developed through Java Community ProcessSM initiative
  • Derives substantially from Jini technology PWG drafts
  • Resulting API integrates tightly with the existing Java 2D™ printing API

The Java Print Service API

• New API in upcoming project “Merlin” release

  • New javax.print package

• Not another graphics printing API

  • To enumerate and describe printers, etc.
    • Augments Java platform printing
  • Unified with PrinterJob for graphics printing
    • Examples later

The Java Print Service API: Features

• API so that application code has full control over printing

• No need for user dialogs to select non-default printers and their options

• This enables better server-side printing too

• Enhanced user dialogs for client applications

  • Application can inspect and override user dialog selections

The Java Print Service API: Features (Cont.)

• Printer discovery

  • PrintServiceLookup class

• Printer objects

  • PrintService interface

• Printer description

  • Attribute interface

• Print request specification

  • Attribute interface

The Java Print Service API: Features (Cont.)

• Print data description

  • DocFlavor class

• Print job submission

  • DocPrintJob interface

• Print Job monitoring

  • PrintJobEvent class

The Java Print Service API: Package Structure

• javax.print

  • Core package

• javax.print.attribute

  • Classes to describe and contain printer attributes

• javax.print.attribute.standard

  • The common printer attributes

• javax.print.event

  • For notification of job and printer events

A Developed Printing Example

• Sample problem:

  • Application has to print an HTML document
  • Use to learn how to apply the API to implement this printing task

• Steps:

  • Describe print data
  • Specify how data is to be printed
  • Locate a suitable printer
  • Create a print job and specify the print data
  • Submit the print job

Describing the Print Data (Document Flavors)

• DocFlavor class

  • Made up of two string elements
  • First describes the type of print data
    • E.g., jpeg image, plain text
    • Uses mime type, e.g., “image/jpeg”
  • Second describes the Java technology representation of the data
    • E.g., input stream, byte array
    • Uses name of Java class, e.g.,“java.io.InputStream”

Describing the Print Data (Document Flavors—Cont.)

• API has pre-defined DocFlavor instances

  • These are for convenience

• Examples:

  • DocFlavor.BYTE_ARRAY.POSTSCRIPT
  • DocFlavor.INPUT_STREAM.TEXT_PLAIN_UTF8
  • DocFlavor.INPUT_STREAM.TEXT_HTML_US_ASCII
  • DocFlavor.SERVICE_FORMATTED.PRINTABLE

Describing the Print Data Developed Example : Step 1

• Describe the print data using a DocFlavor

• Application is obtaining the HTML content from a URL. Data is ASCII-encoded

• DocFlavor htmlFlavor = DocFlavor.URL.TEXT_HTML_US_ASCII;

• Or alternatively:

• DocFlavor htmlFlavor = new DocFlavor("text/plain;charset=ascii", "java.net.URL");

Specifying How to Print the Data: Printer Attributes

• Printers have capabilities such as:

  • Paper sizes supported
  • Multiple media trays
  • Duplex (2-sided) printing
    • These are request attributes in the JPS API
    • They may be used in a print request to specify how the job is to be printed

• Printer attributes such as name, location are service attributes

Specifying How to Print the Data: Printer Attributes

• Attribute interface

  • Combines role of printer attribute category and attribute value
  • IPP attribute categories
  • First implementing class defines IPP category
    • All subclasses are the same category
  • Instances define particular values

• Different attribute roles (service, request, job, etc).

Specifying How to Print the Data: Printer Attributes (Cont.)

• JPS API represents these using subclasses of the Attribute interface, e.g., PrintRequestAttribute, PrintServiceAttribute

• Applications may use both these attribute types (request and service) to select a suitable printer for a job:

  • E.g., find a colour printer on the 3rd floor that can do large format duplex printing
• More on this in discussion on printer lookup

Specifying How to Print the Data: Printer Attributes (Cont.)

• PrintRequestAttribute examples

  • MediaSizeName class
    • Named paper sizes, e.g., ISO_A4, NA_LETTER, JIS_B5
  • Copies class
    • Number of document copies to print.
    • Client creates instance to hold integer
    • new Copies(99)

Specifying How to Print the Data: Printer Attributes (Cont.)

• PrintRequestAttribute examples

  • Sides class
    • Single or two sided printing.
    • Closed enumeration
    • ONE_SIDED
    • TWO_SIDED_LONG_EDGE
      • Same as DUPLEX
    • TWO_SIDED_SHORT_EDGE
      • Same as TUMBLE

Specifying How to Print the Data: Attribute Sets

• Need for specifying arbitrary sets of attributes in a print request

• Services may also support non-standardised (vendor-specific) attributes, so must be an extensible API for specifying the set of attributes in a print request

• And only one attribute of a particular category can be specified

  • E.g., not valid to specify both Copies(1) and Copies(5)

Specifying How to Print the Data: Attribute Sets (Cont.)

• Support using implementations of AttributeSet interface and more specific subclasses (PrintRequestAttributeSet)

• API includes implementations, e.g.,

  • HashPrintRequestAttributeSet

• import javax.print.attribute.*;

• PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();

Specifying How to Print the Data Developed Example: Step 2

• import javax.print.attribute.*;
  import javax.print.attribute.standard.*;

  PrintRequestAttributeSet aset =
      new HashPrintRequestAttributeSet();

  aset.add(MediaSizeName.ISO_A4);
  aset.add(Sides.TWO_SIDED_LONG_EDGE);
  aset.add(new Copies(2));

The Java Print Service API: Locating a Printer

• Printers represented using the PrintService interface

• PrintServiceLookup class has static methods which can find print services

• Given a job specification can use to find just the printers which can print as specified

• PrintService has methods for determining supported values: e.g.,

  • isAttributeValueSupported(Attribute, ...)

Locating a Printer Developed Example: Step 3

• // use attribute set and doc flavor
  // created earlier.
  PrintService []matchingServices =
      PrintServiceLookup.lookupPrintServices(
           aset, htmlFlavor);

  if (matchingServices.length == 0) {
      return;
  }

  // pick one of the services.

  PrintService service = matchingServices[0];

The Java Print Service API: Creating the Print Job

• A Print Job is obtained from a PrintService

• Print data is supplied using the Doc interface

• Doc encapsulates:

  • The print data (e.g., the URL for HTML)
  • The doc flavor describing the print data
  • Any doc specific attributes (typically null)

• SimpleDoc implementation of Doc included in the API

Create Print Job and Specify Data Developed Example: Step 4

• import java.net.*;
  import javax.print.*;

  URL url = < ... the print data source ..>;

  DocPrintJob pjob =

     service.createPrintJob();
  SimpleDoc doc =
     new SimpleDoc(url, htmlFlavor, null);

Submit the Print Job Developed Example: Step 5

• Exception thrown if problem detected with job specification

• Printing job may complete asynchronously, use event listeners to be sure job printed

  try {
     pjob.print(doc, aset);
  } catch (PrintException e) {
  }

2D PrinterJob: SDK 1.4 Example

• Using 2D PrinterJob with Print services

  PrintRequestAttributeSet aset =
     new HashPrintRequestAttributeSet();

  DocFlavor pFlavor =
  DocFlavor.SERVICE_FORMATTED_PRINTABLE;

  PrintService[] services =
  PrintServiceLookup(pFlavor, aset);

  if (services.length == 0) {
     return;
  }

2D PrinterJob: SDK 1.4 Example (Cont.)

PrinterJob job = PrinterJob.getPrinterJob();
job.setPrintable(this); // Printable object

job.setPrintService(services[0]);

if (job.printDialog(aset)) {
   try {       job.print(aset);
   } catch (PrinterException e) {
}