Add Experience Composer API (#227)

* Added startRender

* Added listRenders

* Deserialize listRenders response to native List

* Added stopRender & getRender

* Use enum for Render status

* Improved RenderProperties

* Experience composer docs edits ...

And other docs corrections

Co-authored-by: Jeff Swartz <jeff.swartz@vonage.com>

Author: SMadani

README.md

@@ -16,6 +16,7 @@ The OpenTok Java SDK provides methods for:
 * [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/)
+* Working with OpenTok [Experience Composers](https://tokbox.com/developer/guides/experience-composer)
 
 ## Installation
 
@@ -411,10 +412,9 @@ For more information on signaling and exception codes, refer to the documentatio
 
 You can broadcast OpenTok publishing streams to an HLS (HTTP live streaming) or
 to RTMP streams. To successfully start broadcasting a session, at least one client must be
-connected to the session. You can only have one active live streaming broadcast at a time
-for a session (however, having more than one would not be useful).
+connected to the session.
 The live streaming broadcast can target one HLS endpoint and up to five
-RTMP servers simulteneously for a session. You can only start live streaming
+RTMP servers simultaneously for a session. You can only start live streaming
 for sessions that use the OpenTok Media Router (with the media mode set to routed);
 you cannot use live streaming with sessions that have the media mode set to relayed.
 (See the [OpenTok Media Router and media
@@ -571,6 +571,25 @@ SipProperties properties = new SipProperties.Builder()
  Sip sip = opentok.dial(sessionId, token, properties);
 ```
 
+### Working with Experience Composers
+
+You can start an [Experience Composer](https://tokbox.com/developer/guides/experience-composer)
+by calling the `OpenTok.startRender(String sessionId, String token, RenderProperties properties)`
+method:
+
+```java
+RenderProperties properties = new RenderProperties.Builder()
+         .url(("http://example.com/path-to-page/")
+         .build();
+
+Render render = opentok.startRender(sessionId, token, properties);
+```
+
+You can stop an Experience Composer by calling the `OpenTok.stopRender(String renderId)` method.
+
+You can get information about Experience Composers by calling the `OpenTok.getRender(String renderId)`,
+`OpenTok.listRenders()` or `OpenTok.listRenders(Integer offset, Integer count)` methods.
+
 ## Samples
 
 There are two sample applications included with the SDK. To get going as fast as possible, clone the whole

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

@@ -15,7 +15,7 @@
 /**
  * Represents a list of archives of OpenTok session(s).
  */
-@JsonFormat(shape= JsonFormat.Shape.OBJECT)
+@JsonFormat(shape = JsonFormat.Shape.OBJECT)
 public class ArchiveList extends ArrayList<Archive> {
 
     private int totalCount;

src/main/java/com/opentok/OpenTok.java

@@ -7,6 +7,7 @@
  */
 package com.opentok;
 import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.ObjectReader;
 import com.opentok.exception.InvalidArgumentException;
@@ -39,20 +40,17 @@ public class OpenTok {
     private int apiKey;
     private String apiSecret;
     protected HttpClient client;
-    static protected ObjectReader archiveReader = new ObjectMapper()
-            .readerFor(Archive.class);
-    static protected ObjectReader archiveListReader = new ObjectMapper()
-            .readerFor(ArchiveList.class);
-    static protected ObjectReader createdSessionReader = new ObjectMapper()
-            .readerFor(CreatedSession[].class);
-    static protected ObjectReader streamReader = new ObjectMapper()
-            .readerFor(Stream.class);
-    static protected ObjectReader streamListReader = new ObjectMapper()
-            .readerFor(StreamList.class);
-    static protected ObjectReader sipReader = new ObjectMapper()
-            .readerFor(Sip.class);
-    static protected ObjectReader broadcastReader = new ObjectMapper()
-            .readerFor(Broadcast.class);
+    protected static final ObjectReader
+        archiveReader = new ObjectMapper().readerFor(Archive.class),
+        archiveListReader = new ObjectMapper().readerFor(ArchiveList.class),
+        createdSessionReader = new ObjectMapper().readerFor(CreatedSession[].class),
+        streamReader = new ObjectMapper().readerFor(Stream.class),
+        streamListReader = new ObjectMapper().readerFor(StreamList.class),
+        sipReader = new ObjectMapper().readerFor(Sip.class),
+        broadcastReader = new ObjectMapper().readerFor(Broadcast.class),
+        renderReader = new ObjectMapper().readerFor(Render.class),
+        renderListReader = new ObjectMapper().readerForListOf(Render.class);
+
     static final String defaultApiUrl = "https://api.opentok.com";
 
     /**
@@ -545,7 +543,7 @@ public void setArchiveLayout(String archiveId, ArchiveProperties properties) thr
     }
 
     /**
-     * Use this method to start a live streaming for an OpenTok session.
+     * Starts a live streaming broadcast for an OpenTok session.
      * This broadcasts the session to an HLS (HTTP live streaming) or to RTMP streams.
      * <p>
      * To successfully start broadcasting a session, at least one client must be connected to the session.
@@ -581,7 +579,7 @@ public Broadcast startBroadcast(String sessionId, BroadcastProperties properties
     }
 
     /**
-     * Use this method to stop a live broadcast of an OpenTok session.
+     * Stops a live streaming broadcast of an OpenTok session.
      * Note that broadcasts automatically stop 120 minutes after they are started.
      * <p>
      * For more information on broadcasting, see the
@@ -819,10 +817,10 @@ public StreamList listStreams(String sessionId) throws OpenTokException {
      * such as phone numbers. (The OpenTok client libraries include properties for inspecting
      * the connection data for a client connected to a session.) See the
      * <a href="https://tokbox.com/developer/guides/signaling/">Token Creation developer guide</a>.
-.    *
+     *
      * @param properties The {@link SipProperties} object defining options for the SIP call.
      *
-     * @return The  {@link Sip} object.
+     * @return The {@link Sip} object.
      */
     public Sip dial(String sessionId, String token, SipProperties properties) throws OpenTokException {
         if ((StringUtils.isEmpty(sessionId) || StringUtils.isEmpty(token) || properties == null || StringUtils.isEmpty(properties.sipUri()))) {
@@ -863,6 +861,100 @@ public void playDTMF(String sessionId, String connectionId, String dtmfDigits) t
         client.playDtmfSingle(sessionId, connectionId, dtmfDigits);
     }
 
+    /**
+     * Starts an Experience Composer render for an OpenTok session. For more information, see the
+     * <a href="https://tokbox.com/developer/guides/experience-composer">Experience Composer developer guide</a>.
+     *
+     * @param sessionId The session ID.
+     * @param properties The {@link RenderProperties} object defining the properties for the Render call.
+     *
+     * @return The {@link Render} response object.
+     *
+     * @throws OpenTokException
+     */
+    public Render startRender(String sessionId, String token, RenderProperties properties) throws OpenTokException {
+        if (StringUtils.isEmpty(sessionId) || StringUtils.isEmpty(token) || properties == null) {
+            throw new InvalidArgumentException("Session id, token and properties are all required.");
+        }
+        String render = client.startRender(sessionId, token, properties);
+        try {
+            return renderReader.readValue(render);
+        } catch (JsonProcessingException e) {
+            throw new RequestException("Exception mapping json: " + e.getMessage());
+        }
+    }
+
+    /**
+     * Gets a Render object, with details on an Experience Composer.
+     *
+     * @param renderId The ID of the Experience Composer to retrieve.
+     *
+     * @return The {@link Render} response object associated with the provided ID.
+     *
+     * @throws OpenTokException
+     */
+    public Render getRender(String renderId) throws OpenTokException {
+        if (StringUtils.isEmpty(renderId)) {
+            throw new InvalidArgumentException("Render id is required.");
+        }
+        String render = client.getRender(renderId);
+        try {
+            return renderReader.readValue(render);
+        } catch (JsonProcessingException e) {
+            throw new RequestException("Exception mapping json: " + e.getMessage());
+        }
+    }
+
+    /**
+     * Stops an Experience Composer of an OpenTok session. Note that by default
+     * Experience Composers automatically stop 2 hours after they are started. You can also set a different
+     * maxDuration value when you create the Experience Composer. When the Experience Composer ends, an event is
+     * posted to the callback URL, if you have configured one for the project.
+     *
+     * @param renderId The ID of the Experience Composer to stop.
+     *
+     * @throws OpenTokException
+     */
+    public void stopRender(String renderId) throws OpenTokException {
+        if (StringUtils.isEmpty(renderId)) {
+            throw new InvalidArgumentException("Render id is required.");
+        }
+        client.stopRender(renderId);
+    }
+
+    /**
+     * Gets a list of Render objects, representing Experience Composers associated with the
+     * OpenTok project.
+     *
+     * @return The list of {@link Render} objects.
+     *
+     * @throws OpenTokException
+     */
+    public List<Render> listRenders() throws OpenTokException {
+        return listRenders(null, null);
+    }
+
+    /**
+     * Gets a list of Render objects, representing a list of Experience Composers associated
+     * with the OpenTok project.
+     *
+     * @param offset (optional) Start offset in the list of existing Renders.
+     * @param count (optional) Number of Renders to retrieve starting at offset. Maximum 1000.
+     *
+     * @return The list of {@link Render} objects.
+     *
+     * @throws OpenTokException
+     */
+    public List<Render> listRenders(Integer offset, Integer count) throws OpenTokException {
+        String response = client.listRenders(offset, count);
+        try {
+            JsonNode root = new ObjectMapper().readTree(response);
+            return renderListReader.readValue(root.get("items"));
+        } catch (IOException e) {
+            throw new RequestException("Exception mapping json: " + e.getMessage());
+        }
+    }
+
     /**
      * Used to create an OpenTok object with advanced settings. You can set
      * the request timeout for API calls and a proxy to use for API calls.

src/main/java/com/opentok/Render.java

@@ -0,0 +1,104 @@
+/**
+ * OpenTok Java SDK
+ * 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.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Represents an Experience Composer element response.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class Render {
+	@JsonProperty private String id;
+	@JsonProperty private String sessionId;
+	@JsonProperty private String projectId;
+	@JsonProperty private long createdAt;
+	@JsonProperty private long updatedAt;
+	@JsonProperty private String url;
+	@JsonProperty private String resolution;
+	@JsonProperty private RenderStatus status;
+	@JsonProperty private String streamId;
+	@JsonProperty private String reason;
+
+	protected Render() {}
+
+	/**
+	 * The Render ID.
+	 */
+	public String getId() {
+		return id;
+	}
+
+	/**
+	 * The Session ID.
+	 */
+	public String getSessionId() {
+		return sessionId;
+	}
+
+	/**
+	 * The Project ID.
+	 */
+	public String getProjectId() {
+		return projectId;
+	}
+
+	/**
+	 * The time the Experience Composer started, expressed in milliseconds since the Unix epoch.
+	 */
+	public long getCreatedAt() {
+		return createdAt;
+	}
+
+	/**
+	 * This timestamp matches the createdAt timestamp when calling {@link OpenTok#getRender(String)}.
+	 */
+	public long getUpdatedAt() {
+		return updatedAt;
+	}
+
+	/**
+	 * A publicly reachable URL controlled by the customer and capable of generating the content to be rendered
+	 * without user intervention.
+	 */
+	public String getUrl() {
+		return url;
+	}
+
+	/**
+	 * The resolution of the Experience Composer (either "640x480", "1280x720", "480x640", or "720x1280").
+	 */
+	public String getResolution() {
+		return resolution;
+	}
+
+	/**
+	 * The status of the Experience Composer.
+	 */
+	public RenderStatus getStatus() {
+		return status;
+	}
+
+	/**
+	 * The ID of the composed stream being published. The streamId is not available when the status is "starting"
+	 * and may not be available when the status is "failed".
+	 */
+	public String getStreamId() {
+		return streamId;
+	}
+
+	/**
+	 * The reason field is only available when the status is either "stopped" or "failed". If the status is stopped,
+	 * the reason field will contain either "Max Duration Exceeded" or "Stop Requested." If the status is failed, the
+	 * reason will contain a more specific error message.
+	 */
+	public String getReason() {
+		return reason;
+	}
+}