Registering for Events

The Java Print Service API allows services to report two types of events to applications: printer status updates and print job progress updates. The events API, which includes the javax.print.event package and methods to register listeners on a service and DocPrintJob, follows the familiar listener model used in AWT.

Print Service Events

Print Service event listeners monitor a service's changes in status and report events as changes in the values of print service attributes. An application can monitor events on a print service by implementing the javax.print.event.PrintServiceAttributeListener interface and installing itself as a listener on a PrintService as shown in this example:

public class PrintPS implements PrintServiceAttributeListener {
	...
	pservices[0].addPrintServiceAttributeListener(this);
	...
	public void attributeUpdate(PrintServiceAttributeEvent e){
		// Do something if an attribute is updated
	}
...

The PrintServiceAttributeListener.attributeUpdate() method is called when print service attributes change. The service uses the PrintServiceAttributeListener interface to decide which events it supports.

An application can discover which print service attributes a service supports by using the same query methods it uses to discover which request attributes a service supports. For example, to discover if the service supports the QueuedJobCount attribute an application calls:

service.isAttributeCategorySupported(QueuedJobCount.class);

The service determines how frequently it reports updates on attributes. If many attributes are supported, the service might batch events, which means an application isn't guaranteed to receive a particular event. The delivered event contains only attributes that have changed in value, which means that static service attributes, such as the printer model, will never be reported in an event.

Print Job Events

Most printing clients are more interested in monitoring a print job than monitoring a service's status. A client can install two different kinds of listeners on a DocPrintJob: PrintJobAttributeListener and PrintJobListener.

PrintJobAttributeListener

PrintJobAttributeListener is similar to the service attribute listener: the job reports changes in attributes that implement the PrintJobAttribute interface. Usually these attributes are also print request attributes and are fixed over the lifetime of a print job. Only a few attributes, such as JobMediaSheetsCompleted, are likely to change. Since few clients are interested in this granularity of detail, and even fewer services support this capability, clients will most likely use PrintJobListener to monitor a job's progress.

PrintJobListener

PrintJobListener is easier to use than PrintJobAttributeListener because it delivers simple messages, such as printJobCompleted or printJobFailed. The interface has only six methods, each of which reports a significant but simple piece of information as an event. As a convenience, the adapter class, PrintJobAdapter, provides default implementations of these six methods.

One message in particular: printJobNoMoreEvents is unusual but useful. A client is often interested in knowing if a job has finished or failed. If possible, a service should deliver such "terminal" events, but sometimes the service cannot be sure if the job finished or failed, and a "completed" message is misleading in this case. For example, a job might be spooled to a network print service that has a queue that's not visible. In this case, the "no more events" message is not sufficient to say that the job has succeeded, but the client can at least infer that it is not known to have failed. The following example demonstrates adding a listener that monitors printJobNoMoreEvents messages:

public class PrintPS extends PrintJobAdapter{
	...
	pj.addPrintJobListener(this);
	...
	public void printJobNoMoreEvents(PrintJobEvent e){
		// Do something here
	}
...