Package net.jini.print.data contains interfaces that let a Jini Print Service instance obtain from the client the data to be printed.

### 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.data 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. (See package net.jini.print.job.)

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.

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. (See package net.jini.print.job.)

### 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. (See package net.jini.print.job.)

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.

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.

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.

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. (See package net.jini.print.job.)

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

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

- Declare the Doc interface whereby the printer obtains a doc to be printed. A doc consists of the print data format, printing attributes, and a print data representation object containing the print data itself. Interface Doc in package net.jini.print.data extends interface Doc in package javax.print.data but specifies restricted semantics for use with a Jini Print Service instance.

- Declare the LeasedDoc interface whereby the print data source can optionally convey a lease on the print data to the printer.

- Declare the MultiDoc interface for providing a group of docs to a single Print Job. A multidoc object provides access to the current doc in the group and the next multidoc object in the group; this "linked list view" allows the printer to scan the group of docs in an idempotent fashion, which is crucial in a distributed system. Interface MultiDoc in package net.jini.print.data extends interface MultiDoc in package javax.print.data but specifies restricted semantics for use with a Jini Print Service instance.

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

A Jini Print Service instance advertises the doc flavors it supports by including supported doc flavor entries in its service registration in the JLUS. To get a Jini Print Service instance that can print your job's data, make sure to include the proper doc flavor as a criterion when you search the JLUS.

Printing attributes are specified by objects that implement interface Attribute in package javax.print.attribute. A Jini Print Service instance advertises the printing attribute values it supports by including supported attribute entries in its service registration in the JLUS. To get a Jini Print Service instance that can support your print job's attributes, make sure to include the attributes as criteria when you search the JLUS. See the print service lookup scheme in package net.jini.print.lookup for further information.

Some print data sources may allocate resources that need to be deallocated if there is a distributed failure of the printer. In that case the print data source can provide a doc object that implements interface LeasedDoc as well as interface Doc, thereby conveying a lease on the print data. The printer must renew the lease until the printer has finished obtaining the print data. When the lease expires or is canceled, the print data source can deallocate resources.

Package net.jini.print.data also provides two "tagging base classes," RemoteInputStream and RemoteReader. These extend the standard InputStream and Reader base classes in package java.io, but impose additional requirements that let the consumer recover from transient remote errors when reading a byte stream or character stream in a distributed system. A doc whose print data representation object is an input stream or a reader can actually supply an instance of class RemoteInputStream or RemoteReader. The Jini Print Service instance can test whether the print data representation object is actually a RemoteInputStream or RemoteReader and, if so, perform additional remote error recovery actions that are not possible with a plain old InputStream or Reader.

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)