JavaDoc for Outlet methods

Author: HelgeStenstrom

src/main/java/com/goxr3plus/streamplayer/stream/Outlet.java

@@ -3,6 +3,14 @@
 import javax.sound.sampled.*;
 import java.util.logging.Logger;
 
+/**
+ * Owner of the SourceDataLine which is the output line of the player.
+ * Also owns controls for the SourceDataLine.
+ * Future goal is to move all handling of the SourceDataLine to here,
+ * so that the StreamPlayer doesn't have to call {@link #getSourceDataLine()}.
+ * Another goal is to remove some of the setter and getter methods of this class,
+ * by moving all code that needs them to this class.
+ */
 public class Outlet {
 
     private final Logger logger;
@@ -12,47 +20,82 @@ public class Outlet {
     private FloatControl panControl;
     private SourceDataLine sourceDataLine;
 
+    /**
+     * @param logger used to log messages
+     */
     public Outlet(Logger logger) {
         this.logger = logger;
     }
 
 
+    /**
+     * @return the balance control of the {@link #sourceDataLine}
+     */
     public FloatControl getBalanceControl() {
         return balanceControl;
     }
 
+    /**
+     * @return the gain control of the {@link #sourceDataLine}
+     */
     public FloatControl getGainControl() {
         return gainControl;
     }
 
+    /**
+     * @return the mute control of the {@link #sourceDataLine}
+     */
     public BooleanControl getMuteControl() {
         return muteControl;
     }
 
+    /**
+     * @return the pan control of the {@link #sourceDataLine}
+     */
     public FloatControl getPanControl() {
         return panControl;
     }
 
+    /**
+     * @return the {@link #sourceDataLine}, which is the output audio signal of the player
+     */
     public SourceDataLine getSourceDataLine() {
         return sourceDataLine;
     }
 
+
+    /**
+     * @param balanceControl to be set on the {@link #sourceDataLine}
+     */
     public void setBalanceControl(FloatControl balanceControl) {
         this.balanceControl = balanceControl;
     }
 
+    /**
+     * @param gainControl to be set on the {@link #sourceDataLine}
+     */
     public void setGainControl(FloatControl gainControl) {
         this.gainControl = gainControl;
     }
 
+    /**
+     * @param muteControl to be set on the {@link #sourceDataLine}
+     */
     public void setMuteControl(BooleanControl muteControl) {
         this.muteControl = muteControl;
     }
 
+    /**
+     * @param panControl to be set on the {@link #sourceDataLine}
+     */
     public void setPanControl(FloatControl panControl) {
         this.panControl = panControl;
     }
 
+    /**
+     * @param sourceDataLine representing the audio output of the player.
+     *                       Usually taken from {@link AudioSystem#getLine(Line.Info)}.
+     */
     public void setSourceDataLine(SourceDataLine sourceDataLine) {
         this.sourceDataLine = sourceDataLine;
     }
@@ -84,6 +127,10 @@ public float getGainValue() {
         }
     }
 
+    /**
+     * Stop the {@link #sourceDataLine} in a nice way.
+     * Also nullify it. (Is that necessary?)
+     */
     void drainStopAndFreeDataLine() {
         // Free audio resources.
         if (sourceDataLine != null) {
@@ -94,34 +141,56 @@ void drainStopAndFreeDataLine() {
         }
     }
 
-     void stopAndFreeDataLine() {
+    /**
+     * Flush and close the {@link #sourceDataLine} in a nice way.
+     * Also nullify it. (Is that necessary?)
+     */
+     void flushAndFreeDataLine() {
         if (sourceDataLine != null) {
             sourceDataLine.flush();
             sourceDataLine.close();
             this.sourceDataLine = null; // TODO: Is this necessary? Will it not be garbage collected?
         }
     }
 
+    /**
+     * Flush and stop the {@link #sourceDataLine}, if it's running.
+     */
     void flushAndStop() {
         // Flush and stop the source data line
-        if (sourceDataLine != null && sourceDataLine.isRunning()) {
+        if (sourceDataLine != null && sourceDataLine.isRunning()) { // TODO: Risk for NullPointerException?
             sourceDataLine.flush();
             sourceDataLine.stop();
         }
     }
 
+    /**
+     * @return true if the {@link #sourceDataLine} is startable.
+     */
     boolean isStartable() {
         return sourceDataLine != null && !sourceDataLine.isRunning();
     }
+
+
+    /**
+     * Start the {@link #sourceDataLine}
+     */
     void start() {
         sourceDataLine.start();
     }
 
-    void open(AudioFormat audioFormat, int currentLineBufferSize) throws LineUnavailableException {
+    /**
+     * Open the {@link #sourceDataLine}.
+     * Also create controls for it.
+     * @param format The wanted audio format.
+     * @param bufferSize the desired buffer size for the {@link #sourceDataLine}
+     * @throws LineUnavailableException
+     */
+    void open(AudioFormat format, int bufferSize) throws LineUnavailableException {
         logger.info("Entered OpenLine()!:\n");
 
         if (sourceDataLine != null) {
-            sourceDataLine.open(audioFormat, currentLineBufferSize);
+            sourceDataLine.open(format, bufferSize);
 
             // opened?
             if (sourceDataLine.isOpen()) {

src/main/java/com/goxr3plus/streamplayer/stream/StreamPlayer.java

@@ -186,7 +186,7 @@ public void reset() {
 			closeStream();
 		}
 
-		outlet.stopAndFreeDataLine();
+		outlet.flushAndFreeDataLine();
 
 		// AudioFile
 		audioInputStream = null;
@@ -759,17 +759,6 @@ public long seekTo(int seconds) throws StreamPlayerException {
 		return seekBytes(bytes);
 	}
 
-//	/**
-//	 * Go to X time of the Audio
-//	 * See  {@link #seek(long)}
-//	 *
-//	 * @param pattern A string in the format (HH:MM:SS) WHERE h = HOURS , M = minutes , S = seconds
-//	 */
-//	public void seekTo(String pattern) throws StreamPlayerException {
-//		long bytes = 0;
-//
-//		seek(bytes);
-//	}
 
 	private void validateSeconds(int seconds, int durationInSeconds) {
 		if (seconds < 0) {
@@ -852,8 +841,6 @@ public Void call() {
 							// Compute position in bytes in encoded stream.
 							final int nEncodedBytes = getEncodedStreamPosition();
 
-							// System.err.println(trimBuffer[0] + " , Data Length :" + trimBuffer.length)
-
 							// Notify all registered Listeners
 							listeners.forEach(listener -> {
 								if (audioInputStream instanceof PropertiesContainer) {
@@ -1103,16 +1090,6 @@ public long getTotalBytes() {
 		return encodedAudioLength;
 	}
 
-	/**
-	 * @return
-	 */
-	// public int getByteLength() {
-	// return audioProperties == null ||
-	// !audioProperties.containsKey("audio.length.bytes") ?
-	// AudioSystem.NOT_SPECIFIED
-	// : ((Integer) audioProperties.get("audio.length.bytes")).intValue();
-	// }
-
 	/**
 	 * @return BytePosition
 	 */