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:
-
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.
-
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:
-
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.
-
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.
-
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.
-
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.
-
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:
Package net.jini.print.service
contains classes for events
pertaining to a Print Service:
Package net.jini.print.job
contains classes for events
pertaining to a Print Job:
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)