diff --git a/openvidu-java-client/src/main/java/io/openvidu/java/client/ConnectionProperties.java b/openvidu-java-client/src/main/java/io/openvidu/java/client/ConnectionProperties.java index 38903f42..a14e1607 100644 --- a/openvidu-java-client/src/main/java/io/openvidu/java/client/ConnectionProperties.java +++ b/openvidu-java-client/src/main/java/io/openvidu/java/client/ConnectionProperties.java @@ -43,14 +43,13 @@ public class ConnectionProperties { // WEBRTC private OpenViduRole role; private KurentoOptions kurentoOptions; + private List customIceServers = new ArrayList<>(); // IPCAM private String rtspUri; private Boolean adaptativeBitrate; private Boolean onlyPlayWithSubscribers; private Integer networkCache; - // External Turn Service - private List customIceServers = new ArrayList<>(); /** * Builder for {@link io.openvidu.java.client.ConnectionProperties}. @@ -231,7 +230,32 @@ public class ConnectionProperties { return this; } - // TODO: Comment + /** + * On certain type of networks, clients using default OpenVidu STUN/TURN server can not be reached it because + * firewall rules and network topologies at the client side. This method allows you to configure your + * own ICE Server for specific connections if you need it. This is usually not necessary, only it is usefull for + * OpenVidu users behind firewalls which allows traffic from/to specific ports which may need a custom + * ICE Server configuration + * + * Add an ICE Server if in your use case you need this connection to use your own ICE Server deployment. + * When the user uses this connection, it will use the specified ICE Servers defined here. + * + * The level of precedence for ICE Server configuration on every OpenVidu connection is: + *
    + *
  1. Configured ICE Server using Openvidu.setAdvancedCofiguration() at openvidu-browser.
    2. + *
  2. Configured ICE server at + * {@link io.openvidu.java.client.ConnectionProperties#customIceServers ConnectionProperties.customIceServers}
    3. + *
  3. Configured ICE Server at global configuration parameter: OPENVIDU_WEBRTC_ICE_SERVERS
    4. + *
  4. Default deployed Coturn within OpenVidu deployment
    5. + *
+ *
+ * If no value is found at level 1, level 2 will be used, and so on until level 4. + *
+ * This method is equivalent to level 2 of precedence. + *

+ * Only for + * {@link io.openvidu.java.client.ConnectionType#WEBRTC} + */ public Builder addCustomIceServer(IceServerProperties iceServerProperties) { this.customIceServers.add(iceServerProperties); return this; @@ -364,7 +388,15 @@ public class ConnectionProperties { return this.networkCache; } - // TODO: Comment + /** + * Returns a list of custom ICE Servers configured for this connection. + *

+ * See {@link io.openvidu.java.client.ConnectionProperties.Builder#addCustomIceServer(IceServerProperties)} for more + * information. + *

+ * Only for + * {@link io.openvidu.java.client.ConnectionType#WEBRTC} + */ public List getCustomIceServers() { return new ArrayList<>(this.customIceServers); } diff --git a/openvidu-java-client/src/main/java/io/openvidu/java/client/IceServerProperties.java b/openvidu-java-client/src/main/java/io/openvidu/java/client/IceServerProperties.java index 565b6a6e..a478a1fa 100644 --- a/openvidu-java-client/src/main/java/io/openvidu/java/client/IceServerProperties.java +++ b/openvidu-java-client/src/main/java/io/openvidu/java/client/IceServerProperties.java @@ -10,20 +10,35 @@ import java.util.Arrays; import java.util.HashSet; import java.util.Set; +/** + * See + * {@link io.openvidu.java.client.ConnectionProperties.Builder#addCustomIceServer(IceServerProperties)} + */ public class IceServerProperties { private String url; private String username; private String credential; + /** + * Returns the defined ICE Server url for this {@link IceServerProperties} object. + */ public String getUrl() { return url; } + /** + * Returns the Username to be used for TURN connections at the defined {@link IceServerProperties#getUrl()} + * and {@link IceServerProperties#getCredential()} for this {@link IceServerProperties} object. + */ public String getUsername() { return username; } + /** + * Returns the credential to be used for TURN connections at the defined {@link IceServerProperties#getUrl()} + * and {@link IceServerProperties#getUsername()} for this {@link IceServerProperties} object. + */ public String getCredential() { return credential; } @@ -35,9 +50,7 @@ public class IceServerProperties { } /** - * Ice server properties following RTCIceServers format: - * https://developer.mozilla.org/en-US/docs/Web/API/RTCIceServer/urls - * @return + * @hidden */ public JsonObject toJson() { JsonObject json = new JsonObject(); @@ -51,28 +64,56 @@ public class IceServerProperties { return json; } + /** + * Builder for {@link IceServerProperties} + */ public static class Builder { private String url; private String username; private String credential; + /** + * Set the url for the ICE Server you want to use. + * It should follow a valid format: + * + */ public IceServerProperties.Builder url(String url) { this.url = url; return this; } + /** + * Set a username for the ICE Server you want to use. + * This parameter should be defined only for TURN, not for STUN ICE Servers. + */ public IceServerProperties.Builder username(String userName) { this.username = userName; return this; } + /** + * Set a credential for the ICE Server you want to use. + * This parameter should be defined only for TURN, not for STUN ICE Servers. + */ public IceServerProperties.Builder credential(String credential) { this.credential = credential; return this; } + /** + * Builder for {@link io.openvidu.java.client.RecordingProperties} + * @throws IllegalArgumentException if the defined properties does not follows + * common STUN/TURN RFCs: + * + */ public IceServerProperties build() throws IllegalArgumentException { if (this.url == null) { throw new IllegalArgumentException("External turn url cannot be null"); @@ -91,10 +132,6 @@ public class IceServerProperties { return new IceServerProperties(this.url, this.username, this.credential); } - /** Parsing Turn Stun Uri based on: - * - https://datatracker.ietf.org/doc/html/rfc7065#section-3.1 - * - https://datatracker.ietf.org/doc/html/rfc7064#section-3.1 - */ private void checkValidStunTurn(String uri) throws IllegalArgumentException { final String TCP_TRANSPORT_SUFFIX = "?transport=tcp"; final String UDP_TRANSPORT_SUFFIX = "?transport=udp";