Package net.jini.print.event contains classes for reporting printing events to a Jini Print Service client.

### Kinds of Events

A Jini Print Service instance can report the following kinds of events to registered event listeners. The following events pertain to the Print Service itself:

1. In the Print Service's attribute set, attributes' values changed in a given attribute category or categories. This lets a client track changes in an attribute regardless of which specific values the attribute achieves.

2. In the Print Service's attribute set, attributes' values became equal to a given value or values. This lets a client be notified only when an attribute achieves a specific value or values.

The following events, although originating from the Print Service, pertain to a Print Job being processed by the Print Service:

3. The Print Service successfully obtained one piece of print data for the Print Job. This lets a client obtain confirmation that the print data completely arrived at the Print Service.

4. The Print Service failed to obtain one piece of print data for the Print Job. This lets a client find out what went wrong (in the form of an exception) when the Print Service tried to get the print data.

5. In the Print Job's attribute set, attributes' values changed in a given attribute category or categories. This lets a client track changes in an attribute regardless of which specific values the attribute achieves.

6. In the Print Job's attribute set, attributes' values became equal to a given value or values. This lets a client be notified only when an attribute achieves a specific value or values.

7. The Print Job finished processing, having achieved some final state such as "completed," "canceled," or "aborted." This lets a client be notified only when a Print Job is finished and discover its final state.

### Event Classes

The UML class diagram below shows the classes used to report printing events. These all follow the standard Jini event class pattern, deriving from class net.jini.core.event.RemoteEvent.

Package net.jini.print.event contains common printing event base classes:

- PrintEvent

Package net.jini.print.service contains classes for events pertaining to a Print Service:

- PrintServiceEvent (event kinds #1 and #2)

Package net.jini.print.job contains classes for events pertaining to a Print Job:

- PrintDataEvent (event kinds #3 and #4)
- PrintJobEvent (event kinds #5 and #6)
- PrintJobFinishedEvent (event kind #7)

### Event Registration

You can register to receive events pertaining to a Print Service by calling the `PrintService.addEventListener()` method, specifying five arguments:

- An array of zero or more attribute categories. When an attribute in any of the given categories in the Print Service's attribute set experiences a change in its value, the Print Service reports a PrintServiceEvent to the event listener (event kind #1).

- An array of zero or more print service attribute values. When an attribute in the Print Service's attribute set achieves any of the given values, the Print Service reports a PrintServiceEvent to the event listener (event kind #2).

- A remote event listener object to receive the reported events.

- A handback object reported to the event listener along with the event itself.

- A requested initial duration for the event registration lease.

As part of the process of setting up a Print Request, you can register to receive events pertaining to the resulting Print Job by calling the `PrintRequest.addEventListener()` method, specifying eight arguments:

- Whether to report a PrintDataEvent to the event listener when the Print Service successfully obtains print data for the job (event kind #3).

- Whether to report a PrintDataEvent to the event listener when the Print Service fails to obtain print data for the job (event kind #4).

- An array of zero or more attribute categories. When an attribute in any of the given categories in the Print Job's attribute set experiences a change in its value, the Print Service reports a PrintJobEvent to the event listener (event kind #5).

- An array of zero or more print job attribute values. When an attribute in the Print Job's attribute set achieves any of the given values, the Print Service reports a PrintJobEvent to the event listener (event kind #6).

- Whether to report a PrintJobFinishedEvent to the event listener when the Print Service finishes processing the job (event kind #7).

- A remote event listener object to receive the reported events.

- A handback object reported to the event listener along with the event itself.

- A requested initial duration for the event registration lease.

These events pertain to the Print Job that results when the Print Request is submitted for printing; these events do not pertain to the Print Request per se.

You can also register to receive events pertaining to an existing Print Job by calling the `PrintJob.addEventListener()` method, specifying the same eight arguments. However, depending on the Print Service implementation, you may miss receiving some Print Job events that happen before the event registration takes effect. By registering for event notifications with the Print Request before it is submitted, you are guaranteed to receive all Print Job events from the point of submission onwards.

Following the standard Jini pattern, event registrations are leased. You must maintain the event registration leases for as long as you wish to receive event notifications. When you no longer need to receive event notifications, you should cancel the leases. (If you fail to cancel the leases, they will eventually expire anyway.) When an event registration lease expires, the Print Service discards that event registration and stops sending the event notifications specified for that event registration.

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)