/*
 * @(#)LineEvent.java	1.27 05/11/17
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.sound.sampled;	

/**
 * The <code>LineEvent</code> class encapsulates information that a line
 * sends its listeners whenever the line opens, closes, starts, or stops.
 * Each of these four state changes is represented by a corresponding
 * type of event.  A listener receives the event as a parameter to its
 * {@link LineListener#update update} method.  By querying the event,
 * the listener can learn the type of event, the line responsible for
 * the event, and how much data the line had processed when the event occurred.
 *
 * <p>Although this class implements Serializable, attempts to
 * serialize a <code>LineEvent</code> object will fail.
 *
 * @author Kara Kytle
 * @version 1.27, 05/11/17
 *
 * @see Line
 * @see LineListener#update
 * @since 1.3
 *
 * @serial exclude
 */
public class LineEvent extends java.util.EventObject {
		
    // INSTANCE VARIABLES
	
    /**
     * The kind of line event (<code>OPEN</code>, <code>CLOSE</code>, 
     * <code>START</code>, or <code>STOP</code>).
     * @see #getType
     * @serial
     */
    private final Type type;

    /**
     * The media position when the event occurred, expressed in sample frames.
     * Note that this field is only relevant to certain events generated by
     * data lines, such as <code>START</code> and <code>STOP</code>.  For 
     * events generated by lines that do not count sample frames, and for any 
     * other events for which this value is not known, the position value 
     * should be {@link AudioSystem#NOT_SPECIFIED}.
     * @serial
     * @see #getFramePosition
     */
    private final long position;

	
    /**
     * Constructs a new event of the specified type, originating from the specified line.
     * @param line the source of this event
     * @param type the event type (<code>OPEN</code>, <code>CLOSE</code>, <code>START</code>, or <code>STOP</code>)

     * @param position the number of sample frames that the line had already processed when the event occurred,

     * or {@link AudioSystem#NOT_SPECIFIED}
     *
     * @throws IllegalArgumentException if <code>line</code> is
     * <code>null</code>.
     */
    public LineEvent(Line line, Type type, long position) {

	super(line);
	this.type = type; 
	this.position = position;
    }

    /**
     * Obtains the audio line that is the source of this event.
     * @return the line responsible for this event
     */
    public final Line getLine() {

	return (Line)getSource();
    }


    /**
     * Obtains the event's type.  
     * @return this event's type ({@link Type#OPEN}, {@link Type#CLOSE}, 
     * {@link Type#START}, or {@link Type#STOP})
     */
    public final Type getType() {

	return type;
    }

    /**
     * Obtains the position in the line's audio data when the event occurred, expressed in sample frames.  
     * For example, if a source line had already played back 14 sample frames at the time it was 
     * paused, the pause event would report the line's position as 14.  The next frame to be processed
     * would be frame number 14 using zero-based numbering, or 15 using one-based numbering.
     * <p>
     * Note that this field is relevant only to certain events generated by
     * data lines, such as <code>START</code> and <code>STOP</code>.  For