Merge branch 'master' into add-license-header-plugin

Conflicts:
	build.gradle
	sample/HelloWorld/README.md
	sample/HelloWorld/build.gradle
	sample/HelloWorld/src/main/java/com/example/FreeMarkerTemplateView.java
	sample/HelloWorld/src/main/java/com/example/HelloWorldServer.java
	settings.gradle
	src/main/java/com/opentok/OpenTok.java
	src/main/java/com/opentok/Role.java
	src/main/java/com/opentok/constants/package-info.java
	src/main/java/com/opentok/exception/RequestException.java
	src/test/java/com/opentok/test/OpenTokTest.java

Author: aoberoi

.gitignore

@@ -1,4 +1,5 @@
 *.class
+*.DS_Store
 
 # Package Files
 *.jar

.travis.yml

@@ -1,5 +1,9 @@
 language: java
 jdk:
-  - openjdk7
-  - openjdk6
-  - oraclejdk7
+- openjdk7
+- openjdk6
+- oraclejdk7
+- oraclejdk8
+notifications:
+  slack:
+    secure: fGRoClN1IQiZvokEiqmKOrF7EeaNQDHDHqUMaT4n7d3qW2fMe3N8ZLxlIDlzgJ2pv09VWqK7rmPgdhJR8yVG7OE4QQ5kzR59xD8ePN0j0jf6W6eOBPq3a9UUarnny21LFsShvRMZ/BaXcvTox1zMVltpMGFw2K4ijH8+ZvdkNz8=

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing Guidelines
+
+For anyone looking to get involved to this project, we are glad to hear from you. Here are a few types of contributions
+that we would be interested in hearing about.
+
+*  Bug fixes
+    -  If you find a bug, please first report it using Github Issues.
+    -  Issues that have already been identified as a bug will be labelled `bug`.
+    -  If you'd like to submit a fix for a bug, send a Pull Request from your own fork and mention the Issue number.
+        +  Include a test that isolates the bug and verifies that it was fixed.
+*  New Features
+    -  If you'd like to accomplish something in the library that it doesn't already do, describe the problem in a new
+       Github Issue.
+    -  Issues that have been identified as a feature request will be labelled `enhancement`.
+    -  If you'd like to implement the new feature, please wait for feedback from the project maintainers before spending
+       too much time writing the code. In some cases, `enhancement`s may not align well with the project objectives at
+       the time.
+*  Tests, Documentation, Miscellaneous
+    -  If you think the test coverage could be improved, the documentation could be clearer, you've got an alternative
+       implementation of something that may have more advantages, or any other change we would still be glad hear about
+       it.
+       -  If its a trivial change, go ahead and send a Pull Request with the changes you have in mind
+       -  If not, open a Github Issue to discuss the idea first.
+
+## Requirements
+
+For a contribution to be accepted:
+
+*  The test suite must be complete and pass
+*  Code must follow existing styling conventions
+*  Commit messages must be descriptive. Related issues should be mentioned by number.
+
+If the contribution doesn't meet these criteria, a maintainer will discuss it with you on the Issue. You can still
+continue to add more commits to the branch you have sent the Pull Request from.
+
+## How To
+
+1. Fork this repository on GitHub.
+1. Clone/fetch your fork to your local development machine.
+1. Create a new branch (e.g. `issue-12`, `feat.add_foo`, etc) and check it out.
+1. Make your changes and commit them. (Did the tests pass?)
+1. Push your new branch to your fork. (e.g. `git push myname issue-12`)
+1. Open a Pull Request from your new branch to the original fork's `master` branch.
+
+## Developer Guidelines
+
+See DEVELOPING.md for guidelines for developing this project.

DEVELOPING.md

@@ -0,0 +1,108 @@
+# Development Guidelines
+
+This document describes tools, tasks and workflow that one needs to be familiar with in order to effectively maintain
+this project. If you use this package within your own software as is but don't plan on modifying it, this guide is
+**not** for you.
+
+## Tools
+
+*  [Gradle](http://www.gradle.org/): used to run predefined tasks. It also manages dependencies for the project. If you
+   do not have it already installed, you won't need to install it. The gradle wrapper is included in the project and you
+   can invoke it using `./gradlew` substituted for `gradle`.
+
+## Tasks
+
+### Building
+
+Gradle's [Java Plugin](http://www.gradle.org/docs/current/userguide/java_plugin.html) provides various tasks to build
+this software. The most common tasks are:
+
+*  `gradle build` - build jars and test
+*  `gradle clean` - remove previously built artifacts.
+
+### Testing
+
+This project's tests are written as JUnit test cases. Common tasks:
+
+*  `gradle check` - run the test suite.
+
+### Generating Documentation
+
+This project's reference documentation is generated by Javadoc and resides in the `docs` directory of the project.
+Common tasks:
+
+*  `gradle javadoc` - generate the reference documentation locally.
+
+### Releasing
+
+In order to create a release, the following should be completed in order.
+
+1. Ensure all the tests are passing (`gradle check`) and that there is enough test coverage.
+1. Make sure you are on the `master` branch of the repository, with all changes merged/commited already.
+1. Update the version number in the source code and the README. See [Versioning](#versioning) for information
+   about selecting an appropriate version number. Files to change:
+   - src/main/java/com/opentok/constants/Version.java
+   - build.gradle
+   - README.md
+1. Commit the version number change with the message "Update to version x.x.x", substituting the new version number.
+1. Create a git tag: `git tag -a vx.x.x -m "Release vx.x.x"`
+1. Ensure that you have permission to update the OSSRH repository. The following system properties must be set:
+    - `ossrhUsername`
+    - `ossrhPassword`
+    - `signing.keyId`
+    - `signing.password`
+    - `signing.secretKeyRingFile`
+1. Run `gradle uploadArchives` to create a staging release.
+1. Login to [OSSRH](https://oss.sonatype.org/) and promote the staging release to a public release.
+1. Change the version number for future development by incrementing the patch number and
+   adding "-alpha.1" in each file except the README. Building may have generated the docs files once again, so to clear
+   them run `git checkout -- docs/`. Then stage the remaining files and commit with the message
+   "Begin development on next version".
+1. Push the changes to the source repository: `git push origin master; git push --tags origin`
+1. Find the latest .jar in the build directory and upload this as an attached to the latest GitHub Release. Add release
+   notes with a description of changes and fixes.
+
+### IDE Integration
+
+Gradle's [IDEA Plugin](http://www.gradle.org/docs/current/userguide/idea_plugin.html) and
+[Eclipse Plugin](http://www.gradle.org/docs/current/userguide/eclipse_plugin.html) provide tasks to generate project
+files for these IDEs. In general, neither of these are necessary to work on the project. If you prefer to use one of
+these IDEs, you may find those tasks helpful.
+
+## Workflow
+
+### Versioning
+
+The project uses [semantic versioning](http://semver.org/) as a policy for incrementing version numbers. For planned
+work that will go into a future version, there should be a Milestone created in the Github Issues named with the version
+number (e.g. "v2.2.1").
+
+During development the version number should end in "-alpha.x" or "-beta.x", where x is an increasing number starting from 1.
+
+### Branches
+
+*  `master` - the main development branch.
+*  `feat.foo` - feature branches. these are used for longer running tasks that cannot be accomplished in one commit.
+   once merged into master, these branches should be deleted.
+*  `vx.x.x` - if development for a future version/milestone has begun while master is working towards a sooner
+   release, this is the naming scheme for that branch. once merged into master, these branches should be deleted.
+
+### Tags
+
+*  `vx.x.x` - commits are tagged with a final version number during release.
+
+### Issues
+
+Issues are labelled to help track their progress within the pipeline.
+
+*  no label - these issues have not been triaged.
+*  `bug` - confirmed bug. aim to have a test case that reproduces the defect.
+*  `enhancement` - contains details/discussion of a new feature. it may not yet be approved or placed into a
+   release/milestone.
+*  `wontfix` - closed issues that were never addressed.
+*  `duplicate` - closed issue that is the same to another referenced issue.
+*  `question` - purely for discussion
+
+### Management
+
+When in doubt, find the maintainers and ask.

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 TokBox, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,14 +1,16 @@
 # OpenTok Java SDK
 
-**TODO**: change this to opentok fork instead of aoberoi
-
-[![Build Status](https://travis-ci.org/aoberoi/Opentok-Java-SDK.svg?branch=modernization)](https://travis-ci.org/aoberoi/Opentok-Java-SDK)
+[![Build Status](https://travis-ci.org/opentok/Opentok-Java-SDK.svg)](https://travis-ci.org/opentok/Opentok-Java-SDK)
 
 The OpenTok Java SDK lets you generate
 [sessions](http://tokbox.com/opentok/tutorials/create-session/) and
 [tokens](http://tokbox.com/opentok/tutorials/create-token/) for [OpenTok](http://www.tokbox.com/)
-applications that run on the JVM. This version of the SDK also includes support for working with OpenTok
-2.0 archives.
+applications that run on the JVM. This version of the SDK also includes support for working
+with [OpenTok 2.0 archives](http://tokbox.com/#archiving).
+
+If you are updating from a previous version of this SDK, see
+[Important changes since v2.2.0](#important-changes-since-v220).
+
 
 # Installation
 
@@ -23,9 +25,9 @@ When you use Maven as your build tool, you can manage dependencies in the `pom.x
 
 ```xml
 <dependency>
-    <groupId>com.opentok</groupId>
+    <groupId>com.tokbox</groupId>
     <artifactId>opentok-server-sdk</artifactId>
-    <version>2.2.0</version>
+    <version>2.2.2</version>
 </dependency>
 ```
 
@@ -35,13 +37,17 @@ When you use Gradle as your build tool, you can manage dependencies in the `buil
 
 ```groovy
 dependencies {
-  compile group: 'com.opentok', name: 'opentok-server-sdk', version: '2.2.0'
+  compile group: 'com.tokbox', name: 'opentok-server-sdk', version: '2.2.2'
 }
 ```
 
 ## Manually:
 
-**TODO**: download from releases page?
+Download the jar file for the latest release from the
+[Releases](https://github.com/opentok/opentok-java-sdk/releases) page. Include it in the classpath
+for your own project by
+[using the JDK directly](http://docs.oracle.com/javase/7/docs/technotes/tools/windows/classpath.html)
+or in your IDE of choice.
 
 # Usage
 
@@ -62,28 +68,35 @@ OpenTok opentok = new OpenTok(apiKey, apiSecret)
 ## Creating Sessions
 
 To create an OpenTok Session, use the `OpenTok` instance's `createSession(SessionProperties properties)`
-method. The `properties` parameter is optional and it is used to specify whether you are creating a
-p2p Session and specifying a location hint. An instance can be initialized using the
-`com.opentok.SessionProperties.Builder` class. The `sessionId` property of the returned `com.opentok.Session`
-instance, which you can read using the `getSessionId()` method, is useful to get a sessionId that can
-be saved to a persistent store (e.g. database).
+method. The `properties` parameter is optional and it is used to specify two things:
+
+* Whether the session uses the OpenTok Media Router
+* A location hint for the OpenTok server.
+
+An instance can be initialized using the `com.opentok.SessionProperties.Builder` class.
+The `sessionId` property of the returned `com.opentok.Session` instance, which you can read using
+the `getSessionId()` method, is useful to get an identifier that can be saved to a persistent store
+(such as a database).
 
 ```java
+import com.opentok.MediaMode;
 import com.opentok.Session;
 import com.opentok.SessionProperties;
 
-// Just a plain Session
+// A session that attempts to stream media directly between clients:
 Session session = opentok.createSession();
-// A p2p Session
+
+// A session that uses the OpenTok Media Router:
 Session session = opentok.createSession(new SessionProperties.Builder()
-  .p2p(true)
+  .mediaMode(MediaMode.ROUTED)
   .build());
-// A Session with a location hint
+
+// A Session with a location hint:
 Session session = opentok.createSession(new SessionProperties.Builder()
   .location("12.34.56.78")
   .build());
 
-// Store this sessionId in the database for later use
+// Store this sessionId in the database for later use:
 String sessionId = session.getSessionId();
 ```
 
@@ -98,7 +111,7 @@ instance can be initialized using the `TokenOptions.Builder` class.
 
 ```java
 import com.opentok.TokenOptions;
-import com.opentok.Roles;
+import com.opentok.Role;
 
 // Generate a token from just a sessionId (fetched from a database)
 String token = opentok.generateToken(sessionId);
@@ -107,7 +120,7 @@ String token = session.generateToken();
 
 // Set some options in a token
 String token = session.generateToken(new TokenOptions.Builder()
-  .role(Roles.MODERATOR)
+  .role(Role.MODERATOR)
   .expireTime((System.currentTimeMillis() / 1000L) + (7 * 24 * 60 * 60)) // in one week
   .data("name=Johnny")
   .build());
@@ -169,9 +182,18 @@ List<Archive> archives = opentok.listArchives(0, 50);
 List<Archive> archives = opentok.listArchives(50, 50);
 ```
 
+# Samples
+
+There are two sample applications included with the SDK. To get going as fast as possible, clone the whole
+repository and follow the Walkthroughs:
+
+*  [HelloWorld](sample/HelloWorld/README.md)
+*  [Archiving](sample/Archiving/README.md)
+
 # Documentation
 
-**TODO**: Reference documentation is available at <http://opentok.github.io/opentok-java-sdk/>
+Reference documentation is available at <http://www.tokbox.com/opentok/libraries/server/java/reference/index.html> and in the
+docs directory of the SDK.
 
 # Requirements
 
@@ -180,26 +202,47 @@ You need an OpenTok API key and API secret, which you can obtain at <https://das
 The OpenTok Java SDK requires JDK 6 or greater to compile. Runtime requires Java SE 6 or greater.
 This project is tested on both OpenJDK and Oracle implementations.
 
+
 # Release Notes
 
-**TODO**: See the [Releases](https://github.com/opentok/opentok-java-sdk/releases) page for details
+See the [Releases](https://github.com/opentok/opentok-java-sdk/releases) page for details
 about each release.
 
-## Important changes in v2.0
+# Important changes since v2.2.0
+
+**Changes in v2.2.1:**
+
+The default setting for the `createSession()` method is to create a session with the media mode set
+to relayed. In previous versions of the SDK, the default setting was to use the OpenTok Media Router
+(with the media mode set to routed in v2.2.0, or with p2p.preference="disabled" in previous
+versions). In a relayed session, clients will attempt to send streams directly between each other
+(peer to peer); and if clients cannot connect due to firewall restrictions, the session uses the
+OpenTok TURN server to relay audio-video streams.
+
+**Changes in v2.2.0:**
 
 This version of the SDK includes support for working with OpenTok 2.0 archives. (This API does not
 work with OpenTok 1.0 archives.)
 
+This version of the SDK includes a number of improvements in the API design. These include a number
+of API changes. See the OpenTok 2.2 SDK Reference for details on the new API.
+
+The API_Config class has been removed. Store your OpenTok API key and API secret in code outside of the SDK files.
+
+The `create_session()` method has been renamed `createSession()`. Also, the method has changed to
+take one parameter: a SessionProperties object. You now generate a SessionProperties object using a Builder pattern.
+
+The `generate_token()` method has been renamed `generateToken()`. Also, the method has changed to
+take two parameters: the session ID and a TokenOptions object.
+
 # Development and Contributing
 
-Interested in contributing? We <3 pull requests! File a new
-[Issue](https://github.com/opentok/opentok-java-sdk/issues) or take a look at the existing ones. If
-you are going to send us a pull request, please try to run the test suite first and also include
-tests for your changes.
+Interested in contributing? We :heart: pull requests! See the [Development](DEVELOPING.md) and
+[Contribution](CONTRIBUTING.md) guidelines.
 
 # Support
 
-See <http://tokbox.com/opentok/support/> for all our support options.
+See <https://support.tokbox.com> for all our support options.
 
 Find a bug? File it on the [Issues](https://github.com/opentok/opentok-java-sdk/issues) page. Hint:
 test cases are really helpful!