/*
* Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.sound.sampled;
The LineEvent 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 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. Although this class implements Serializable, attempts to
serialize a LineEvent object will fail.
Author: Kara Kytle See Also: Since: 1.3 @serial exclude
/**
* 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
*
* @see Line
* @see LineListener#update
* @since 1.3
*
* @serial exclude
*/
public class LineEvent extends java.util.EventObject {
// INSTANCE VARIABLES
The kind of line event (OPEN, CLOSE,
START, or STOP).
See Also: - getType
@serial
/**
* 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 START and STOP. 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 AudioSystem.NOT_SPECIFIED. See Also: @serial
/**
* 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.
Params: - line – the source of this event
- type – the event type (
OPEN, CLOSE, START, or STOP) - position – the number of sample frames that the line had already processed when the event occurred, or
AudioSystem.NOT_SPECIFIED
Throws: - IllegalArgumentException – if
line is
null.
/**
* 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.
Returns: the line responsible for this event
/**
* 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.
Returns: this event's type (Type.OPEN, Type.CLOSE, Type.START, or Type.STOP)
/**
* 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.
Note that this field is relevant only to certain events generated by
data lines, such as START and STOP. 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 AudioSystem.NOT_SPECIFIED.
Returns: the line's position as a sample frame number
/**
* 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
* 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}.
*
* @return the line's position as a sample frame number
*/
/*
* $$kk: 04.20.99: note to myself: should make sure our implementation is consistent with this.
* which is a reasonable definition....
*/
public final long getFramePosition() {
return position;
}
Obtains a string representation of the event. The contents of the string may vary
between implementations of Java Sound.
Returns: a string describing the event.
/**
* Obtains a string representation of the event. The contents of the string may vary
* between implementations of Java Sound.
* @return a string describing the event.
*/
public String toString() {
String sType = "";
if (type != null) sType = type.toString()+" ";
String sLine;
if (getLine() == null) {
sLine = "null";
} else {
sLine = getLine().toString();
}
return new String(sType + "event from line " + sLine);
}
The LineEvent.Type inner class identifies what kind of event occurred on a line.
Static instances are provided for the common types (OPEN, CLOSE, START, and STOP).
See Also: - getType.getType()
/**
* The LineEvent.Type inner class identifies what kind of event occurred on a line.
* Static instances are provided for the common types (OPEN, CLOSE, START, and STOP).
*
* @see LineEvent#getType()
*/
public static class Type {
Type name.
/**
* Type name.
*/
// $$kk: 03.25.99: why can't this be final??
private /*final*/ String name;
Constructs a new event type.
Params: - name – name of the type
/**
* Constructs a new event type.
* @param name name of the type
*/
protected Type(String name) {
this.name = name;
}
//$$fb 2002-11-26: fix for 4695001: SPEC: description of equals() method contains typo
Indicates whether the specified object is equal to this event type,
returning true if the objects are identical.
Params: - obj – the reference object with which to compare
Returns: true if this event type is the same as
obj; false otherwise
/**
* Indicates whether the specified object is equal to this event type,
* returning <code>true</code> if the objects are identical.
* @param obj the reference object with which to compare
* @return <code>true</code> if this event type is the same as
* <code>obj</code>; <code>false</code> otherwise
*/
public final boolean equals(Object obj) {
return super.equals(obj);
}
Finalizes the hashcode method.
/**
* Finalizes the hashcode method.
*/
public final int hashCode() {
return super.hashCode();
}
Returns the type name as the string representation.
/**
* Returns the type name as the string representation.
*/
public String toString() {
return name;
}
// LINE EVENT TYPE DEFINES
A type of event that is sent when a line opens, reserving system
resources for itself.
See Also: - CLOSE
- Line.open
/**
* A type of event that is sent when a line opens, reserving system
* resources for itself.
* @see #CLOSE
* @see Line#open
*/
public static final Type OPEN = new Type("Open");
A type of event that is sent when a line closes, freeing the system
resources it had obtained when it was opened.
See Also: - OPEN
- Line.close
/**
* A type of event that is sent when a line closes, freeing the system
* resources it had obtained when it was opened.
* @see #OPEN
* @see Line#close
*/
public static final Type CLOSE = new Type("Close");
A type of event that is sent when a line begins to engage in active input or output of audio data in response to a start request. See Also:
/**
* A type of event that is sent when a line begins to engage in active
* input or output of audio data in response to a
* {@link DataLine#start start} request.
* @see #STOP
* @see DataLine#start
*/
public static final Type START = new Type("Start");
A type of event that is sent when a line ceases active input or output of audio data in response to a stop request, or because the end of media has been reached. See Also:
/**
* A type of event that is sent when a line ceases active input or output
* of audio data in response to a {@link DataLine#stop stop} request,
* or because the end of media has been reached.
* @see #START
* @see DataLine#stop
*/
public static final Type STOP = new Type("Stop");
/**
* A type of event that is sent when a line ceases to engage in active
* input or output of audio data because the end of media has been reached.
*/
/*
* ISSUE: we may want to get rid of this. Is JavaSound
* responsible for reporting this??
*
* [If it's decided to keep this API, the docs will need to be updated to include mention
* of EOM events elsewhere.]
*/
//public static final Type EOM = new Type("EOM");
/**
* A type of event that is sent when a line begins to engage in active
* input or output of audio data. Examples of when this happens are
* when a source line begins or resumes writing data to its mixer, and
* when a target line begins or resumes reading data from its mixer.
* @see #STOP
* @see SourceDataLine#write
* @see TargetDataLine#read
* @see DataLine#start
*/
//public static final Type ACTIVE = new Type("ACTIVE");
/**
* A type of event that is sent when a line ceases active input or output
* of audio data.
* @see #START
* @see DataLine#stop
*/
//public static final Type INACTIVE = new Type("INACTIVE");
} // class Type
} // class LineEvent