LineEvent


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