src/share/classes/javax/sound/sampled/Clip.java

Print this page

        

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2014, 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

@@ -23,201 +23,197 @@
  * questions.
  */
 
 package javax.sound.sampled;
 
-import java.io.InputStream;
 import java.io.IOException;
 
 /**
- * The <code>Clip</code> interface represents a special kind of data line whose
- * audio data can be loaded prior to playback, instead of being streamed in
- * real time.
- * <p>
- * Because the data is pre-loaded and has a known length, you can set a clip
- * to start playing at any position in its audio data.  You can also create a
- * loop, so that when the clip is played it will cycle repeatedly.  Loops are
- * specified with a starting and ending sample frame, along with the number of
- * times that the loop should be played.
- * <p>
- * Clips may be obtained from a <code>{@link Mixer}</code> that supports lines
- * of this type.  Data is loaded into a clip when it is opened.
- * <p>
- * Playback of an audio clip may be started and stopped using the <code>start</code>
- * and <code>stop</code> methods.  These methods do not reset the media position;
- * <code>start</code> causes playback to continue from the position where playback
- * was last stopped.  To restart playback from the beginning of the clip's audio
- * data, simply follow the invocation of <code>{@link DataLine#stop stop}</code>
- * with setFramePosition(0), which rewinds the media to the beginning
- * of the clip.
+ * The {@code Clip} interface represents a special kind of data line whose audio
+ * data can be loaded prior to playback, instead of being streamed in real time.
+ * <p>
+ * Because the data is pre-loaded and has a known length, you can set a clip to
+ * start playing at any position in its audio data. You can also create a loop,
+ * so that when the clip is played it will cycle repeatedly. Loops are specified
+ * with a starting and ending sample frame, along with the number of times that
+ * the loop should be played.
+ * <p>
+ * Clips may be obtained from a {@link Mixer} that supports lines of this type.
+ * Data is loaded into a clip when it is opened.
+ * <p>
+ * Playback of an audio clip may be started and stopped using the
+ * {@link #start start} and {@link #stop stop} methods. These methods do not
+ * reset the media position; {@code start} causes playback to continue from the
+ * position where playback was last stopped. To restart playback from the
+ * beginning of the clip's audio data, simply follow the invocation of
+ * {@code stop} with {@code setFramePosition(0)}, which rewinds the media to the
+ * beginning of the clip.
  *
  * @author Kara Kytle
  * @since 1.3
  */
 public interface Clip extends DataLine {
 
-
     /**
      * A value indicating that looping should continue indefinitely rather than
      * complete after a specific number of loops.
+     *
      * @see #loop
      */
-    public static final int LOOP_CONTINUOUSLY = -1;
+    int LOOP_CONTINUOUSLY = -1;
 
     /**
-     * Opens the clip, meaning that it should acquire any required
-     * system resources and become operational.  The clip is opened
-     * with the format and audio data indicated.
-     * If this operation succeeds, the line is marked as open and an
-     * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched
-     * to the line's listeners.
-     * <p>
-     * Invoking this method on a line which is already open is illegal
-     * and may result in an IllegalStateException.
-     * <p>
-     * Note that some lines, once closed, cannot be reopened.  Attempts
-     * to reopen such a line will always result in a
-     * <code>{@link LineUnavailableException}</code>.
+     * Opens the clip, meaning that it should acquire any required system
+     * resources and become operational. The clip is opened with the format and
+     * audio data indicated. If this operation succeeds, the line is marked as
+     * open and an {@link LineEvent.Type#OPEN OPEN} event is dispatched to the
+     * line's listeners.
+     * <p>
+     * Invoking this method on a line which is already open is illegal and may
+     * result in an {@code IllegalStateException}.
+     * <p>
+     * Note that some lines, once closed, cannot be reopened. Attempts to reopen
+     * such a line will always result in a {@code LineUnavailableException}.
      *
      * @param format the format of the supplied audio data
      * @param data a byte array containing audio data to load into the clip
      * @param offset the point at which to start copying, expressed in
      * <em>bytes</em> from the beginning of the array
-     * @param bufferSize the number of <em>bytes</em>
-     * of data to load into the clip from the array.
-     * @throws LineUnavailableException if the line cannot be
-     * opened due to resource restrictions
-     * @throws IllegalArgumentException if the buffer size does not represent
-     * an integral number of sample frames,
-     * or if <code>format</code> is not fully specified or invalid
+     * @param  bufferSize the number of <em>bytes</em> of data to load into the
+     *         clip from the array
+     * @throws LineUnavailableException if the line cannot be opened due to
+     *         resource restrictions
+     * @throws IllegalArgumentException if the buffer size does not represent an
+     *         integral number of sample frames, or if {@code format} is not
+     *         fully specified or invalid
      * @throws IllegalStateException if the line is already open
-     * @throws SecurityException if the line cannot be
-     * opened due to security restrictions
-     *
+     * @throws SecurityException if the line cannot be opened due to security
+     *         restrictions
      * @see #close
      * @see #isOpen
      * @see LineListener
      */
-    public void open(AudioFormat format, byte[] data, int offset, int bufferSize) throws LineUnavailableException;
+    void open(AudioFormat format, byte[] data, int offset, int bufferSize)
+            throws LineUnavailableException;
 
     /**
-     * Opens the clip with the format and audio data present in the provided audio
-     * input stream.  Opening a clip means that it should acquire any required
-     * system resources and become operational.  If this operation
-     * input stream.  If this operation
-     * succeeds, the line is marked open and an
-     * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched
-     * to the line's listeners.
-     * <p>
-     * Invoking this method on a line which is already open is illegal
-     * and may result in an IllegalStateException.
-     * <p>
-     * Note that some lines, once closed, cannot be reopened.  Attempts
-     * to reopen such a line will always result in a
-     * <code>{@link LineUnavailableException}</code>.
-     *
-     * @param stream an audio input stream from which audio data will be read into
-     * the clip
-     * @throws LineUnavailableException if the line cannot be
-     * opened due to resource restrictions
-     * @throws IOException if an I/O exception occurs during reading of
-     * the stream
-     * @throws IllegalArgumentException if the stream's audio format
-     * is not fully specified or invalid
+     * Opens the clip with the format and audio data present in the provided
+     * audio input stream. Opening a clip means that it should acquire any
+     * required system resources and become operational. If this operation input
+     * stream. If this operation succeeds, the line is marked open and an
+     * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's
+     * listeners.
+     * <p>
+     * Invoking this method on a line which is already open is illegal and may
+     * result in an {@code IllegalStateException}.
+     * <p>
+     * Note that some lines, once closed, cannot be reopened. Attempts to reopen
+     * such a line will always result in a {@code LineUnavailableException}.
+     *
+     * @param  stream an audio input stream from which audio data will be read
+     *         into the clip
+     * @throws LineUnavailableException if the line cannot be opened due to
+     *         resource restrictions
+     * @throws IOException if an I/O exception occurs during reading of the
+     *         stream
+     * @throws IllegalArgumentException if the stream's audio format is not
+     *         fully specified or invalid
      * @throws IllegalStateException if the line is already open
-     * @throws SecurityException if the line cannot be
-     * opened due to security restrictions
-     *
+     * @throws SecurityException if the line cannot be opened due to security
+     *         restrictions
      * @see #close
      * @see #isOpen
      * @see LineListener
      */
-    public void open(AudioInputStream stream) throws LineUnavailableException, IOException;
+    void open(AudioInputStream stream)
+            throws LineUnavailableException, IOException;
 
     /**
      * Obtains the media length in sample frames.
-     * @return the media length, expressed in sample frames,
-     * or <code>AudioSystem.NOT_SPECIFIED</code> if the line is not open.
+     *
+     * @return the media length, expressed in sample frames, or
+     *         {@code AudioSystem.NOT_SPECIFIED} if the line is not open
      * @see AudioSystem#NOT_SPECIFIED
      */
-    public int getFrameLength();
+    int getFrameLength();
 
     /**
-     * Obtains the media duration in microseconds
-     * @return the media duration, expressed in microseconds,
-     * or <code>AudioSystem.NOT_SPECIFIED</code> if the line is not open.
+     * Obtains the media duration in microseconds.
+     *
+     * @return the media duration, expressed in microseconds, or
+     *         {@code AudioSystem.NOT_SPECIFIED} if the line is not open
      * @see AudioSystem#NOT_SPECIFIED
      */
-    public long getMicrosecondLength();
+    long getMicrosecondLength();
 
     /**
-     * Sets the media position in sample frames.  The position is zero-based;
-     * the first frame is frame number zero.  When the clip begins playing the
-     * next time, it will start by playing the frame at this position.
+     * Sets the media position in sample frames. The position is zero-based; the
+     * first frame is frame number zero. When the clip begins playing the next
+     * time, it will start by playing the frame at this position.
      * <p>
      * To obtain the current position in sample frames, use the
-     * <code>{@link DataLine#getFramePosition getFramePosition}</code>
-     * method of <code>DataLine</code>.
+     * {@link DataLine#getFramePosition getFramePosition} method of
+     * {@code DataLine}.
      *
      * @param frames the desired new media position, expressed in sample frames
      */
-    public void setFramePosition(int frames);
+    void setFramePosition(int frames);
 
     /**
      * Sets the media position in microseconds.  When the clip begins playing the
-     * next time, it will start at this position.
-     * The level of precision is not guaranteed.  For example, an implementation
-     * might calculate the microsecond position from the current frame position
-     * and the audio sample frame rate.  The precision in microseconds would
-     * then be limited to the number of microseconds per sample frame.
+     * next time, it will start at this position. The level of precision is not
+     * guaranteed. For example, an implementation might calculate the
+     * microsecond position from the current frame position and the audio sample
+     * frame rate. The precision in microseconds would then be limited to the
+     * number of microseconds per sample frame.
      * <p>
      * To obtain the current position in microseconds, use the
-     * <code>{@link DataLine#getMicrosecondPosition getMicrosecondPosition}</code>
-     * method of <code>DataLine</code>.
+     * {@link DataLine#getMicrosecondPosition getMicrosecondPosition} method of
+     * {@code DataLine}.
      *
-     * @param microseconds the desired new media position, expressed in microseconds
+     * @param  microseconds the desired new media position, expressed in
+     *         microseconds
      */
-    public void setMicrosecondPosition(long microseconds);
+    void setMicrosecondPosition(long microseconds);
 
     /**
-     * Sets the first and last sample frames that will be played in
-     * the loop.  The ending point must be greater than
-     * or equal to the starting point, and both must fall within the
-     * the size of the loaded media.  A value of 0 for the starting
-     * point means the beginning of the loaded media.  Similarly, a value of -1
-     * for the ending point indicates the last frame of the media.
+     * Sets the first and last sample frames that will be played in the loop.
+     * The ending point must be greater than or equal to the starting point, and
+     * both must fall within the the size of the loaded media. A value of 0 for
+     * the starting point means the beginning of the loaded media. Similarly, a
+     * value of -1 for the ending point indicates the last frame of the media.
+     *
      * @param start the loop's starting position, in sample frames (zero-based)
-     * @param end the loop's ending position, in sample frames (zero-based), or
-     * -1 to indicate the final frame
-     * @throws IllegalArgumentException if the requested
-     * loop points cannot be set, usually because one or both falls outside
-     * the media's duration or because the ending point is
-     * before the starting point
-     */
-    public void setLoopPoints(int start, int end);
+     * @param  end the loop's ending position, in sample frames (zero-based),
+     *         or -1 to indicate the final frame
+     * @throws IllegalArgumentException if the requested loop points cannot be
+     *         set, usually because one or both falls outside the media's
+     *         duration or because the ending point is before the starting point
+     */
+    void setLoopPoints(int start, int end);
 
     /**
-     * Starts looping playback from the current position.   Playback will
-     * continue to the loop's end point, then loop back to the loop start point
-     * <code>count</code> times, and finally continue playback to the end of
-     * the clip.
+     * Starts looping playback from the current position. Playback will continue
+     * to the loop's end point, then loop back to the loop start point
+     * {@code count} times, and finally continue playback to the end of the
+     * clip.
      * <p>
      * If the current position when this method is invoked is greater than the
-     * loop end point, playback simply continues to the
-     * end of the clip without looping.
+     * loop end point, playback simply continues to the end of the clip without
+     * looping.
      * <p>
-     * A <code>count</code> value of 0 indicates that any current looping should
+     * A {@code count} value of 0 indicates that any current looping should
      * cease and playback should continue to the end of the clip.  The behavior
      * is undefined when this method is invoked with any other value during a
      * loop operation.
      * <p>
      * If playback is stopped during looping, the current loop status is
      * cleared; the behavior of subsequent loop and start requests is not
      * affected by an interrupted loop operation.
      *
      * @param count the number of times playback should loop back from the
      * loop's end position to the loop's  start position, or
-     * <code>{@link #LOOP_CONTINUOUSLY}</code> to indicate that looping should
+     *         {@link #LOOP_CONTINUOUSLY} to indicate that looping should
      * continue until interrupted
      */
-    public void loop(int count);
+    void loop(int count);
 }