/*
* Copyright (c) 1999, 2018, 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;
import java.util.EventObject;
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} 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} object will fail.
*
* @author Kara Kytle
* @see Line
* @see LineListener#update
* @since 1.3
*
* @serial exclude
*/
public class LineEvent extends EventObject {
Use serialVersionUID from JDK 1.3 for interoperability.
/**
* Use serialVersionUID from JDK 1.3 for interoperability.
*/
private static final long serialVersionUID = -1274246333383880410L;
The kind of line event (OPEN, CLOSE, START, or STOP). See Also: @serial
/**
* The kind of line event ({@code OPEN}, {@code CLOSE}, {@code START}, or
* {@code STOP}).
*
* @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} and {@code 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
* {@link AudioSystem#NOT_SPECIFIED}.
*
* @see #getFramePosition
* @serial
*/
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 CLOSE}, {@code START},
* or {@code STOP})
* @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} is {@code null}
*/
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} and {@code 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
* {@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
*/
@Override
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.
*/
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 the same. Params: - obj – the reference object with which to compare
Returns: true if the specified object is equal to this event type; false otherwise
/**
* Indicates whether the specified object is equal to this event type,
* returning {@code true} if the objects are the same.
*
* @param obj the reference object with which to compare
* @return {@code true} if the specified object is equal to this event
* type; {@code false} otherwise
*/
@Override
public final boolean equals(Object obj) {
return super.equals(obj);
}
Returns a hash code value for this event type.
Returns: a hash code value for this event type
/**
* Returns a hash code value for this event type.
*
* @return a hash code value for this event type
*/
@Override
public final int hashCode() {
return super.hashCode();
}
Returns the type name as the string representation.
Returns: the type name as the string representation
/**
* Returns the type name as the string representation.
*
* @return the type name as the string representation
*/
@Override
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");
}
}