//******************************************************************************
//
// File:    PrintJobFinishedEvent.java
// Package: net.jini.print.job
// Unit:    Class net.jini.print.job.PrintJobFinishedEvent
//
//******************************************************************************

package net.jini.print.job;

import java.io.IOException;

import java.rmi.MarshalledObject;

import javax.print.attribute.standard.JobState;

import net.jini.print.event.PrintEvent;

import net.jini.print.service.PrintService;

/**
 * Class PrintJobFinishedEvent encapsulates an event a Jini Print Service 
 * instance reports to let the client know that a Print Job has finished 
 * processing. The event reports the Print Job's final state, an instance of the 
 * {@link javax.print.attribute.standard.JobState JobState} attribute. See the 
 * description of print job processing in interface {@link PrintJob PrintJob} 
 * for further information on when print job finished events are reported. 
 * <P>
 * The Jini Print Service is <I>not</I> required to guarantee that print job 
 * finished events are delivered reliably in sequence. In other words, print job 
 * finished events may be lost or delivered out of order due to processor or 
 * network failures. 
 * <H4>Design</H4>
 * A print job finished event object contains a Print Job object. The Print Job 
 * object is stored inside the print job finished event object in marshalled 
 * form. This allows the print job finished event object to flow through 
 * intermediate event listeners without requiring those event listeners to 
 * download the Print Job object's codebase. When the print job finished event 
 * object arrives at its ultimate destination, the {@link #getPrintJob() 
 * <CODE>getPrintJob()</CODE>} method unmarshals the Print Job object, 
 * downloading the codebase if necessary at that time. 
 * <P>
 * <B>DRAFT STANDARD VERSION 1.0 (23-MAY-2000)</B>
 *
 * @author  Alan Kaminsky
 * @version 10-May-2000
 */
public class PrintJobFinishedEvent
	extends PrintEvent
	{

// Hidden data members.

	/**
	 * Print Job object (in marshalled form) to which this event pertains.
	 * @serial
	 */
	private MarshalledObject printJob;

	/**
	 * Final state of the Print Job.
	 * @serial
	 */
	private JobState finalState;
 
// Exported constructors.

	/**
	 * Constructs a new print job finished 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.
	 * @param  thePrintJob        Print Job object to which this event pertains.
	 * @param  theFinalState      Final state of the Print Job.
	 *
	 * @exception  NullPointerException
	 *     (unchecked exception) Thrown if <CODE>theSource</CODE> is null, 
	 *     <CODE>thePrintJob</CODE> is null, or <CODE>theFinalState</CODE> is 
	 *     null. 
	 * @exception  IOException
	 *     Thrown if there was an I/O error while marshalling 
	 *     <CODE>thePrintJob</CODE>, such as if it is not serializable. 
	 */
	public PrintJobFinishedEvent
		(PrintService theSource,
		 long theEventID,
		 long theSequenceNumber,
		 MarshalledObject theHandbackObject,
		 PrintJob thePrintJob,
		 JobState theFinalState)
		throws IOException
		{
		super (theSource, theEventID, theSequenceNumber, theHandbackObject);
		printJob = new MarshalledObject (verify (thePrintJob));
		finalState = verify (theFinalState);
		}

	private static PrintJob verify
		(PrintJob thePrintJob)
		{
		if (thePrintJob == null)
			{
			throw new NullPointerException
				("net.jini.print.job.PrintJobFinishedEvent.PrintJobFinishedEvent(): thePrintJob is null");
			}
		return thePrintJob;
		}

	private static JobState verify
		(JobState theFinalState)
		{
		if (theFinalState == null)
			{
			throw new NullPointerException
				("net.jini.print.job.PrintJobFinishedEvent.PrintJobFinishedEvent(): theFinalState is null");
			}
		return theFinalState;
		}

// Exported operations.

	/**
	 * Determine the Print Job to which this print job finished event pertains. 
	 *
	 * @return  Print Job object.
	 *
	 * @exception  IOException
	 *     Thrown if there was an I/O error while unmarshalling the Print Job 
	 *     object. 
	 * @exception  ClassNotFoundException
	 *     Thrown if a class needed to unmarshal the Print Job object could not 
	 *     be found. 
	 */
	public PrintJob getPrintJob()
		throws IOException, ClassNotFoundException
		{
		return (PrintJob) printJob.get();
		}

	/**
	 * Determine the final state of the Print Job to which this print job 
	 * finished event pertains. 
	 *
	 * @return  Final state.
	 */
	public JobState getFinalState()
		{
		return finalState;
		}

	}