Edits to Javadoc comments.

Author: jeffswartz

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

@@ -14,29 +14,29 @@ public class Archive {
      */
     public enum Status {
         /**
-         * The archive file is AVAILABLE for download from the OpenTok cloud. You can get the URL of
+         * The archive file is available for download from the OpenTok cloud. You can get the URL of
          * the download file by calling the {@link Archive#getUrl} method.
          */
         AVAILABLE,
         /**
-         * The archive file has been DELETED.
+         * The archive file has been deleted.
          */
         DELETED,
         /**
-         * The recording of the archive FAILED.
+         * The recording of the archive failed.
          */
         FAILED,
         /**
-         * The archive recording has STARTED and is in progress.
+         * The archive recording has started and is in progress.
          */
         STARTED,
         /**
-         * The archive recording has STOPPED, but the file is not AVAILABLE.
+         * The archive recording has stopped, but the file is not available.
          */
         STOPPED,
         /**
-         * The archive file is AVAILABLE at the target S3 bucket you specified using the
-         * REST API.
+         * The archive file is available at the target S3 bucket you at the
+         * <a href="https://dashboard.tokbox.com">OpenTok dashboard</a>.
          */
         UPLOADED;
 

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

@@ -55,8 +55,8 @@ public class OpenTok {
     /**
      * Creates an OpenTokSDK object.
      *
-     * @param apiKey Your OpenTok API key. (See the <a href="https://dashboard.tokbox.com">OpenTok dashboard</a>
-     * page)
+     * @param apiKey Your OpenTok API key. (See the <a href="https://dashboard.tokbox.com">OpenTok
+     * dashboard</a> page.)
      * @param apiSecret Your OpenTok API secret. (See the <a href="https://dashboard.tokbox.com">OpenTok dashboard</a>
      * page)
      */
@@ -73,33 +73,15 @@ public OpenTok(int apiKey, String apiSecret, String apiUrl) {
     }
 
     /**
-     * Creates a token for connecting to an OpenTok session. In order to authenticate a user connecting to an OpenTok session
-     * that user must pass an authentication token along with the API key.
-     * The following Java code example shows how to obtain a token:
-     * <p>
-     * <pre>
-     * import com.opentok.api.OpenTokSDK;
-     *
-     * class Test {
-     *     public static void main(String argv[]) throws OpenTokException {
-     *         int API_KEY = 0; // Replace with your OpenTok API key (see http://dashboard.tokbox.com).
-     *         String API_SECRET = ""; // Replace with your OpenTok API secret.
-     *         OpenTokSDK sdk = new OpenTokSDK(API_KEY, API_SECRET);
-     *
-     *         //Generate a basic session. Or you could use an existing session ID.
-     *         String sessionId = System.out.println(sdk.createSession());
-     *
-     *         String token = sdk.generateToken(sessionId);
-     *         System.out.println(token);
-     *     }
-     * }
-     * </pre>
+     * Creates a token for connecting to an OpenTok session. In order to authenticate a user
+     * connecting to an OpenTok session, the client passes a token when connecting to the session.
      * <p>
-     * The following Java code example shows how to obtain a token that has a role of "subscriber" and that has
-     * a connection metadata string:
+     * The following example shows how to obtain a token that has a role of "subscriber" and
+     * that has a connection metadata string:
      * <p>
      * <pre>
      * import com.opentok.Role;
+     * import com.opentok.TokenOptions;
      *
      * class Test {
      *     public static void main(String argv[]) throws OpenTokException {
@@ -116,37 +98,27 @@ public OpenTok(int apiKey, String apiSecret, String apiUrl) {
      *         // Use the Role value appropriate for the user.
      *         String role = Role.SUBSCRIBER;
      *
-     *         // Generate a token.
-     *         String token = sdk.generateToken(sessionId, Role.PUBLISHER, null, connectionMetadata);
+     *         // Generate a token:
+     *         TokenOptions options = new TokenOptions.Buider().role(role).data(connectionMetadata).build();
+     *         String token = sdk.generateToken(sessionId, options);
      *         System.out.println(token);
      *     }
      * }
      * </pre>
      * <p>
-     * For testing, you can also use the <a href="https://dashboard.tokbox.com/projects">OpenTok dashboard</a>
-     * page to generate test tokens.
+     * For testing, you can also use the <a href="https://dashboard.tokbox.com/projects">OpenTok
+     * dashboard</a> page to generate test tokens.
      *
      * @param sessionId The session ID corresponding to the session to which the user will connect.
      *
-     * @param role Each role defines a set of permissions granted to the token.
-     * Valid values are defined in the Role class:
-     *
-     *   * `SUBSCRIBER` &mdash; A subscriber can only subscribe to streams.</li>
-     *
-     *   * `PUBLISHER` &mdash; A publisher can publish streams, subscribe to streams, and signal.
-     *     (This is the default value if you do not specify a value for the `role` parameter.)</li>
-     *
-     *   * `MODERATOR` &mdash; In addition to the privileges granted to a publisher, a moderator
-     *     can call the `forceUnpublish()` and `forceDisconnect()` method of the
-     *     Session object.</li>
-     *
-     * @param expireTime The expiration time, in seconds, since the UNIX epoch. Pass in 0 to use
-     * the default expiration time of 24 hours after the token creation time. The maximum expiration
-     * time is 30 days after the creation time.
+     * @param tokenOptions This TokenOptions object defines options for the token.
+     * These include the following:
      *
-     * @param connectionData A string containing metadata describing the end-user. For example, you can pass the
-     * user ID, name, or other data describing the end-user. The length of the string is limited to 1000 characters.
-     * This data cannot be updated once it is set.
+     * <ul>
+     *    <li>The role of the token (subscriber, publisher, or moderator)</li>
+     *    <li>The expiration time of the token</li>
+     *    <li>Connection data describing the end-user</li>
+     * </ul>
      *
      * @return The token string.
      */
@@ -170,49 +142,68 @@ public String generateToken(String sessionId, TokenOptions tokenOptions) throws
         return session.generateToken(tokenOptions);
     }
 
-    public String generateToken(String sessionId) throws OpenTokException {
-        return generateToken(sessionId, new TokenOptions.Builder().build());
-    }
-
     /**
-     * Creates a new OpenTok session and returns the session ID, which uniquely identifies the session.
-     * <p>
-     * For example, when using the OpenTok JavaScript library,
-     * use the session ID in JavaScript on the page that you serve to the client. The JavaScript will use this
-     * value when calling the <a href="http://tokbox.com/opentok/libraries/client/js/reference/Session.html#connect">connect()</a>
-     * method of the Session object (to connect a user to an OpenTok session).
-     * <p>
-     * OpenTok sessions do not expire. However, authentication tokens do expire (see the
-     * {@link #generateToken(String, String, long, String)} method).
-     * Also note that sessions cannot explicitly be destroyed.
-     * <p>
-     * A session ID string can be up to 255 characters long.
+     * Creates a token for connecting to an OpenTok session, using the default settings. The default
+     * settings are the following:
+     *
+     * <ul>
+     *   <li>The token is assigned the role of publisher.</li>
+     *   <li>The token expires 24 hours after it is created.</li>
+     *   <li>The token includes no connection data.</li>
+     * </ul>
+     *
      * <p>
-     * Calling this method results in an {@link com.opentok.exception.OpenTokException} in the event of an error. Check
-     * the error message for details.
+     * The following example shows how to generate a token that has the default settings:
      * <p>
-     * The following code creates a session that uses the OpenTok Media Router:
-     *
      * <pre>
-     * import com.opentok.api.OpenTokSDK;
-     * import com.opentok.SessionProperties;
+     * import com.opentok.OpenTokSDK;
      *
      * class Test {
      *     public static void main(String argv[]) throws OpenTokException {
-     *         int API_KEY = 0; // Replace with your OpenTok API key.
+     *         int API_KEY = 0; // Replace with your OpenTok API key (see http://dashboard.tokbox.com).
      *         String API_SECRET = ""; // Replace with your OpenTok API secret.
      *         OpenTokSDK sdk = new OpenTokSDK(API_KEY, API_SECRET);
      *
-     *         String sessionId = sdk.createSession();
-     *         System.out.println(sessionId);
+     *         //Generate a basic session. Or you could use an existing session ID.
+     *         String sessionId = System.out.println(sdk.createSession().getSessionId());
+     *
+     *         String token = sdk.generateToken(sessionId);
+     *         System.out.println(token);
      *     }
      * }
      * </pre>
+     * @param sessionId The session ID corresponding to the session to which the user will connect.
+     *
+     * @return The token string.
      *
+     * @see #generateToken(String, TokenOptions)
+     */
+    public String generateToken(String sessionId) throws OpenTokException {
+        return generateToken(sessionId, new TokenOptions.Builder().build());
+    }
+
+    /**
+     * Creates a new OpenTok session and returns the session ID, which uniquely identifies
+     * the session.
+     * <p>
+     * For example, when using the OpenTok JavaScript library, use the session ID when calling the
+     * <a href="http://tokbox.com/opentok/libraries/client/js/reference/OT.html#initSession">
+     * OT.initSession()</a> method (to initialize an OpenTok session).
+     * <p>
+     * OpenTok sessions do not expire. However, authentication tokens do expire (see the
+     * {@link #generateToken(String, TokenOptions)} method). Also note that sessions cannot
+     * explicitly be destroyed.
+     * <p>
+     * A session ID string can be up to 255 characters long.
+     * <p>
+     * Calling this method results in an {@link com.opentok.exception.OpenTokException} in
+     * the event of an error. Check the error message for details.
+     * <p>
      * The following code creates a peer-to-peer session:
      *
      * <pre>
-     * import com.opentok.api.OpenTokSDK;
+     * import com.opentok.OpenTokSDK;
+     * import com.opentok.Session;
      * import com.opentok.SessionProperties;
      *
      * class Test {
@@ -221,41 +212,25 @@ public String generateToken(String sessionId) throws OpenTokException {
      *         String API_SECRET = ""; // Replace with your OpenTok API secret.
      *         OpenTokSDK sdk = new OpenTokSDK(API_KEY, API_SECRET);
      *
-     *         SessionProperties sp = new SessionProperties();
-     *         sp.p2p_preference = "enabled";
+     *         SessionProperties sp = new SessionProperties().Builder().p2p(true).build();
      *
-     *         String sessionId = sdk.createSession(null, sp);
-     *         System.out.println(sessionId);
+     *         Session session = sdk.createSession(sp);
+     *         System.out.println(session.getSessionId());
      *     }
      * }
      * </pre>
      *
      * You can also create a session using the <a href="http://www.tokbox.com/opentok/api/#session_id_production">OpenTok
      * REST API</a> or the <a href="https://dashboard.tokbox.com/projects">OpenTok dashboard</a>.
      *
-     * @param properties Defines whether the session's streams will be transmitted directly between peers or
-     * using the OpenTok media server. You can set the following possible values:
-     * <p>
+     * @param properties This SessionProperties object defines options for the session.
+     * These include the following:
+     *
      * <ul>
-     *   <li>
-     *     "disabled" (the default) &mdash; The session's streams will all be relayed using the OpenTok media server.
-     *     <br><br>
-     *     <i>In OpenTok v2:</i> The <a href="http://www.tokbox.com/blog/mantis-next-generation-cloud-technology-for-webrtc/">OpenTok
-     *     media server</a> provides benefits not AVAILABLE in peer-to-peer sessions. For example, the OpenTok media server can
-     *     decrease bandwidth usage in multiparty sessions. Also, the OpenTok server can improve the quality of the user experience
-     *     through <a href="http://www.tokbox.com/blog/quality-of-experience-and-traffic-shaping-the-next-step-with-mantis/">dynamic
-     *     traffic shaping</a>. For information on pricing, see the <a href="http://www.tokbox.com/pricing">OpenTok pricing page</a>.
-     *     <br><br>
-     *   </li>
-     *   <li>
-     *     "enabled" &mdash; The session will attempt to transmit streams directly between clients.
-     *     <br><br>
-     *     <i>In OpenTok v1:</i> Peer-to-peer streaming decreases latency and improves quality. If peer-to-peer streaming
-     *     fails (either when streams are initially published or during the course of a session), the session falls back to using
-     *     the OpenTok media server to relaying streams. (Peer-to-peer streaming uses UDP, which may be blocked by a firewall.)
-     *     For a session created with peer-to-peer streaming enabled, only two clients can connect to the session at a time.
-     *     If an additional client attempts to connect, the client dispatches an exception event.
-     *   </li>
+     *    <li>Whether the session's streams will be transmitted directly between peers or
+     *    using the OpenTok Media Router.</li>
+     *
+     *    <li>A location hint for the location of the OpenTok server to use for the session.</li>
      * </ul>
      *
      * @return A session ID for the new session. For example, when using the OpenTok JavaScript library, use this session ID
@@ -289,9 +264,32 @@ public Session createSession(SessionProperties properties) throws OpenTokExcepti
     }
 
     /**
-     * Creates an OpenTok session and returns the session ID, with the default properties. The
-     * session uses the OpenTok media server. And the session uses the first client connecting
-     * to determine the location of OpenTok server to use.
+     * Creates an OpenTok session with the default settings:
+     *
+     * <ul>
+     *     <li>The session uses the OpenTok media server.
+     *     <li>The session uses the first client connecting to determine the location of the
+     *     OpenTok server to use.</li>
+     * </ul>
+     *
+     * <p>
+     * The following example creates a session that uses the default settings:
+     *
+     * <pre>
+     * import com.opentok.OpenTokSDK;
+     * import com.opentok.SessionProperties;
+     *
+     * class Test {
+     *     public static void main(String argv[]) throws OpenTokException {
+     *         int API_KEY = 0; // Replace with your OpenTok API key.
+     *         String API_SECRET = ""; // Replace with your OpenTok API secret.
+     *         OpenTokSDK sdk = new OpenTokSDK(API_KEY, API_SECRET);
+     *
+     *         String sessionId = sdk.createSession();
+     *         System.out.println(sessionId);
+     *     }
+     * }
+     * </pre>
      *
      * @see #createSession(SessionProperties)
      */

src/main/java/com/opentok/Role.java

@@ -7,15 +7,24 @@
 
 package com.opentok;
 /**
- * Defines values for the role parameter of the <code>OpenTokSDK.generateToken()</code> method.
- *
- * @see <a href="../OpenTokSDK.html#generateToken(java.lang.String, java.lang.String)">OpenTokSDK.generateTokentoken(String, String)</a>
- * @see <a href="../OpenTokSDK.html#generateToken(java.lang.String, java.lang.String, java.lang.Long)">OpenTokSDK.generateTokentoken(String, String, Long)</a>
- * @see <a href="../OpenTokSDK.html#generateTokentoken(java.lang.String, java.lang.String, java.lang.Long, java.lang.String)">OpenTokSDK.generateTokentoken(String, String, Long, String)</a>
+ * Defines values for the role parameter of the {@link TokenOptions.Builder#role(Role role)} method.
  */
 public enum Role {
+    /**
+    *   A subscriber can only subscribe to streams.
+    */
     SUBSCRIBER,
+    /**
+    * A publisher can publish streams, subscribe to streams, and signal. (This is the default
+    * value if you do not set a roll by calling the {@link TokenOptions.Builder#role(Role role)}
+    * method.
+    */
     PUBLISHER,
+    /**
+    * In addition to the privileges granted to a publisher, in clients using the OpenTok.js 2.2
+    * library, a moderator can call the <code>forceUnpublish()</code> and
+    * <code>forceDisconnect()</code> method of the Session object.
+    */
     MODERATOR;
 
     @Override