1 /*
2 * Copyright (c) 1999, 2003, 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 /**
29 * The <code>LineEvent</code> class encapsulates information that a line
30 * sends its listeners whenever the line opens, closes, starts, or stops.
31 * Each of these four state changes is represented by a corresponding
32 * type of event. A listener receives the event as a parameter to its
33 * {@link LineListener#update update} method. By querying the event,
34 * the listener can learn the type of event, the line responsible for
35 * the event, and how much data the line had processed when the event occurred.
36 *
37 * <p>Although this class implements Serializable, attempts to
38 * serialize a <code>LineEvent</code> object will fail.
39 *
40 * @author Kara Kytle
41 *
42 * @see Line
43 * @see LineListener#update
44 * @since 1.3
45 *
46 * @serial exclude
47 */
48 public class LineEvent extends java.util.EventObject {
49
50 // INSTANCE VARIABLES
51
52 /**
53 * The kind of line event (<code>OPEN</code>, <code>CLOSE</code>,
54 * <code>START</code>, or <code>STOP</code>).
55 * @see #getType
56 * @serial
57 */
58 private final Type type;
59
60 /**
61 * The media position when the event occurred, expressed in sample frames.
62 * Note that this field is only relevant to certain events generated by
63 * data lines, such as <code>START</code> and <code>STOP</code>. For
64 * events generated by lines that do not count sample frames, and for any
65 * other events for which this value is not known, the position value
66 * should be {@link AudioSystem#NOT_SPECIFIED}.
67 * @serial
68 * @see #getFramePosition
69 */
70 private final long position;
71
72
73 /**
74 * Constructs a new event of the specified type, originating from the specified line.
75 * @param line the source of this event
76 * @param type the event type (<code>OPEN</code>, <code>CLOSE</code>, <code>START</code>, or <code>STOP</code>)
77 * @param position the number of sample frames that the line had already processed when the event occurred,
78 * or {@link AudioSystem#NOT_SPECIFIED}
79 *
80 * @throws IllegalArgumentException if <code>line</code> is
81 * <code>null</code>.
82 */
83 public LineEvent(Line line, Type type, long position) {
84
85 super(line);
86 this.type = type;
87 this.position = position;
88 }
89
90 /**
91 * Obtains the audio line that is the source of this event.
92 * @return the line responsible for this event
93 */
94 public final Line getLine() {
95
96 return (Line)getSource();
97 }
98
99
100 /**
101 * Obtains the event's type.
102 * @return this event's type ({@link Type#OPEN}, {@link Type#CLOSE},
103 * {@link Type#START}, or {@link Type#STOP})
104 */
105 public final Type getType() {
106
107 return type;
108 }
109
110 /**
111 * Obtains the position in the line's audio data when the event occurred, expressed in sample frames.
112 * For example, if a source line had already played back 14 sample frames at the time it was
113 * paused, the pause event would report the line's position as 14. The next frame to be processed
114 * would be frame number 14 using zero-based numbering, or 15 using one-based numbering.
115 * <p>
116 * Note that this field is relevant only to certain events generated by
117 * data lines, such as <code>START</code> and <code>STOP</code>. For
118 * events generated by lines that do not count sample frames, and for any
119 * other events for which this value is not known, the position value
120 * should be {@link AudioSystem#NOT_SPECIFIED}.
121 *
122 * @return the line's position as a sample frame number
123 */
124 /*
125 * $$kk: 04.20.99: note to myself: should make sure our implementation is consistent with this.
126 * which is a reasonable definition....
127 */
128 public final long getFramePosition() {
129
130 return position;
131 }
132
133 /**
134 * Obtains a string representation of the event. The contents of the string may vary
135 * between implementations of Java Sound.
136 * @return a string describing the event.
137 */
138 public String toString() {
139 String sType = "";
140 if (type != null) sType = type.toString()+" ";
141 String sLine;
142 if (getLine() == null) {
143 sLine = "null";
144 } else {
145 sLine = getLine().toString();
146 }
147 return new String(sType + "event from line " + sLine);
148 }
149
150
151 /**
152 * The LineEvent.Type inner class identifies what kind of event occurred on a line.
153 * Static instances are provided for the common types (OPEN, CLOSE, START, and STOP).
154 *
155 * @see LineEvent#getType()
156 */
157 public static class Type {
158
159
160 /**
161 * Type name.
162 */
163 // $$kk: 03.25.99: why can't this be final??
164 private /*final*/ String name;
165
166 /**
167 * Constructs a new event type.
168 * @param name name of the type
169 */
170 protected Type(String name) {
171 this.name = name;
172 }
173
174
175 //$$fb 2002-11-26: fix for 4695001: SPEC: description of equals() method contains typo
176 /**
177 * Indicates whether the specified object is equal to this event type,
178 * returning <code>true</code> if the objects are identical.
179 * @param obj the reference object with which to compare
180 * @return <code>true</code> if this event type is the same as
181 * <code>obj</code>; <code>false</code> otherwise
182 */
183 public final boolean equals(Object obj) {
184 return super.equals(obj);
185 }
186
187
188 /**
189 * Finalizes the hashcode method.
190 */
191 public final int hashCode() {
192 return super.hashCode();
193 }
194
195
196 /**
197 * Returns the type name as the string representation.
198 */
199 public String toString() {
200 return name;
201 }
202
203
204 // LINE EVENT TYPE DEFINES
205
206 /**
207 * A type of event that is sent when a line opens, reserving system
208 * resources for itself.
209 * @see #CLOSE
210 * @see Line#open
211 */
212 public static final Type OPEN = new Type("Open");
213
214
215 /**
216 * A type of event that is sent when a line closes, freeing the system
217 * resources it had obtained when it was opened.
218 * @see #OPEN
219 * @see Line#close
220 */
221 public static final Type CLOSE = new Type("Close");
222
223
224 /**
225 * A type of event that is sent when a line begins to engage in active
226 * input or output of audio data in response to a
227 * {@link DataLine#start start} request.
228 * @see #STOP
229 * @see DataLine#start
230 */
231 public static final Type START = new Type("Start");
232
233
234 /**
235 * A type of event that is sent when a line ceases active input or output
236 * of audio data in response to a {@link DataLine#stop stop} request,
237 * or because the end of media has been reached.
238 * @see #START
239 * @see DataLine#stop
240 */
241 public static final Type STOP = new Type("Stop");
242
243
244 /**
245 * A type of event that is sent when a line ceases to engage in active
246 * input or output of audio data because the end of media has been reached.
247 */
248 /*
249 * ISSUE: we may want to get rid of this. Is JavaSound
250 * responsible for reporting this??
251 *
252 * [If it's decided to keep this API, the docs will need to be updated to include mention
253 * of EOM events elsewhere.]
254 */
255 //public static final Type EOM = new Type("EOM");
256
257
258 /**
259 * A type of event that is sent when a line begins to engage in active
260 * input or output of audio data. Examples of when this happens are
261 * when a source line begins or resumes writing data to its mixer, and
262 * when a target line begins or resumes reading data from its mixer.
263 * @see #STOP
264 * @see SourceDataLine#write
265 * @see TargetDataLine#read
266 * @see DataLine#start
267 */
268 //public static final Type ACTIVE = new Type("ACTIVE");
269
270
271 /**
272 * A type of event that is sent when a line ceases active input or output
273 * of audio data.
274 * @see #START
275 * @see DataLine#stop
276 */
277 //public static final Type INACTIVE = new Type("INACTIVE");
278
279 } // class Type
280
281 } // class LineEvent