Merge pull request #212 from opentok/dev

v4.6.0

Author: Mofizur Rahman

.bumpversion.cfg

@@ -1,7 +1,7 @@
 [bumpversion]
 commit = True
 tag = True
-current_version = 4.5.0
+current_version = 4.6.0
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\-(?P<release>[a-z]+))?
 serialize = 
 	{major}.{minor}.{patch}

README.md

@@ -5,16 +5,17 @@
 
 <img src="https://assets.tokbox.com/img/vonage/Vonage_VideoAPI_black.svg" height="48px" alt="Tokbox is now known as Vonage" />
 
-The OpenTok Java SDK lets you generate
-[sessions](https://tokbox.com/developer/guides/create-session/) and
-[tokens](https://tokbox.com/developer/guides/create-token/) for
-[OpenTok](http://www.tokbox.com/) applications that run on the JVM. It also includes methods for
-working with OpenTok [archives](https://tokbox.com/developer/guides/archiving),
-working with OpenTok [live streaming
-broadcasts](https://tokbox.com/developer/guides/broadcast/live-streaming/),
-working with OpenTok [SIP interconnect](https://tokbox.com/developer/guides/sip),
-[signaling OpenTok sessions from the server](https://tokbox.com/developer/guides/signaling/),
-and [disconnecting clients from sessions](https://tokbox.com/developer/guides/moderation/rest/).
+The OpenTok Java SDK provides methods for:
+
+* Generating [sessions](https://tokbox.com/developer/guides/create-session/) and
+  [tokens](https://tokbox.com/developer/guides/create-token/) for
+  [OpenTok](https://www.vonage.com/communications-apis/video/) applications
+* Working with OpenTok [archives](https://tokbox.com/developer/guides/archiving)
+* Working with OpenTok [live streaming broadcasts](https://tokbox.com/developer/guides/broadcast/live-streaming/)
+* Working with OpenTok [SIP interconnect](https://tokbox.com/developer/guides/sip)
+* [Sending signals to clients connected to a session](https://tokbox.com/developer/guides/signaling/)
+* [Disconnecting clients from sessions](https://tokbox.com/developer/guides/moderation/rest/)
+* [Forcing clients in a session to disconnect or mute published audio](https://tokbox.com/developer/guides/moderation/)
 
 ## Installation
 
@@ -366,6 +367,19 @@ The `connectionId` parameter is used to specify the connection ID of a client co
 
 For more information on the force disconnect functionality and exception codes, please see the [REST API documentation](https://tokbox.com/developer/rest/#forceDisconnect).
 
+### Forcing clients in a session to mute published audio
+
+You can force the publisher of a specific stream to stop publishing audio using the 
+`Opentok.forceMuteStream(String sessionId, String streamId)`method.
+
+You can force the publisher of all streams in a session (except for an optional list of streams)
+to stop publishing audio using the `Opentok.forceMuteAll(String sessionId, MuteAllProperties properties)`
+method. You can then disable the mute state of the session by calling the
+`Opentok.disableForceMute(String sessionId)` method.
+
+For more information, see
+[Muting the audio of streams in a session](https://tokbox.com/developer/guides/moderation/#force_mute).
+
 ### Signaling
 
 You can send signals to all the connections in a session or to a specific connection:

build.gradle

@@ -12,7 +12,7 @@ apply plugin: 'jacoco'
 
 group = 'com.tokbox'
 archivesBaseName = 'opentok-server-sdk'
-version = '4.5.0'
+version = '4.6.0'
 
 task javadocJar(type: Jar) {
     classifier = 'javadoc'

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.
@@ -20,7 +20,7 @@ public enum ArchiveMode {
     MANUAL ("manual"),
 
     /**
-     * The session is archived automatically (as soon as there are clients publishing streams
+     * The session is archived automatically (as soon as there are clients connected
      * to the session).
      */
     ALWAYS ("always");

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());