com.opentok

Class OpenTok

java.lang.Object

com.opentok.OpenTok

public class OpenTok
extends java.lang.Object

Contains methods for creating OpenTok sessions, generating tokens, and working with archives.

To create a new OpenTok object, call the OpenTok constructor with your OpenTok API key and the API secret for your TokBox account. Do not publicly share your API secret. You will use it with the OpenTok constructor (only on your web server) to create OpenTok sessions.

Be sure to include the entire OpenTok server SDK on your web server.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	OpenTok.Builder

Constructor Summary

Constructors

Constructor and Description
OpenTok(int apiKey, java.lang.String apiSecret) Creates an OpenTok object.

Method Summary

Modifier and Type	Method and Description
void	close()
Session	createSession() Creates an OpenTok session with the default settings:
Session	createSession(SessionProperties properties) Creates a new OpenTok session.
void	deleteArchive(java.lang.String archiveId) Deletes an OpenTok archive.
java.lang.String	generateToken(java.lang.String sessionId) Creates a token for connecting to an OpenTok session, using the default settings.
java.lang.String	generateToken(java.lang.String sessionId, TokenOptions tokenOptions) Creates a token for connecting to an OpenTok session.
Archive	getArchive(java.lang.String archiveId) Gets an Archive object for the given archive ID.
ArchiveList	listArchives() Returns a List of Archive objects, representing archives that are both both completed and in-progress, for your API key.
ArchiveList	listArchives(int offset, int count) Returns a List of Archive objects, representing archives that are both both completed and in-progress, for your API key.
ArchiveList	listArchives(java.lang.String sessionId) Returns a List of Archive objects, representing archives that are both both completed and in-progress, for your API key.
Archive	startArchive(java.lang.String sessionId)
Archive	startArchive(java.lang.String sessionId, ArchiveProperties properties) Starts archiving an OpenTok session.
Archive	startArchive(java.lang.String sessionId, java.lang.String name)
Archive	stopArchive(java.lang.String archiveId) Stops an OpenTok archive that is being recorded.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OpenTok

public OpenTok(int apiKey,
               java.lang.String apiSecret)

Creates an OpenTok object.

Parameters:

apiKey - Your OpenTok API key. (See your TokBox account page.)

apiSecret - Your OpenTok API secret. (See your TokBox account page.)

Method Detail

generateToken

public java.lang.String generateToken(java.lang.String sessionId,
                                      TokenOptions tokenOptions)
                               throws OpenTokException

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.

The following example shows how to obtain a token that has a role of "subscriber" and that has a connection metadata string:

 import com.opentok.Role;
 import com.opentok.TokenOptions;

 class Test {
     public static void main(String argv[]) throws OpenTokException {
         int API_KEY = 0; // Replace with your OpenTok API key (see https://tokbox.com/account).
         String API_SECRET = ""; // Replace with your OpenTok API secret.
         OpenTok sdk = new OpenTok(API_KEY, API_SECRET);

         //Generate a basic session. Or you could use an existing session ID.
         String sessionId = System.out.println(sdk.createSession());

         // Replace with meaningful metadata for the connection.
         String connectionMetadata = "username=Bob,userLevel=4";

         // Use the Role value appropriate for the user.
         String role = Role.SUBSCRIBER;

         // Generate a token:
         TokenOptions options = new TokenOptions.Buider().role(role).data(connectionMetadata).build();
         String token = sdk.generateToken(sessionId, options);
         System.out.println(token);
     }
 }
 

For testing, you can also generate tokens by logging in to your TokBox account.

Parameters:

sessionId - The session ID corresponding to the session to which the user will connect.

tokenOptions - This TokenOptions object defines options for the token. These include the following:

• The role of the token (subscriber, publisher, or moderator)
• The expiration time of the token
• Connection data describing the end-user

Returns:

The token string.

Throws:

OpenTokException

generateToken

public java.lang.String generateToken(java.lang.String sessionId)
                               throws OpenTokException

Creates a token for connecting to an OpenTok session, using the default settings. The default settings are the following:

• The token is assigned the role of publisher.
• The token expires 24 hours after it is created.
• The token includes no connection data.

The following example shows how to generate a token that has the default settings:

 import com.opentok.OpenTok;

 class Test {
     public static void main(String argv[]) throws OpenTokException {
         int API_KEY = 0; // Replace with your OpenTok API key (see https://tokbox.com/account).
         String API_SECRET = ""; // Replace with your OpenTok API secret.
         OpenTok sdk = new OpenTok(API_KEY, API_SECRET);

         //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);
     }
 }
 

Parameters:

sessionId - The session ID corresponding to the session to which the user will connect.

Returns:

The token string.

Throws:

OpenTokException

See Also:

generateToken(String, TokenOptions)

createSession

public Session createSession(SessionProperties properties)
                      throws OpenTokException

Creates a new OpenTok session.

For example, when using the OpenTok.js library, use the session ID when calling the OT.initSession() method (to initialize an OpenTok session).

OpenTok sessions do not expire. However, authentication tokens do expire (see the generateToken(String, TokenOptions) method). Also note that sessions cannot explicitly be destroyed.

A session ID string can be up to 255 characters long.

Calling this method results in an OpenTokException in the event of an error. Check the error message for details.

The following code creates a session that attempts to send streams directly between clients (falling back to use the OpenTok TURN server to relay streams if the clients cannot connect):

 import com.opentok.MediaMode;
 import com.opentok.OpenTok;
 import com.opentok.Session;
 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.
         OpenTok sdk = new OpenTok(API_KEY, API_SECRET);

         SessionProperties sp = new SessionProperties().Builder()
           .mediaMode(MediaMode.RELAYED).build();

         Session session = sdk.createSession(sp);
         System.out.println(session.getSessionId());
     }
 }
 

You can also create a session using the OpenTok REST API or or by logging in to your TokBox account.

Parameters:

properties - This SessionProperties object defines options for the session. These include the following:

• Whether the session's streams will be transmitted directly between peers or using the OpenTok Media Router.
• A location hint for the location of the OpenTok server to use for the session.

Returns:

A Session object representing the new session. Call the getSessionId() method of the Session object to get the session ID, which uniquely identifies the session. You will use this session ID in the client SDKs to identify the session.

Throws:

OpenTokException

createSession

public Session createSession()
                      throws OpenTokException

Creates an OpenTok session with the default settings:

• The media mode is "relayed". The session will attempt to transmit streams directly between clients. If two clients cannot send and receive each others' streams, due to firewalls on the clients' networks, their streams will be relayed using the OpenTok TURN Server.
• The session uses the first client connecting to determine the location of the OpenTok server to use.

The following example creates a session that uses the default settings:

 import com.opentok.OpenTok;
 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.
         OpenTok sdk = new OpenTok(API_KEY, API_SECRET);

         String sessionId = sdk.createSession();
         System.out.println(sessionId);
     }
 }
 

Returns:

A Session object representing the new session. Call the getSessionId() method of the Session object to get the session ID, which uniquely identifies the session. You will use this session ID in the client SDKs to identify the session.

Throws:

OpenTokException

See Also:

createSession(SessionProperties)

getArchive

public Archive getArchive(java.lang.String archiveId)
                   throws OpenTokException

Gets an Archive object for the given archive ID.

Parameters:

archiveId - The archive ID.

Returns:

The Archive object.

Throws:

OpenTokException

listArchives

public ArchiveList listArchives()
                         throws OpenTokException

Returns a List of Archive objects, representing archives that are both both completed and in-progress, for your API key. This list is limited to 1000 archives starting with the first archive recorded. For a specific range of archives, call listArchives(int offset, int count).

Returns:

A List of Archive objects.

Throws:

OpenTokException

listArchives

public ArchiveList listArchives(int offset,
                                int count)
                         throws OpenTokException

Returns a List of Archive objects, representing archives that are both both completed and in-progress, for your API key.

Parameters:

offset - The index offset of the first archive. 0 is offset of the most recently started archive. 1 is the offset of the archive that started prior to the most recent archive.

count - The number of archives to be returned. The maximum number of archives returned is 1000.

Returns:

A List of Archive objects.

Throws:

OpenTokException

listArchives

public ArchiveList listArchives(java.lang.String sessionId)
                         throws RequestException

Returns a List of Archive objects, representing archives that are both both completed and in-progress, for your API key.

Parameters:

sessionId - The sessionId for which archives should be retrieved.

Returns:

A List of Archive objects.

Throws:

RequestException

startArchive

public Archive startArchive(java.lang.String sessionId,
                            ArchiveProperties properties)
                     throws OpenTokException

Starts archiving an OpenTok session. This version of the startArchive() method lets you disable audio or video recording.

Clients must be actively connected to the OpenTok session for you to successfully start recording an archive.

You can only record one archive at a time for a given session. You can only record archives of sessions that use the OpenTok Media Router (sessions with the media mode set to routed); you cannot archive sessions with the media mode set to relayed.

For more information on archiving, see the OpenTok archiving programming guide.

Parameters:

sessionId - The session ID of the OpenTok session to archive.

properties - This ArchiveProperties object defines options for the archive.

Returns:

The Archive object. This object includes properties defining the archive, including the archive ID.

Throws:

OpenTokException

startArchive

public Archive startArchive(java.lang.String sessionId)
                     throws OpenTokException

Throws:

OpenTokException

startArchive

public Archive startArchive(java.lang.String sessionId,
                            java.lang.String name)
                     throws OpenTokException

Throws:

OpenTokException

stopArchive

public Archive stopArchive(java.lang.String archiveId)
                    throws OpenTokException

Stops an OpenTok archive that is being recorded.

Archives automatically stop recording after 120 minutes or when all clients have disconnected from the session being archived.

Parameters:

archiveId - The archive ID of the archive you want to stop recording.

Returns:

The Archive object corresponding to the archive being stopped.

Throws:

OpenTokException

deleteArchive

public void deleteArchive(java.lang.String archiveId)
                   throws OpenTokException

Deletes an OpenTok archive.

You can only delete an archive which has a status of "available" or "uploaded". Deleting an archive removes its record from the list of archives. For an "available" archive, it also removes the archive file, making it unavailable for download.

Parameters:

archiveId - The archive ID of the archive you want to delete.

Throws:

OpenTokException

close

public void close()