Skip to content

Commit

Permalink
Add Java client documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@cruizba
cruizba committed Feb 10, 2022
1 parent fca9c7b commit 784db2c
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 11 deletions.
40 changes: 36 additions & 4 deletions openvidu-java-client/src/main/java/io/openvidu/java/client/ConnectionProperties.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,14 +43,13 @@ public static class Builder {
// WEBRTC
private OpenViduRole role;
private KurentoOptions kurentoOptions;
private List<IceServerProperties> customIceServers = new ArrayList<>();
// IPCAM
private String rtspUri;
private Boolean adaptativeBitrate;
private Boolean onlyPlayWithSubscribers;
private Integer networkCache;

// External Turn Service
private List<IceServerProperties> customIceServers = new ArrayList<>();

/**
* Builder for {@link io.openvidu.java.client.ConnectionProperties}.
Expand Down Expand Up @@ -231,7 +230,32 @@ public Builder networkCache(int networkCache) {
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:
* <ol>
* <li>Configured ICE Server using Openvidu.setAdvancedCofiguration() at openvidu-browser.</li>
* <li><bold>Configured ICE server at
* {@link io.openvidu.java.client.ConnectionProperties#customIceServers ConnectionProperties.customIceServers}</li>
* <li>Configured ICE Server at global configuration parameter: OPENVIDU_WEBRTC_ICE_SERVERS</li>
* <li>Default deployed Coturn within OpenVidu deployment</li>
* </ol>
* <br>
* If no value is found at level 1, level 2 will be used, and so on until level 4.
* <br>
* This method is equivalent to level 2 of precedence.
* <br><br>
* <strong>Only for
* {@link io.openvidu.java.client.ConnectionType#WEBRTC}</strong>
*/
public Builder addCustomIceServer(IceServerProperties iceServerProperties) {
this.customIceServers.add(iceServerProperties);
return this;
Expand Down Expand Up @@ -364,7 +388,15 @@ public Integer getNetworkCache() {
return this.networkCache;
}

// TODO: Comment
/**
* Returns a list of custom ICE Servers configured for this connection.
* <br><br>
* See {@link io.openvidu.java.client.ConnectionProperties.Builder#addCustomIceServer(IceServerProperties)} for more
* information.
* <br><br>
* <strong>Only for
* {@link io.openvidu.java.client.ConnectionType#WEBRTC}</strong>
*/
public List<IceServerProperties> getCustomIceServers() {
return new ArrayList<>(this.customIceServers);
}
Expand Down
51 changes: 44 additions & 7 deletions openvidu-java-client/src/main/java/io/openvidu/java/client/IceServerProperties.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,35 @@
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;
}
Expand All @@ -35,9 +50,7 @@ private IceServerProperties(String url, String username, String credential) {
}

/**
* 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();
Expand All @@ -51,28 +64,56 @@ public JsonObject toJson() {
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:
* <ul>
* <li><a href="https://datatracker.ietf.org/doc/html/rfc7065#section-3.1" target="_blank">https://datatracker.ietf.org/doc/html/rfc7065#section-3.1</a></li>
* <li><a href="https://datatracker.ietf.org/doc/html/rfc7064#section-3.1" target="_blank">https://datatracker.ietf.org/doc/html/rfc7064#section-3.1</a></li>
* </ul>
*/
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:
* <ul>
* <li><a href="https://datatracker.ietf.org/doc/html/rfc7065#section-3.1" target="_blank">https://datatracker.ietf.org/doc/html/rfc7065#section-3.1</a></li>
* <li><a href="https://datatracker.ietf.org/doc/html/rfc7064#section-3.1" target="_blank">https://datatracker.ietf.org/doc/html/rfc7064#section-3.1</a></li>
* </ul>
*/
public IceServerProperties build() throws IllegalArgumentException {
if (this.url == null) {
throw new IllegalArgumentException("External turn url cannot be null");
Expand All @@ -91,10 +132,6 @@ public IceServerProperties build() throws IllegalArgumentException {
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";
Expand Down

0 comments on commit 784db2c

Please sign in to comment.