Skip to content

Commit 83dac22

Browse files
aoberoiaoberoi
committed
update readme to adhere to standard outline #17 
1 parent 69df390 commit 83dac22

File tree

1 file changed

+153
-165
lines changed

1 file changed

+153
-165
lines changed

‎README.md

Lines changed: 153 additions & 165 deletions
Original file line numberDiff line numberDiff line change
@@ -1,217 +1,205 @@
11
# OpenTok Java SDK
22

3+
**TODO**: change this to opentok fork instead of aoberoi
4+
35
[![Build Status](https://travis-ci.org/aoberoi/Opentok-Java-SDK.svg?branch=modernization)](https://travis-ci.org/aoberoi/Opentok-Java-SDK)
46

5-
The OpenTok server SDKs include code for your web server. Use these SDKs to generate
6-
[sessions](http://tokbox.com/opentok/tutorials/create-session/) and to obtain
7-
[tokens](http://tokbox.com/opentok/tutorials/create-token/) for
8-
[OpenTok](http://www.tokbox.com/) applications. This version of the SDK also includes
9-
support for working with OpenTok 2.0 archives.
7+
The OpenTok Java SDK lets you generate
8+
[sessions](http://tokbox.com/opentok/tutorials/create-session/) and
9+
[tokens](http://tokbox.com/opentok/tutorials/create-token/) for [OpenTok](http://www.tokbox.com/)
10+
applications that run on the JVM. This version of the SDK also includes support for working with OpenTok
11+
2.0 archives.
1012

11-
## Download
13+
# Installation
1214

13-
Download the Java files:
15+
## Maven Central (recommended):
1416

15-
<https://github.com/opentok/Opentok-Java-SDK/archive/master.zip>
17+
The [Maven Central](http://central.sonatype.org/) repository helps manage dependencies for JVM
18+
based projects. It can be used via several build tools, including Maven and Gradle.
1619

17-
## Installing the SDK via Maven
20+
### Maven
1821

19-
The OpenTok Server SDK for Java defines the class in the com.opentok.api package. If you use Maven, add
20-
the following dependency information to the Project Object Model (pom.xml) file:
22+
When you use Maven as your build tool, you can manage dependencies in the `pom.xml` file:
2123

22-
<pre>
23-
&lt;dependency&gt;
24-
&lt;groupId&gt;com.opentok.api&lt;/groupId&gt;
25-
&lt;artifactId&gt;opentok-java-sdk&lt;/artifactId&gt;
26-
&lt;version&gt;[0.91.54,)&lt;/version&gt;
27-
&lt;/dependency&gt;
28-
</pre>
24+
```xml
25+
<dependency>
26+
<groupId>com.opentok</groupId>
27+
<artifactId>opentok-server-sdk</artifactId>
28+
<version>2.2.0</version>
29+
</dependency>
30+
```
2931

32+
### Gradle
3033

31-
## Requirements
34+
When you use Gradle as your build tool, you can manage dependencies in the `build.gradle` file:
3235

33-
The OpenTok Java SDK requires Java 6 or greater.
36+
```groovy
37+
dependencies {
38+
compile group: 'com.opentok', name: 'opentok-server-sdk', version: '2.2.0'
39+
}
40+
```
3441

35-
You need an OpenTok API key and API secret, which you can obtain at <https://dashboard.tokbox.com>.
42+
## Manually:
3643

44+
**TODO**: download from releases page?
3745

38-
# Changes in v2.0 of the OpenTok Java SDK
46+
# Usage
3947

40-
This version of the SDK includes support for working with OpenTok 2.0 archives. (This API does not work
41-
with OpenTok 1.0 archives.)
48+
## Initializing
4249

43-
The API_Config class has been removed. Store your OpenTok API key and API secret in code outside
44-
of the SDK files.
50+
Import the required classes in any class where it will be used. Then initialize a `com.opentok.OpenTok`
51+
object with your own API Key and API Secret.
4552

46-
The create_session() method has been renamed createSession(). Also, the method has changed to
47-
take one parameter: a SessionProperties object. You now generate a SessionProperties object using a
48-
Builder pattern. And the createSession() method returns a session ID string, not a Session object.
49-
(The Session class has been removed.)
53+
```java
54+
import com.opentok.OpenTok;
5055

51-
The generateTokentoken() method has been renamed generateToken().
56+
// inside a class or method...
57+
int apiKey = 000000; // YOUR API KEY
58+
String apiSecret = "YOUR API SECRET";
59+
OpenTok opentok = new OpenTok(apiKey, apiSecret)
60+
```
5261

53-
# Creating Sessions
54-
Use the `createSession()` method of the OpenTokSDK object to create a session and a session ID.
62+
## Creating Sessions
5563

56-
The following code creates a session that uses the OpenTok Media Router:
64+
To create an OpenTok Session, use the `OpenTok` instance's `createSession(SessionProperties properties)`
65+
method. The `properties` parameter is optional and it is used to specify whether you are creating a
66+
p2p Session and specifying a location hint. An instance can be initialized using the
67+
`com.opentok.SessionProperties.Builder` class. The `sessionId` property of the returned `com.opentok.Session`
68+
instance, which you can read using the `getSessionId()` method, is useful to get a sessionId that can
69+
be saved to a persistent store (e.g. database).
5770

58-
<pre>
59-
import com.opentok.api.OpenTokSDK;
60-
import com.opentok.exception.OpenTokException;
71+
```java
72+
import com.opentok.Session;
73+
import com.opentok.SessionProperties;
6174

62-
class Test {
63-
public static void main(String argv[]) throws OpenTokException {
64-
int API_KEY = 0; // Replace with your OpenTok API key.
65-
String API_SECRET = ""; // Replace with your OpenTok API secret.
66-
OpenTokSDK sdk = new OpenTokSDK(API_KEY, API_SECRET);
75+
// Just a plain Session
76+
Session session = opentok.createSession();
77+
// A p2p Session
78+
Session session = opentok.createSession(new SessionProperties.Builder()
79+
.p2p(true)
80+
.build());
81+
// A Session with a location hint
82+
Session session = opentok.createSession(new SessionProperties.Builder()
83+
.location("12.34.56.78")
84+
.build());
6785

68-
//Generate a session that uses the OpenTok Media Router
69-
System.out.println(sdk.createSession());
70-
}
71-
}
72-
</pre>
86+
// Store this sessionId in the database for later use
87+
String sessionId = session.getSessionId();
88+
```
7389

74-
The following code creates a peer-to-peer session:
90+
## Generating Tokens
7591

76-
<pre>
77-
import com.opentok.api.OpenTokSDK;
78-
import com.opentok.SessionProperties;
79-
import com.opentok.exception.OpenTokException;
92+
Once a Session is created, you can start generating Tokens for clients to use when connecting to it.
93+
You can generate a token either by calling an `com.opentok.OpenTok` instance's
94+
`generateToken(String sessionId, TokenOptions options)` method, or by calling a `com.opentok.Session`
95+
instance's `generateToken(TokenOptions options)` method after creating it. The `options` parameter
96+
is optional and it is used to set the role, expire time, and connection data of the token. An
97+
instance can be initialized using the `TokenOptions.Builder` class.
8098

81-
class Test {
82-
public static void main(String argv[]) throws OpenTokException {
83-
int API_KEY = 0; // Replace with your OpenTok API key.
84-
String API_SECRET = ""; // Replace with your OpenTok API secret.
99+
```java
100+
import com.opentok.TokenOptions;
101+
import com.opentok.Roles;
85102

86-
OpenTokSDK sdk = new OpenTokSDK(API_KEY, API_SECRET);
103+
// Generate a token from just a sessionId (fetched from a database)
104+
String token = opentok.generateToken(sessionId);
105+
// Generate a token by calling the method on the Session (returned from createSession)
106+
String token = session.generateToken();
87107

88-
SessionProperties sp = new SessionProperties.Builder().p2pPreference(true).build();
89-
String sessionId = sdk.create_session(sp);
90-
System.out.println(sessionId);
91-
}
92-
}
93-
</pre>
108+
// Set some options in a token
109+
String token = session.generateToken(new TokenOptions.Builder()
110+
.role(Roles.MODERATOR)
111+
.expireTime((System.currentTimeMillis() / 1000L) + (7 * 24 * 60 * 60)) // in one week
112+
.data("name=Johnny")
113+
.build());
114+
```
94115

95-
# Generating tokens
96-
Use the `generateTokentoken()` method of the OpenTokSDK object to create an OpenTok token:
116+
## Working with Archives
97117

98-
The following example shows how to obtain a token:
118+
You can start the recording of an OpenTok Session using a `com.opentok.OpenTok` instance's
119+
`startArchive(String sessionId, String name)` method. This will return a `com.opentok.Archive` instance.
120+
The parameter `name` is a optional and used to assign a name for the Archive. Note that you can
121+
only start an Archive on a Session that has clients connected.
99122

100-
<pre>
101-
import com.opentok.api.OpenTokSDK;
102-
import com.opentok.exception.OpenTokException;
123+
```java
124+
import com.opentok.Archive;
103125

104-
class Test {
105-
public static void main(String argv[]) throws OpenTokException {
106-
int API_KEY = 0; // Replace with your OpenTok API key (see http://dashboard.tokbox.com).
107-
String API_SECRET = ""; // Replace with your OpenTok API secret.
108-
OpenTokSDK sdk = new OpenTokSDK(API_KEY, API_SECRET);
126+
// A simple Archive (without a name)
127+
Archive archive = opentok.startArchive(sessionId, null);
109128

110-
//Generate a basic session. Or you could use an existing session ID.
111-
String sessionId = System.out.println(sdk.create_session());
129+
// Store this archiveId in the database for later use
130+
String archiveId = archive.getId();
131+
```
112132

113-
String token = sdk.generateTokentoken(sessionId);
114-
System.out.println(token);
115-
}
116-
}
117-
</pre>
133+
You can stop the recording of a started Archive using a `com.opentok.Archive` instance's
134+
`stopArchive(String archiveId)` method.
118135

119-
The following Java code example shows how to obtain a token that has a role of "subscriber" and that has
120-
a connection metadata string:
136+
```java
137+
// Stop an Archive from an archiveId (fetched from database)
138+
Archive archive = opentok.stopArchive(archiveId);
139+
```
121140

122-
<pre>
123-
import com.opentok.api.OpenTokSDK;
124-
import com.opentok.Role;
141+
To get an `com.opentok.Archive` instance (and all the information about it) from an `archiveId`, use
142+
a `com.opentok.OpenTok` instance's `getArchive(String archiveId)` method.
125143

126-
class Test {
127-
public static void main(String argv[]) throws OpenTokException {
128-
int API_KEY = 0; // Replace with your OpenTok API key (see http://dashboard.tokbox.com).
129-
String API_SECRET = ""; // Replace with your OpenTok API secret.
130-
OpenTokSDK sdk = new OpenTokSDK(API_KEY, API_SECRET);
144+
```java
145+
Archive archive = opentok.getArchive(String archiveId);
146+
```
131147

132-
//Generate a basic session. Or you could use an existing session ID.
133-
String sessionId = System.out.println(sdk.create_session().getSessionId());
148+
To delete an Archive, you can call a `com.opentok.OpenTok` instance's `deleteArchive(String archiveId)`
149+
method.
134150

135-
// Use the RoleConstants value appropriate for the user.
136-
String role = RoleConstants.SUBSCRIBER;
151+
```java
152+
// Delete an Archive from an archiveId (fetched from database)
153+
opentok.deleteArchive(archiveId);
154+
```
137155

138-
// Replace with meaningful metadata for the connection.
139-
String connectionData = "username=Bob,userLevel=4";
156+
You can also get a list of all the Archives you've created (up to 1000) with your API Key. This is
157+
done using a `com.opentok.OpenTok` instance's `listArchives(int offset, int count)` method. You may optionally
158+
paginate the Archives you receive using the offset and count parameters. This will return a
159+
`List<Archive>` type.
140160

141-
// Generate a token.
142-
String token = sdk.generateTokentoken(sessionId, role, null, connectionData);
143-
System.out.println(token);
144-
}
145-
}
146-
</pre>
161+
```java
162+
// Get a list with the first 1000 archives created by the API Key
163+
List<Archive> archives = opentok.listArchives();
147164

165+
// Get a list of the first 50 archives created by the API Key
166+
List<Archive> archives = opentok.listArchives(0, 50);
148167

149-
# Working with OpenTok 2.0 archives
168+
// Get a list of the next 50 archives
169+
List<Archive> archives = opentok.listArchives(50, 50);
170+
```
150171

151-
The following method starts recording an archive of an OpenTok 2.0 session (given a session ID)
152-
and returns the archive ID (on success).
172+
# Documentation
153173

154-
<pre>
155-
java.util.UUID startArchive(OpenTokSDK sdk, String sessionId, String name) {
156-
try {
157-
Archive archive = sdk.startArchive(sessionId, name);
158-
return archive.getId();
159-
} catch (OpenTokException exception){
160-
System.out.println(exception.toString());
161-
return null;
162-
}
163-
}
164-
</pre>
165-
166-
The following method stops the recording of an archive (given an archive ID), returning
167-
true on success, and false on failure.
168-
169-
<pre>
170-
boolean stopArchive(OpenTokSDK sdk, String archiveId) {
171-
try {
172-
Archive archive = sdk.stopArchive(archiveId);
173-
return true;
174-
} catch (OpenTokException exception){
175-
System.out.println(exception.toString());
176-
return false;
177-
}
178-
}
179-
</pre>
180-
181-
The following method logs information on a given archive.
182-
183-
<pre>
184-
void logArchiveInfo(OpenTokSDK sdk, String archiveId) {
185-
try {
186-
Archive archive = sdk.getArchive(archiveId);
187-
System.out.println(archive.toString());
188-
} catch (OpenTokException exception){
189-
System.out.println(exception.toString());
190-
}
191-
}
192-
</pre>
193-
194-
The following method logs information on all archives (up to 50)
195-
for your API key:
196-
197-
<pre>
198-
void listArchives(OpenTokSDK sdk) {
199-
try {
200-
List<Archive> archives = sdk.listArchives();
201-
for (int i = 0; i &lt; archives.size(); i++) {
202-
Archive archive = archives.get(i);
203-
System.out.println(archive.toString());
204-
}
205-
} catch (OpenTokException exception) {
206-
System.out.println(exception.toString());
207-
}
208-
}
209-
</pre>
174+
**TODO**: Reference documentation is available at <http://opentok.github.io/opentok-java-sdk/>
175+
176+
# Requirements
177+
178+
You need an OpenTok API key and API secret, which you can obtain at <https://dashboard.tokbox.com>.
179+
180+
The OpenTok Java SDK requires JDK 6 or greater to compile. Runtime requires Java SE 6 or greater.
181+
This project is tested on both OpenJDK and Oracle implementations.
182+
183+
# Release Notes
184+
185+
**TODO**: See the [Releases](https://github.com/opentok/opentok-java-sdk/releases) page for details
186+
about each release.
187+
188+
## Important changes in v2.0
189+
190+
This version of the SDK includes support for working with OpenTok 2.0 archives. (This API does not
191+
work with OpenTok 1.0 archives.)
210192

193+
# Development and Contributing
211194

195+
Interested in contributing? We <3 pull requests! File a new
196+
[Issue](https://github.com/opentok/opentok-java-sdk/issues) or take a look at the existing ones. If
197+
you are going to send us a pull request, please try to run the test suite first and also include
198+
tests for your changes.
212199

213-
# More information
200+
# Support
214201

215-
For details on the API, see the comments in Java files in src/main/java/com/opentok.
202+
See <http://tokbox.com/opentok/support/> for all our support options.
216203

217-
For more information on OpenTok, go to <http://www.tokbox.com/>.
204+
Find a bug? File it on the [Issues](https://github.com/opentok/opentok-java-sdk/issues) page. Hint:
205+
test cases are really helpful!

0 commit comments

Comments
 (0)