//******************************************************************************
//
// File:    PrintEvent.java
// Package: net.jini.print.event
// Unit:    Class net.jini.print.event.PrintEvent
//
//******************************************************************************

package net.jini.print.event;

import java.rmi.MarshalledObject;

import net.jini.core.event.RemoteEvent;

import net.jini.print.service.PrintService;

/**
 * Class PrintEvent is an abstract base class for all printing events. It 
 * encapsulates the event source, namely the Jini Print Service instance that 
 * reported the event. Subclasses encapsulate additional information for various 
 * kinds of printing events. 
 * <P>
 * The Jini Print Service is <I>not</I> required to guarantee that print events 
 * are delivered reliably in sequence. In other words, print events may be lost 
 * or delivered out of order due to processor or network failures. 
 * <P>
 * The information returned by the methods inherited from class 
 * net.jini.core.event.RemoteEvent is as follows: 
 * <UL>
 * <LI>
 * <CODE>getID()</CODE> -- The event identifier is unique among all the event 
 * registrations for a particular Jini Print Service instance. 
 * <P>
 * <LI>
 * <CODE>getSequenceNumber()</CODE> -- Jini Print Service event sequence numbers 
 * are "fully ordered." For a given print service and event identifier, sequence 
 * numbers start at 1, successive events' sequence numbers are strictly 
 * increasing, and no sequence numbers are skipped. 
 * <P>
 * <LI>
 * <CODE>getRegistrationObject()</CODE> -- This is the handback object the 
 * client provided when registering for this event notification. 
 * </UL>
 * <P>
 * <B>DRAFT STANDARD VERSION 1.0 (23-MAY-2000)</B>
 *
 * @author  Alan Kaminsky
 * @version 10-May-2000
 */
public abstract class PrintEvent
	extends RemoteEvent
	{
 
// Exported constructors.

	/**
	 * Constructs a new print event object. 
	 *
	 * @param  theSource          Event source, namely the print service that
	 *                            reported this event.
	 * @param  theEventID         Event identifier for this event.
	 * @param  theSequenceNumber  Sequence number for this event.
	 * @param  theHandbackObject  Handback object for this event, or null if
	 *                            there is no handback object.
	 *
	 * @exception  NullPointerException
	 *     (unchecked exception) Thrown if <CODE>theSource</CODE> is null. 
	 */
	public PrintEvent
		(PrintService theSource,
		 long theEventID,
		 long theSequenceNumber,
		 MarshalledObject theHandbackObject)
		{
		super
			(verify (theSource),
			 theEventID,
			 theSequenceNumber,
			 theHandbackObject);
		}

	private static PrintService verify
		(PrintService theSource)
		{
		if (theSource == null)
			{
			throw new NullPointerException
				("net.jini.print.event.PrintEvent.PrintEvent(): theSource is null");
			}
		return theSource;
		}

// Exported operations.

	/**
	 * Determine the Print Service that reported this print event (i.e., the 
	 * event source). 
	 *
	 * @return  Print Service object.
	 */
	public PrintService getPrintService()
		{
		return (PrintService) getSource();
		}

	}