1 /*
   2  * Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.sound.sampled;
  27 
  28 import java.util.EventObject;
  29 
  30 /**
  31  * The {@code LineEvent} class encapsulates information that a line sends its
  32  * listeners whenever the line opens, closes, starts, or stops. Each of these
  33  * four state changes is represented by a corresponding type of event. A
  34  * listener receives the event as a parameter to its
  35  * {@link LineListener#update update} method. By querying the event, the
  36  * listener can learn the type of event, the line responsible for the event, and
  37  * how much data the line had processed when the event occurred.
  38  * <p>
  39  * Although this class implements Serializable, attempts to serialize a
  40  * {@code LineEvent} object will fail.
  41  *
  42  * @author Kara Kytle
  43  * @see Line
  44  * @see LineListener#update
  45  * @since 1.3
  46  *
  47  * @serial exclude
  48  */
  49 public class LineEvent extends EventObject {
  50 
  51     /**
  52      * Use serialVersionUID from JDK 1.3 for interoperability.
  53      */
  54     private static final long serialVersionUID = -1274246333383880410L;
  55 
  56     /**
  57      * The kind of line event ({@code OPEN}, {@code CLOSE}, {@code START}, or
  58      * {@code STOP}).
  59      *
  60      * @see #getType
  61      * @serial
  62      */
  63     @SuppressWarnings("serial") // Not statically typed as Serializable
  64     private final Type type;
  65 
  66     /**
  67      * The media position when the event occurred, expressed in sample frames.
  68      * Note that this field is only relevant to certain events generated by data
  69      * lines, such as {@code START} and {@code STOP}. For events generated by
  70      * lines that do not count sample frames, and for any other events for which
  71      * this value is not known, the position value should be
  72      * {@link AudioSystem#NOT_SPECIFIED}.
  73      *
  74      * @see #getFramePosition
  75      * @serial
  76      */
  77     private final long position;
  78 
  79     /**
  80      * Constructs a new event of the specified type, originating from the
  81      * specified line.
  82      *
  83      * @param  line the source of this event
  84      * @param  type the event type ({@code OPEN}, {@code CLOSE}, {@code START},
  85      *         or {@code STOP})
  86      * @param  position the number of sample frames that the line had already
  87      *         processed when the event occurred, or
  88      *         {@link AudioSystem#NOT_SPECIFIED}
  89      * @throws IllegalArgumentException if {@code line} is {@code null}
  90      */
  91     public LineEvent(Line line, Type type, long position) {
  92 
  93         super(line);
  94         this.type = type;
  95         this.position = position;
  96     }
  97 
  98     /**
  99      * Obtains the audio line that is the source of this event.
 100      *
 101      * @return the line responsible for this event
 102      */
 103     public final Line getLine() {
 104         return (Line)getSource();
 105     }
 106 
 107     /**
 108      * Obtains the event's type.
 109      *
 110      * @return this event's type ({@link Type#OPEN}, {@link Type#CLOSE},
 111      *         {@link Type#START}, or {@link Type#STOP})
 112      */
 113     public final Type getType() {
 114         return type;
 115     }
 116 
 117     /**
 118      * Obtains the position in the line's audio data when the event occurred,
 119      * expressed in sample frames. For example, if a source line had already
 120      * played back 14 sample frames at the time it was paused, the pause event
 121      * would report the line's position as 14. The next frame to be processed
 122      * would be frame number 14 using zero-based numbering, or 15 using
 123      * one-based numbering.
 124      * <p>
 125      * Note that this field is relevant only to certain events generated by data
 126      * lines, such as {@code START} and {@code STOP}. For events generated by
 127      * lines that do not count sample frames, and for any other events for which
 128      * this value is not known, the position value should be
 129      * {@link AudioSystem#NOT_SPECIFIED}.
 130      *
 131      * @return the line's position as a sample frame number
 132      */
 133     /*
 134      * $$kk: 04.20.99: note to myself: should make sure our implementation is
 135      * consistent with this.
 136      * which is a reasonable definition....
 137      */
 138     public final long getFramePosition() {
 139         return position;
 140     }
 141 
 142     /**
 143      * Returns a string representation of the event.
 144      *
 145      * @return a string representation of the event
 146      */
 147     @Override
 148     public String toString() {
 149         return String.format("%s event from line %s", type, getLine());
 150     }
 151 
 152     /**
 153      * The LineEvent.Type inner class identifies what kind of event occurred on
 154      * a line. Static instances are provided for the common types (OPEN, CLOSE,
 155      * START, and STOP).
 156      *
 157      * @see LineEvent#getType()
 158      */
 159     public static class Type {
 160 
 161         /**
 162          * Type name.
 163          */
 164         private final String name;
 165 
 166         /**
 167          * Constructs a new event type.
 168          *
 169          * @param  name name of the type
 170          */
 171         protected Type(String name) {
 172             this.name = name;
 173         }
 174 
 175         //$$fb 2002-11-26: fix for 4695001: SPEC: description of equals() method contains typo
 176 
 177         /**
 178          * Indicates whether the specified object is equal to this event type,
 179          * returning {@code true} if the objects are the same.
 180          *
 181          * @param  obj the reference object with which to compare
 182          * @return {@code true} if the specified object is equal to this event
 183          *         type; {@code false} otherwise
 184          */
 185         @Override
 186         public final boolean equals(Object obj) {
 187             return super.equals(obj);
 188         }
 189 
 190         /**
 191          * Returns a hash code value for this event type.
 192          *
 193          * @return a hash code value for this event type
 194          */
 195         @Override
 196         public final int hashCode() {
 197             return super.hashCode();
 198         }
 199 
 200         /**
 201          * Returns type's name as the string representation of the event type.
 202          *
 203          * @return a string representation of the event type
 204          */
 205         @Override
 206         public String toString() {
 207             return name;
 208         }
 209 
 210         // LINE EVENT TYPE DEFINES
 211 
 212         /**
 213          * A type of event that is sent when a line opens, reserving system
 214          * resources for itself.
 215          *
 216          * @see #CLOSE
 217          * @see Line#open
 218          */
 219         public static final Type OPEN = new Type("Open");
 220 
 221         /**
 222          * A type of event that is sent when a line closes, freeing the system
 223          * resources it had obtained when it was opened.
 224          *
 225          * @see #OPEN
 226          * @see Line#close
 227          */
 228         public static final Type CLOSE = new Type("Close");
 229 
 230         /**
 231          * A type of event that is sent when a line begins to engage in active
 232          * input or output of audio data in response to a
 233          * {@link DataLine#start start} request.
 234          *
 235          * @see #STOP
 236          * @see DataLine#start
 237          */
 238         public static final Type START = new Type("Start");
 239 
 240         /**
 241          * A type of event that is sent when a line ceases active input or
 242          * output of audio data in response to a {@link DataLine#stop stop}
 243          * request, or because the end of media has been reached.
 244          *
 245          * @see #START
 246          * @see DataLine#stop
 247          */
 248         public static final Type STOP = new Type("Stop");
 249 
 250         /**
 251          * A type of event that is sent when a line ceases to engage in active
 252          * input or output of audio data because the end of media has been
 253          * reached.
 254          */
 255         /*
 256          * ISSUE: we may want to get rid of this. Is JavaSound responsible for
 257          * reporting this??
 258          *
 259          * [If it's decided to keep this API, the docs will need to be updated
 260          * to include mention of EOM events elsewhere.]
 261          */
 262         //public static final Type EOM  = new Type("EOM");
 263 
 264         /**
 265          * A type of event that is sent when a line begins to engage in active
 266          * input or output of audio data. Examples of when this happens are when
 267          * a source line begins or resumes writing data to its mixer, and when a
 268          * target line begins or resumes reading data from its mixer.
 269          *
 270          * @see #STOP
 271          * @see SourceDataLine#write
 272          * @see TargetDataLine#read
 273          * @see DataLine#start
 274          */
 275         //public static final Type ACTIVE       = new Type("ACTIVE");
 276 
 277         /**
 278          * A type of event that is sent when a line ceases active input or
 279          * output of audio data.
 280          *
 281          * @see #START
 282          * @see DataLine#stop
 283          */
 284         //public static final Type INACTIVE     = new Type("INACTIVE");
 285     }
 286 }