[DEVX-5709] add selective stream for archive and broadcast (#206)

* add selective stream for archive and broadcast

* update patch to reflect api docs

* Docs edits

* Docs typo corrections

* StreamMode docs edits

* update license year

* remove patchproperties

Co-authored-by: Paul Ardeleanu <paul.ardeleanu@vonage.com>
Co-authored-by: Jeff Swartz <jeff.swartz@vonage.com>

Author: 3 people

src/main/java/com/opentok/Archive.java

@@ -1,6 +1,6 @@
 /**
  * OpenTok Java SDK
- * Copyright (C) 2021 Vonage.
+ * Copyright (C) 2022 Vonage.
  * http://www.tokbox.com
  *
  * Licensed under The MIT License (MIT). See LICENSE file for more information.
@@ -88,6 +88,26 @@ public enum OutputMode {
         }
     }
 
+    /**
+     * Defines values used in the
+     * {@link ArchiveProperties.Builder#streamMode(com.opentok.Archive.StreamMode)} method
+     * and returned by the {@link Archive#getStreamMode()} method.
+     */
+    public enum StreamMode {
+        /**
+         * Streams will be automatically included in the archive.
+         */
+        AUTO,
+        /**
+         * Streams will be included in the archive based on calls to the
+         * {@link OpenTok#addArchiveStream(String, String, boolean, boolean)} and
+         * {@link OpenTok#removeArchiveStream(String, String)} methods.
+         */
+        MANUAL;
+
+        @JsonValue public String toString() { return super.toString().toLowerCase(); }
+    }
+
     @JsonProperty private long createdAt;
     @JsonProperty private int duration = 0;
     @JsonProperty private String id;
@@ -101,6 +121,7 @@ public enum OutputMode {
     @JsonProperty private boolean hasVideo = true;
     @JsonProperty private boolean hasAudio = true;
     @JsonProperty private OutputMode outputMode = OutputMode.COMPOSED;
+    @JsonProperty private StreamMode streamMode = StreamMode.AUTO;
     @JsonProperty private String password;
     @JsonProperty private String resolution;
 
@@ -215,6 +236,14 @@ public boolean hasAudio() {
     public OutputMode getOutputMode() {
         return outputMode;
     }
+
+    /**
+     * The stream mode to used for selecting streams to be included in this archive:
+     * <code>StreamMode.AUTO</code> or <code>StreamMode.MANUAL</code>.
+     */
+    public StreamMode getStreamMode() {
+        return streamMode;
+    }
 
     /**
      * The encrypted password if an archive storage was configured to use an encryption key

src/main/java/com/opentok/ArchiveLayout.java

@@ -1,6 +1,6 @@
 /**
  * OpenTok Java SDK
- * Copyright (C) 2021 Vonage.
+ * Copyright (C) 2022 Vonage.
  * http://www.tokbox.com
  *
  * Licensed under The MIT License (MIT). See LICENSE file for more information.

src/main/java/com/opentok/ArchiveList.java

@@ -1,6 +1,6 @@
 /**
  * OpenTok Java SDK
- * Copyright (C) 2021 Vonage.
+ * Copyright (C) 2022 Vonage.
  * http://www.tokbox.com
  *
  * Licensed under The MIT License (MIT). See LICENSE file for more information.

src/main/java/com/opentok/ArchiveMode.java

@@ -1,6 +1,6 @@
 /**
  * OpenTok Java SDK
- * Copyright (C) 2021 Vonage.
+ * Copyright (C) 2022 Vonage.
  * http://www.tokbox.com
  *
  * Licensed under The MIT License (MIT). See LICENSE file for more information.

src/main/java/com/opentok/ArchiveProperties.java

@@ -1,13 +1,14 @@
 /**
  * OpenTok Java SDK
- * Copyright (C) 2021 Vonage.
+ * Copyright (C) 2022 Vonage.
  * http://www.tokbox.com
  *
  * Licensed under The MIT License (MIT). See LICENSE file for more information.
  */
 package com.opentok;
 
 import com.opentok.Archive.OutputMode;
+import com.opentok.Archive.StreamMode;
 
 import java.util.ArrayList;
 import java.util.Collection;
@@ -17,7 +18,7 @@
 
 /**
  * Defines values for the <code>properties</code> parameter of the
- * {@link OpenTok#createSession(SessionProperties)} method.
+ * {@link OpenTok#startArchive(String sessionId, ArchiveProperties properties)} method.
  *
  * @see OpenTok#createSession(com.opentok.SessionProperties properties)
  */
@@ -29,6 +30,7 @@ public class ArchiveProperties {
     private boolean hasAudio;
     private boolean hasVideo;
     private OutputMode outputMode;
+    private StreamMode streamMode;
     private ArchiveLayout layout;
 
     private ArchiveProperties(Builder builder) {
@@ -37,11 +39,12 @@ private ArchiveProperties(Builder builder) {
         this.hasAudio = builder.hasAudio;
         this.hasVideo = builder.hasVideo;
         this.outputMode = builder.outputMode;
+        this.streamMode = builder.streamMode;
         this.layout = builder.layout;
     }
 
     /**
-     * Use this class to create a ArchiveProperties object.
+     * Used to create an ArchiveProperties object.
      *
      * @see ArchiveProperties
      */
@@ -51,11 +54,11 @@ public static class Builder {
         private boolean hasAudio = true;
         private boolean hasVideo = true;
         private OutputMode outputMode = OutputMode.COMPOSED;
+        private StreamMode streamMode = StreamMode.AUTO;
         private ArchiveLayout layout = null;
-        
 
         /**
-         * Call this method to set a name to the archive.
+         * Sets a name for the archive.
          *
          * @param name The name of the archive. You can use this name to identify the archive. It is a property
          * of the Archive object, and it is a property of archive-related events in the OpenTok JavaScript SDK.
@@ -68,7 +71,7 @@ public Builder name(String name) {
         }
 
         /**
-         * Call this method to set the resolution of the archive.
+         * Sets the resolution of the archive.
          *
          * @param resolution The resolution of the archive, either "640x480" (SD, the default) or
          * "1280x720" (HD). This property only applies to composed archives. If you set this
@@ -83,7 +86,8 @@ public Builder resolution(String resolution) {
         }
 
         /**
-         * Call this method to include an audio track (<code>true</code>) or not <code>false</code>).
+         * Call this method to include an audio track (<code>true</code>, the default)
+         * or not <code>false</code>).
          *
          * @param hasAudio Whether the archive will include an audio track.
          *
@@ -93,21 +97,22 @@ public Builder hasAudio(boolean hasAudio) {
             this.hasAudio = hasAudio;
             return this;
         }
-        
+
         /**
-         * Call this method to include an video track (<code>true</code>) or not <code>false</code>).
+         * Call this method to include an video track (<code>true</code>, the default)
+         * or not <code>false</code>).
          *
-         * @param hasVideo Whether the archive will include an video track.
+         * @param hasVideo Whether the archive will include a video track.
          *
          * @return The ArchiveProperties.Builder object with the hasVideo setting.
          */
         public Builder hasVideo(boolean hasVideo) {
             this.hasVideo = hasVideo;
             return this;
-        }        
+        }
 
         /**
-         * Call this method to choose the output mode to be generated for this archive.
+         * Sets the output mode for this archive.
          *
          * @param outputMode Set to a value defined in the {@link Archive.OutputMode} enum.
          *
@@ -119,13 +124,36 @@ public Builder outputMode(OutputMode outputMode) {
         }
 
         /**
-         * Call this method to customize the layout for a composed archive
+         * Sets the stream mode for this archive.
+         *
+         * When streams are selected automatically (<code>StreamMode.AUTO</code>, the default), all
+         * streams in the session can be included in the archive. When streams are selected manually
+         * (<code>StreamMode.MANUAL</code>), you specify streams to be included based on calls
+         * to the {@link OpenTok#addArchiveStream(String, String, boolean, boolean)} and
+         * {@link OpenTok#removeArchiveStream(String, String)} methods. With
+         * <code>StreamMode.MANUAL</code>, you can specify whether a stream's audio, video, or both
+         * are included in the archive. Un both automatic and manual modes, the archive composer
+         * includes streams based on
+         * <a href="https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules">stream
+         * prioritization rules</a>.
+         *
+         * @param streamMode Set to a value defined in the {@link Archive.StreamMode} enum.
+         *
+         * @return The ArchiveProperties.Builder object with the stream mode setting.
+         */
+        public Builder streamMode(StreamMode streamMode) {
+            this.streamMode = streamMode;
+            return this;
+        }
+
+        /**
+         * Sets the layout for a composed archive.
          *
          * @param layout An object of type {@link ArchiveLayout} .
          *
          * @return The ArchiveProperties.Builder object with the output mode setting.
          */
-        public Builder layout(ArchiveLayout layout){
+        public Builder layout(ArchiveLayout layout) {
             this.layout = layout;
             return this;
         }
@@ -139,18 +167,21 @@ public ArchiveProperties build() {
             return new ArchiveProperties(this);
         }
     }
+
     /**
-     * Returns the name of the archive, which you can use to identify the archive
+     * Returns the name of the archive, which you can use to identify the archive.
      */
     public String name() {
         return name;
     }
+
     /**
-     * Returns the resolution of the archive
+     * Returns the resolution of the archive.
      */
     public String resolution() {
         return resolution;
     }
+
     /**
      * Whether the archive has a video track (<code>true</code>) or not (<code>false</code>).
      */
@@ -164,7 +195,7 @@ public boolean hasVideo() {
     public boolean hasAudio() {
         return hasAudio;
     }
-    
+
     /**
      * The output mode of the archive.
      */
@@ -173,7 +204,12 @@ public OutputMode outputMode() {
     }
 
     /**
-     * Optionally set a custom layout (composed archives only)
+     * The stream mode of the archive.
+     */
+    public StreamMode streamMode() { return streamMode; }
+
+    /**
+     * Returns the custom layout of the archive (composed archives only).
      */
     public ArchiveLayout layout() {
         return layout;
@@ -197,15 +233,19 @@ public Map<String, Collection<String>> toMap() {
         ArrayList<String> valueList = new ArrayList<String>();
         valueList.add(Boolean.toString(hasAudio));
         params.put("hasAudio", valueList);
-        
+
         valueList = new ArrayList<String>();
         valueList.add(Boolean.toString(hasVideo));
         params.put("hasVideo", valueList);
-        
+
         valueList = new ArrayList<String>();
         valueList.add(outputMode.toString());
         params.put("outputMode", valueList);
 
+        valueList = new ArrayList<String>();
+        valueList.add(streamMode.toString());
+        params.put("streamMode", valueList);
+
         if (layout != null) {
             valueList = new ArrayList<String>();
             valueList.add(layout.toString());

src/main/java/com/opentok/Broadcast.java

@@ -1,6 +1,6 @@
 /**
  * OpenTok Java SDK
- * Copyright (C) 2021 Vonage.
+ * Copyright (C) 2022 Vonage.
  * http://www.tokbox.com
  *
  * Licensed under The MIT License (MIT). See LICENSE file for more information.
@@ -10,6 +10,7 @@
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonValue;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
 import java.util.ArrayList;
@@ -21,6 +22,26 @@
  */
 @JsonIgnoreProperties(ignoreUnknown=true)
 public class Broadcast {
+    /**
+     * Defines values used in the
+     * {@link BroadcastProperties.Builder#streamMode(com.opentok.Broadcast.StreamMode)} method
+     * and returned by the {@link Broadcast#getStreamMode()} method.
+     */
+    public enum StreamMode {
+        /**
+        * Streams will be automatically included in the broadcast.
+         */
+        AUTO,
+        /**
+         * Strams will be included in the archive based on calls to the
+         * {@link OpenTok#addBroadcastStream(String, String, boolean, boolean)} and
+         * {@link OpenTok#removeBroadcastStream(String, String)} methods.
+         */
+        MANUAL;
+
+        @JsonValue
+        public String toString() { return super.toString().toLowerCase(); }
+    }
 
     @JsonProperty private String id;
     @JsonProperty private String sessionId;
@@ -29,6 +50,7 @@ public class Broadcast {
     @JsonProperty private long updatedAt;
     @JsonProperty private String resolution;
     @JsonProperty private String status;
+    @JsonProperty private StreamMode streamMode = StreamMode.AUTO;
     private List<Rtmp> rtmpList = new ArrayList<>();
     private String hls;
 
@@ -137,4 +159,12 @@ public String toString() {
         }
     }
 
+    /**
+     * The stream mode to used for selecting streams to be included in this archive:
+     * <code>StreamMode.AUTO</code> or <code>StreamMode.MANUAL</code>.
+     */
+    public StreamMode getStreamMode() {
+        return streamMode;
+    }
+
 }

src/main/java/com/opentok/BroadcastLayout.java

@@ -1,6 +1,6 @@
 /**
  * OpenTok Java SDK
- * Copyright (C) 2021 Vonage.
+ * Copyright (C) 2022 Vonage.
  * http://www.tokbox.com
  *
  * Licensed under The MIT License (MIT). See LICENSE file for more information.