Package net.jini.print.job contains interfaces that let a client print a job.

### Single Doc Print Jobs

The above interaction diagram shows the interfaces involved in printing a job consisting of just one doc. ("Doc" is a short, easy-to-pronounce term that means "a piece of print data.") Interfaces declared in package net.jini.print.job are highlighted. The Jini Print Service instance supplies the Print Service, Print Request, and Print Job objects, and the client supplies the Doc object.

1. The client searches the Jini Lookup Service (JLUS) for a Jini Print Service instance, and the JLUS returns a Print Service object which implements the base interface PrintService. (See package net.jini.print.lookup.)

2. The client calls a method in interface PrintService telling the printer to create a Print Request to print a single Doc. The printer then returns a Print Request object which implements interface DocPrintRequest as well as the base interface PrintRequest. (See package net.jini.print.service.)

3. The client calls methods in interfaces PrintRequest and DocPrintRequest to specify the doc object to be printed and a set of job-level printing attributes to use for the job. The client can also register event listeners to receive event notifications for the job. Finally, the client calls a method to submit the Print Request to be printed, and the printer returns a Print Job object which implements interface PrintJob.

4. The printer calls methods in interface Doc to obtain the print data format, the document-level printing attributes, and the actual print data, then proceeds to print the job. (See package net.jini.print.data.)

5. The client calls methods in interface PrintJob to monitor the Print Job's progress and control the Print Job as the printer processes it. The client can also register event listeners to receive event notifications for the job. Alternatively, if the client doesn't need to monitor or control the job, the client can simply disregard the returned Print Job object.

### Multiple Doc Print Jobs

The above interaction diagram shows the interfaces involved in printing a job consisting of more than one doc -- a "multidoc." It is much the same as the previous scenario, except a few different interfaces are involved.

1. The client searches the Jini Lookup Service (JLUS) for a Jini Print Service instance, and the JLUS returns a Print Service object which implements interface MultiDocPrintService as well as the base interface PrintService. (See package net.jini.print.lookup.)

2. The client calls a method in interface MultiDocPrintService telling the Print Service to create a Print Request to print a MultiDoc. The printer then returns a Print Request object which implements interface MultiDocPrintRequest as well as the base interface PrintRequest. (See package net.jini.print.service.)

3. The client calls methods in interfaces PrintRequest and MultiDocPrintRequest to specify the multidoc object to be printed and a set of job-level printing attributes to use for the job. The client can also register event listeners to receive event notifications for the job. Finally, the client calls a method to submit the Print Request to be printed, and the printer returns a Print Job object which implements interface PrintJob.

4. The multidoc provides a "linked list view" of the docs to be printed. The printer calls a method in interface MultiDoc on the current multidoc object to get the current doc to be printed. (See package net.jini.print.data.)

5. The printer calls methods in interface Doc on the current doc object to obtain the print data format, the document-level printing attributes, and the actual print data. (See package net.jini.print.data.)

6. The printer calls a method in interface MultiDoc on the current multidoc object to get the next multidoc object, and repeats from Step 4 until it has gotten all the docs. The printer then proceeds to print the job consisting of all the docs. (See package net.jini.print.data.)

7. The client calls methods in interface PrintJob to monitor the Print Job's progress and control the Print Job as the printer processes it. The client can also register event listeners to receive event notifications for the job. Alternatively, if the client doesn't need to monitor or control the job, the client can simply disregard the returned Print Job object.

### Package net.jini.print.job's Role

Package net.jini.print.job's role in the Jini Print Service API is to:

- Declare the PrintRequest interface, the base interface for a Print Request object. A Print Request represents a nascent print job being set up before being submitted to be printed. Interface PrintRequest contains methods that pertain to all Print Requests. The chief method submits a Print Request to be printed.

- Declare the DocPrintRequest interface. A Print Request object created to print a single doc -- a "doc print request" -- implements interface DocPrintRequest as well as the base interface PrintRequest. Interface DocPrintRequest has a method to supply a doc to be printed.

- Declare the MultiDocPrintRequest interface. A Print Request object created to print multiple docs -- a "multidoc print request" -- implements interface MultiDocPrintRequest as well as the base interface PrintRequest. Interface MultiDocPrintRequest has methods to supply a multidoc (a group of docs) to be printed.

- Declare the PrintJob interface, the base interface for a Print Job object. A Print Job represents an actual print job that has been submitted to be printed. Interface PrintJob contains methods for monitoring the job's status.

- Declare the CancelablePrintJob interface, containing a method to cancel a Print Job.

The following UML class diagram shows the relationships among the interfaces and classes described above.

Package net.jini.print.job also includes these supporting classes:

- Container for returning a Print Job and its Lease together -- class PrintJobAndLease.

- Remote event objects for reporting events pertaining to a Print Job -- classes PrintDataEvent, PrintJobEvent, and PrintJobFinishedEvent.

- Exception classes thrown by methods in package net.jini.print.job -- classes PrintJobException and PrintRequestException.

All Jini Print Service instances must be capable of creating doc print requests. Thus, all Jini Print Service proxy objects mandatorily implement interface PrintService. However, creating multidoc print jobs is an optional capability that not all Jini Print Service instances are required to provide. If a Jini Print Service instance can create multidoc print requests, its service proxy object implements interface MultiDocPrintService as well as PrintService.

A Jini Print Service instance advertises the kinds of Print Jobs it supports by the interfaces its service proxy object implements. To get a Jini Print Service instance that can print your kind of job, make sure to search the JLUS for the proper service interface. To print a job with a single doc, search for a service that implements interface PrintService. To print a job with multiple docs, search for a service that implements interface MultiDocPrintService. See the print service lookup scheme in package net.jini.print.lookup for further information.

All Jini Print Service instances must be capable of monitoring print job status. Thus, all Jini Print Service instances create Print Job objects that implement interface PrintJob. However, canceling print jobs is an optional capability that not all Jini Print Service instances are required to provide. If a Jini Print Service instance can cancel print jobs, its Print Job objects implement interface CancelablePrintJob as well as PrintJob.

A Print Request object is not a leased resource; it is merely a container for conveying a job request to a Jini Print Service instance. When a Print Service creates a Print Request object for a client, the Print Service does not allocate any resources that have to be cleaned up if there is a distributed failure of the client.

A Print Job object, on the other hand, is leased resource. When the client submits a Print Request, the Jini Print Service instance creates a Print Job and returns both the Print Job object and a lease object for the Print Job. If the client wants to keep using the Print Job object beyond the lease's duration, the client must renew the lease. When the client no longer needs to use the Print Job object, the client can cancel the lease or simply let it expire. This signals the Jini Print Service instance to clean up resources allocated to the client, if any. However, cancelation or expiration of the Print Job object's lease does not cancel the actual print job, it merely signals that the client will no longer use the Print Job object. The actual print job will continue processing until it has finished printing (barring errors), even if the lease expires or is canceled earlier. Conversely, if the client maintains the lease on the Print Job object beyond the point when the actual print job has finished printing, the client will still be able to use the Print Job object -- for example, to poll its final state.

The client can register a remote event listener to receive event notifications pertaining to a Print Job object. To ensure that the client receives event notifications starting from the point of submission, the client must register for event notifications with the Print Request object before submitting the Print Request. The client can also register for event notifications with the Print Job object after the request has been submitted, although the client may miss some events that occurred between when the job was submitted and when the event registration took effect. The events that can be reported are represented by classes PrintDataEvent and PrintJobEvent.

### Future Capabilities

The following Print Job capabilities will be added in future versions of the Jini Print Service API:

- Change print job settings after submission.
- Dynamic print job control (suspend, resume, reprioritize, redirect, etc.).

Placement of this package under package net.jini.print is preliminary and not yet approved by the Jini Community.

DRAFT STANDARD VERSION 1.0 (23-MAY-2000)