Add null annotations to audio package (openhab#1174)

Signed-off-by: Wouter Born <[email protected]>

bundles/org.openhab.core.audio/src/main/java/org/eclipse/smarthome/core/audio/AudioException.java

@@ -12,47 +12,51 @@
  */
 package org.eclipse.smarthome.core.audio;
 
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
 /**
  * General purpose audio exception
  *
  * @author Harald Kuhn - Initial contribution
  * @author Kelly Davis - Modified to match discussion in #584
  */
+@NonNullByDefault
 public class AudioException extends Exception {
 
     private static final long serialVersionUID = 1L;
 
-   /**
-    * Constructs a new exception with null as its detail message.
-    */
+    /**
+     * Constructs a new exception with null as its detail message.
+     */
     public AudioException() {
         super();
     }
 
-   /**
-    * Constructs a new exception with the specified detail message and cause.
-    *
-    * @param message Detail message
-    * @param cause The cause 
-    */
-    public AudioException(String message, Throwable cause) {
+    /**
+     * Constructs a new exception with the specified detail message and cause.
+     *
+     * @param message Detail message
+     * @param cause The cause
+     */
+    public AudioException(String message, @Nullable Throwable cause) {
         super(message, cause);
     }
 
-   /**
-    * Constructs a new exception with the specified detail message.
-    *
-    * @param message Detail message
-    */
+    /**
+     * Constructs a new exception with the specified detail message.
+     *
+     * @param message Detail message
+     */
     public AudioException(String message) {
         super(message);
     }
 
-   /**
-    * Constructs a new exception with the specified cause.
-    *
-    * @param cause The cause 
-    */
+    /**
+     * Constructs a new exception with the specified cause.
+     *
+     * @param cause The cause
+     */
     public AudioException(Throwable cause) {
         super(cause);
     }

bundles/org.openhab.core.audio/src/main/java/org/eclipse/smarthome/core/audio/AudioFormat.java

@@ -14,13 +14,17 @@
 
 import java.util.Set;
 
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
 /**
  * An audio format definition
  *
  * @author Harald Kuhn - Initial contribution
  * @author Kelly Davis - Modified to match discussion in #584
  * @author Kai Kreuzer - Moved class, included constants, added toString
  */
+@NonNullByDefault
 public class AudioFormat {
 
     // generic mp3 format without any further constraints
@@ -111,36 +115,36 @@ public class AudioFormat {
     /**
      * Codec
      */
-    private final String codec;
+    private final @Nullable String codec;
 
     /**
      * Container
      */
-    private final String container;
+    private final @Nullable String container;
 
     /**
      * Big endian or little endian
      */
-    private final Boolean bigEndian;
+    private final @Nullable Boolean bigEndian;
 
     /**
      * Bit depth
      *
      * @see <a href="http://bit.ly/1OTydad">Bit Depth</a>
      */
-    private final Integer bitDepth;
+    private final @Nullable Integer bitDepth;
 
     /**
      * Bit rate
      *
      * @see <a href="http://bit.ly/1OTy5rk">Bit Rate</a>
      */
-    private final Integer bitRate;
+    private final @Nullable Integer bitRate;
 
     /**
      * Sample frequency
      */
-    private final Long frequency;
+    private final @Nullable Long frequency;
 
     /**
      * Constructs an instance with the specified properties.
@@ -161,8 +165,8 @@ public class AudioFormat {
      * @param bitRate The bit rate of the audio
      * @param frequency The frequency at which the audio was sampled
      */
-    public AudioFormat(String container, String codec, Boolean bigEndian, Integer bitDepth, Integer bitRate,
-            Long frequency) {
+    public AudioFormat(@Nullable String container, @Nullable String codec, @Nullable Boolean bigEndian,
+            @Nullable Integer bitDepth, @Nullable Integer bitRate, @Nullable Long frequency) {
         this.container = container;
         this.codec = codec;
         this.bigEndian = bigEndian;
@@ -176,7 +180,7 @@ public AudioFormat(String container, String codec, Boolean bigEndian, Integer bi
      *
      * @return The codec
      */
-    public String getCodec() {
+    public @Nullable String getCodec() {
         return codec;
     }
 
@@ -185,7 +189,7 @@ public String getCodec() {
      *
      * @return The container
      */
-    public String getContainer() {
+    public @Nullable String getContainer() {
         return container;
     }
 
@@ -194,7 +198,7 @@ public String getContainer() {
      *
      * @return If format is big endian
      */
-    public Boolean isBigEndian() {
+    public @Nullable Boolean isBigEndian() {
         return bigEndian;
     }
 
@@ -204,7 +208,7 @@ public Boolean isBigEndian() {
      * @see <a href="http://bit.ly/1OTydad">Bit Depth</a>
      * @return Bit depth
      */
-    public Integer getBitDepth() {
+    public @Nullable Integer getBitDepth() {
         return bitDepth;
     }
 
@@ -214,7 +218,7 @@ public Integer getBitDepth() {
      * @see <a href="http://bit.ly/1OTy5rk">Bit Rate</a>
      * @return Bit rate
      */
-    public Integer getBitRate() {
+    public @Nullable Integer getBitRate() {
         return bitRate;
     }
 
@@ -223,7 +227,7 @@ public Integer getBitRate() {
      *
      * @return The frequency
      */
-    public Long getFrequency() {
+    public @Nullable Long getFrequency() {
         return frequency;
     }
 
@@ -233,7 +237,7 @@ public Long getFrequency() {
      * This AudioFormat is compatible with the passed AudioFormat if both have
      * the same value for all non-null members of this instance.
      */
-    public boolean isCompatible(AudioFormat audioFormat) {
+    public boolean isCompatible(@Nullable AudioFormat audioFormat) {
         if (audioFormat == null) {
             return false;
         }
@@ -265,7 +269,7 @@ public boolean isCompatible(AudioFormat audioFormat) {
      * @param outputs the supported audio formats of an audio sink
      * @return the best matching format or null, if source and sink are incompatible
      */
-    public static AudioFormat getBestMatch(Set<AudioFormat> inputs, Set<AudioFormat> outputs) {
+    public static @Nullable AudioFormat getBestMatch(Set<AudioFormat> inputs, Set<AudioFormat> outputs) {
         AudioFormat preferredFormat = getPreferredFormat(inputs);
         if (preferredFormat != null) {
             for (AudioFormat output : outputs) {
@@ -291,7 +295,7 @@ public static AudioFormat getBestMatch(Set<AudioFormat> inputs, Set<AudioFormat>
      * @return The preferred AudioFormat or null if none could be determined. A passed concrete format is preferred
      *         adding default values to an abstract AudioFormat in the passed set.
      */
-    public static AudioFormat getPreferredFormat(Set<AudioFormat> audioFormats) {
+    public static @Nullable AudioFormat getPreferredFormat(Set<AudioFormat> audioFormats) {
         // Return the first concrete AudioFormat found
         for (AudioFormat currentAudioFormat : audioFormats) {
             // Check if currentAudioFormat is abstract
@@ -387,7 +391,7 @@ public static AudioFormat getPreferredFormat(Set<AudioFormat> audioFormats) {
     }
 
     @Override
-    public boolean equals(Object obj) {
+    public boolean equals(@Nullable Object obj) {
         if (obj instanceof AudioFormat) {
             AudioFormat format = (AudioFormat) obj;
             if (!(null == getCodec() ? null == format.getCodec() : getCodec().equals(format.getCodec()))) {

bundles/org.openhab.core.audio/src/main/java/org/eclipse/smarthome/core/audio/AudioHTTPServer.java

@@ -12,6 +12,7 @@
  */
 package org.eclipse.smarthome.core.audio;
 
+import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.smarthome.core.audio.internal.AudioServlet;
 
 /**
@@ -21,6 +22,7 @@
  *
  * @author Kai Kreuzer - Initial contribution
  */
+@NonNullByDefault
 public interface AudioHTTPServer {
 
     /**

bundles/org.openhab.core.audio/src/main/java/org/eclipse/smarthome/core/audio/AudioSource.java

@@ -15,13 +15,17 @@
 import java.util.Locale;
 import java.util.Set;
 
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
 /**
  * This is an audio source, which can provide a continuous live stream of audio.
  * Its main use is for microphones and other "line-in" sources and it can be registered as a service in order to make
  * it available throughout the system.
  *
  * @author Kai Kreuzer - Initial contribution
  */
+@NonNullByDefault
 public interface AudioSource {
 
     /**
@@ -37,7 +41,7 @@ public interface AudioSource {
      * @param locale the locale to provide the label for
      * @return a localized string to be used in UIs
      */
-    String getLabel(Locale locale);
+    String getLabel(@Nullable Locale locale);
 
     /**
      * Obtain the audio formats supported by this AudioSource

bundles/org.openhab.core.audio/src/main/java/org/eclipse/smarthome/core/audio/AudioStream.java

@@ -14,6 +14,8 @@
 
 import java.io.InputStream;
 
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
 /**
  * Wrapper for a source of audio data.
  *
@@ -26,6 +28,7 @@
  * @author Kelly Davis - Modified to match discussion in #584
  * @author Kai Kreuzer - Refactored to be only a temporary instance for the stream
  */
+@NonNullByDefault
 public abstract class AudioStream extends InputStream {
 
     /**

bundles/org.openhab.core.audio/src/main/java/org/eclipse/smarthome/core/audio/ByteArrayAudioStream.java

@@ -16,16 +16,19 @@
 import java.io.IOException;
 import java.io.InputStream;
 
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
 /**
  * This is an implementation of a {@link FixedLengthAudioStream}, which is based on a simple byte array.
  *
  * @author Kai Kreuzer - Initial contribution
  */
+@NonNullByDefault
 public class ByteArrayAudioStream extends FixedLengthAudioStream {
 
-    private byte[] bytes;
-    private AudioFormat format;
-    private ByteArrayInputStream stream;
+    private final byte[] bytes;
+    private final AudioFormat format;
+    private final ByteArrayInputStream stream;
 
     public ByteArrayAudioStream(byte[] bytes, AudioFormat format) {
         this.bytes = bytes;

bundles/org.openhab.core.audio/src/main/java/org/eclipse/smarthome/core/audio/FileAudioStream.java

@@ -19,6 +19,7 @@
 import java.io.InputStream;
 
 import org.apache.commons.io.IOUtils;
+import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.smarthome.core.audio.utils.AudioStreamUtils;
 
 /**
@@ -28,6 +29,7 @@
  * @author Kai Kreuzer - Refactored to take a file as input
  * @author Christoph Weitkamp - Refactored use of filename extension
  */
+@NonNullByDefault
 public class FileAudioStream extends FixedLengthAudioStream {
 
     public static final String WAV_EXTENSION = "wav";

bundles/org.openhab.core.audio/src/main/java/org/eclipse/smarthome/core/audio/FixedLengthAudioStream.java

@@ -14,12 +14,15 @@
 
 import java.io.InputStream;
 
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
 /**
  * This is an {@link AudioStream}, which can provide information about its absolute length and is able to provide
  * cloned streams.
  *
  * @author Kai Kreuzer - Initial contribution
  */
+@NonNullByDefault
 public abstract class FixedLengthAudioStream extends AudioStream {
 
     /**

bundles/org.openhab.core.audio/src/main/java/org/eclipse/smarthome/core/audio/URLAudioStream.java

@@ -23,6 +23,8 @@
 import java.util.regex.Pattern;
 
 import org.apache.commons.io.IOUtils;
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
 import org.eclipse.smarthome.core.audio.utils.AudioStreamUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -35,6 +37,7 @@
  * @author Kai Kreuzer - Refactored to not require a source
  * @author Christoph Weitkamp - Refactored use of filename extension
  */
+@NonNullByDefault
 public class URLAudioStream extends AudioStream {
 
     private static final Pattern PLS_STREAM_PATTERN = Pattern.compile("^File[0-9]=(.+)$");
@@ -48,12 +51,9 @@ public class URLAudioStream extends AudioStream {
     private final InputStream inputStream;
     private String url;
 
-    private Socket shoutCastSocket;
+    private @Nullable Socket shoutCastSocket;
 
     public URLAudioStream(String url) throws AudioException {
-        if (url == null) {
-            throw new IllegalArgumentException("url must not be null!");
-        }
         this.url = url;
         this.audioFormat = new AudioFormat(AudioFormat.CONTAINER_NONE, AudioFormat.CODEC_MP3, false, 16, null, null);
         this.inputStream = createInputStream();
@@ -96,14 +96,15 @@ private InputStream createInputStream() throws AudioException {
                 // Java does not parse non-standard headers used by SHOUTCast
                 int port = streamUrl.getPort() > 0 ? streamUrl.getPort() : 80;
                 // Manipulate User-Agent to receive a stream
-                shoutCastSocket = new Socket(streamUrl.getHost(), port);
+                Socket socket = new Socket(streamUrl.getHost(), port);
+                shoutCastSocket = socket;
 
-                OutputStream os = shoutCastSocket.getOutputStream();
+                OutputStream os = socket.getOutputStream();
                 String userAgent = "WinampMPEG/5.09";
                 String req = "GET / HTTP/1.0\r\nuser-agent: " + userAgent
                         + "\r\nIcy-MetaData: 1\r\nConnection: keep-alive\r\n\r\n";
                 os.write(req.getBytes());
-                return shoutCastSocket.getInputStream();
+                return socket.getInputStream();
             } else {
                 // getInputStream() method is more error-proof than openStream(),
                 // because openStream() does openConnection().getInputStream(),