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 private static final long serialVersionUID = -1274246333383880410L;
52
53 /**
54 * The kind of line event ({@code OPEN}, {@code CLOSE}, {@code START}, or
55 * {@code STOP}).
56 *
57 * @serial
58 * @see #getType
59 */
60 private final Type type;
61
62 /**
63 * The media position when the event occurred, expressed in sample frames.
64 * Note that this field is only relevant to certain events generated by data
65 * lines, such as {@code START} and {@code STOP}. For events generated by
66 * lines that do not count sample frames, and for any other events for which
67 * this value is not known, the position value should be
68 * {@link AudioSystem#NOT_SPECIFIED}.
69 *
70 * @serial
71 * @see #getFramePosition
72 */
73 private final long position;
74
75 /**
76 * Constructs a new event of the specified type, originating from the
77 * specified line.
78 *
79 * @param line the source of this event
80 * @param type the event type ({@code OPEN}, {@code CLOSE}, {@code START},
81 * or {@code STOP})
82 * @param position the number of sample frames that the line had already
83 * processed when the event occurred, or
84 * {@link AudioSystem#NOT_SPECIFIED}
85 * @throws IllegalArgumentException if {@code line} is {@code null}
86 */
87 public LineEvent(Line line, Type type, long position) {
88
89 super(line);
90 this.type = type;
91 this.position = position;
170 * Type name.
171 */
172 private final String name;
173
174 /**
175 * Constructs a new event type.
176 *
177 * @param name name of the type
178 */
179 protected Type(String name) {
180 this.name = name;
181 }
182
183 //$$fb 2002-11-26: fix for 4695001: SPEC: description of equals() method contains typo
184
185 /**
186 * Indicates whether the specified object is equal to this event type,
187 * returning {@code true} if the objects are identical.
188 *
189 * @param obj the reference object with which to compare
190 * @return {@code true} if this event type is the same as {@code obj};
191 * {@code false} otherwise
192 */
193 @Override
194 public final boolean equals(Object obj) {
195 return super.equals(obj);
196 }
197
198 /**
199 * Finalizes the hashcode method.
200 */
201 @Override
202 public final int hashCode() {
203 return super.hashCode();
204 }
205
206 /**
207 * Returns the type name as the string representation.
208 */
209 @Override
210 public String toString() {
211 return name;
212 }
213
214 // LINE EVENT TYPE DEFINES
215
216 /**
217 * A type of event that is sent when a line opens, reserving system
218 * resources for itself.
219 *
220 * @see #CLOSE
221 * @see Line#open
222 */
223 public static final Type OPEN = new Type("Open");
224
225 /**
226 * A type of event that is sent when a line closes, freeing the system
227 * resources it had obtained when it was opened.
236 * input or output of audio data in response to a
237 * {@link DataLine#start start} request.
238 *
239 * @see #STOP
240 * @see DataLine#start
241 */
242 public static final Type START = new Type("Start");
243
244 /**
245 * A type of event that is sent when a line ceases active input or
246 * output of audio data in response to a {@link DataLine#stop stop}
247 * request, or because the end of media has been reached.
248 *
249 * @see #START
250 * @see DataLine#stop
251 */
252 public static final Type STOP = new Type("Stop");
253
254 /**
255 * A type of event that is sent when a line ceases to engage in active
256 * input or output of audio data because the end of media has been reached.
257 */
258 /*
259 * ISSUE: we may want to get rid of this. Is JavaSound
260 * responsible for reporting this??
261 *
262 * [If it's decided to keep this API, the docs will need to be updated to include mention
263 * of EOM events elsewhere.]
264 */
265 //public static final Type EOM = new Type("EOM");
266
267 /**
268 * A type of event that is sent when a line begins to engage in active
269 * input or output of audio data. Examples of when this happens are
270 * when a source line begins or resumes writing data to its mixer, and
271 * when a target line begins or resumes reading data from its mixer.
272 * @see #STOP
273 * @see SourceDataLine#write
274 * @see TargetDataLine#read
275 * @see DataLine#start
276 */
277 //public static final Type ACTIVE = new Type("ACTIVE");
278
279 /**
280 * A type of event that is sent when a line ceases active input or output
281 * of audio data.
282 * @see #START
283 * @see DataLine#stop
284 */
285 //public static final Type INACTIVE = new Type("INACTIVE");
286 }
287 }
|
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 private final Type type;
64
65 /**
66 * The media position when the event occurred, expressed in sample frames.
67 * Note that this field is only relevant to certain events generated by data
68 * lines, such as {@code START} and {@code STOP}. For events generated by
69 * lines that do not count sample frames, and for any other events for which
70 * this value is not known, the position value should be
71 * {@link AudioSystem#NOT_SPECIFIED}.
72 *
73 * @see #getFramePosition
74 * @serial
75 */
76 private final long position;
77
78 /**
79 * Constructs a new event of the specified type, originating from the
80 * specified line.
81 *
82 * @param line the source of this event
83 * @param type the event type ({@code OPEN}, {@code CLOSE}, {@code START},
84 * or {@code STOP})
85 * @param position the number of sample frames that the line had already
86 * processed when the event occurred, or
87 * {@link AudioSystem#NOT_SPECIFIED}
88 * @throws IllegalArgumentException if {@code line} is {@code null}
89 */
90 public LineEvent(Line line, Type type, long position) {
91
92 super(line);
93 this.type = type;
94 this.position = position;
173 * Type name.
174 */
175 private final String name;
176
177 /**
178 * Constructs a new event type.
179 *
180 * @param name name of the type
181 */
182 protected Type(String name) {
183 this.name = name;
184 }
185
186 //$$fb 2002-11-26: fix for 4695001: SPEC: description of equals() method contains typo
187
188 /**
189 * Indicates whether the specified object is equal to this event type,
190 * returning {@code true} if the objects are identical.
191 *
192 * @param obj the reference object with which to compare
193 * @return {@code true} if this event type is the same as the
194 * {@code obj} argument; {@code false} otherwise
195 */
196 @Override
197 public final boolean equals(Object obj) {
198 return super.equals(obj);
199 }
200
201 /**
202 * Returns a hash code value for this event type.
203 *
204 * @return a hash code value for this event type
205 */
206 @Override
207 public final int hashCode() {
208 return super.hashCode();
209 }
210
211 /**
212 * Returns the type name as the string representation.
213 *
214 * @return the type name as the string representation
215 */
216 @Override
217 public String toString() {
218 return name;
219 }
220
221 // LINE EVENT TYPE DEFINES
222
223 /**
224 * A type of event that is sent when a line opens, reserving system
225 * resources for itself.
226 *
227 * @see #CLOSE
228 * @see Line#open
229 */
230 public static final Type OPEN = new Type("Open");
231
232 /**
233 * A type of event that is sent when a line closes, freeing the system
234 * resources it had obtained when it was opened.
243 * input or output of audio data in response to a
244 * {@link DataLine#start start} request.
245 *
246 * @see #STOP
247 * @see DataLine#start
248 */
249 public static final Type START = new Type("Start");
250
251 /**
252 * A type of event that is sent when a line ceases active input or
253 * output of audio data in response to a {@link DataLine#stop stop}
254 * request, or because the end of media has been reached.
255 *
256 * @see #START
257 * @see DataLine#stop
258 */
259 public static final Type STOP = new Type("Stop");
260
261 /**
262 * A type of event that is sent when a line ceases to engage in active
263 * input or output of audio data because the end of media has been
264 * reached.
265 */
266 /*
267 * ISSUE: we may want to get rid of this. Is JavaSound responsible for
268 * reporting this??
269 *
270 * [If it's decided to keep this API, the docs will need to be updated
271 * to include mention of EOM events elsewhere.]
272 */
273 //public static final Type EOM = new Type("EOM");
274
275 /**
276 * A type of event that is sent when a line begins to engage in active
277 * input or output of audio data. Examples of when this happens are when
278 * a source line begins or resumes writing data to its mixer, and when a
279 * target line begins or resumes reading data from its mixer.
280 *
281 * @see #STOP
282 * @see SourceDataLine#write
283 * @see TargetDataLine#read
284 * @see DataLine#start
285 */
286 //public static final Type ACTIVE = new Type("ACTIVE");
287
288 /**
289 * A type of event that is sent when a line ceases active input or
290 * output of audio data.
291 *
292 * @see #START
293 * @see DataLine#stop
294 */
295 //public static final Type INACTIVE = new Type("INACTIVE");
296 }
297 }
|