diff --git a/IPython/html/static/services/sessions/js/session.js b/IPython/html/static/services/sessions/js/session.js
index 579939c..99b49c7 100644
--- a/IPython/html/static/services/sessions/js/session.js
+++ b/IPython/html/static/services/sessions/js/session.js
@@ -9,6 +9,22 @@ define([
], function(IPython, $, utils, kernel) {
"use strict";
+ /**
+ * Session object for accessing the session REST api. The session
+ * should be used to start kernels and then shut them down -- for
+ * all other operations, the kernel object should be used.
+ *
+ * Options should include:
+ * - notebook_name: the notebook name
+ * - notebook_path: the path (not including name) to the notebook
+ * - kernel_name: the type of kernel (e.g. python3)
+ * - base_url: the root url of the notebook server
+ * - ws_url: the url to access websockets
+ * - notebook: Notebook object
+ *
+ * @class Session
+ * @param {Object} options
+ */
var Session = function (options) {
this.id = null;
this.notebook_model = {
@@ -27,11 +43,19 @@ define([
this.notebook = options.notebook;
this.kernel = null;
- this.events = options.events;
+ this.events = options.notebook.events;
};
+ // Public REST api functions
+
/**
* GET /api/sessions
+ *
+ * Get a list of the current sessions.
+ *
+ * @function list
+ * @param {function} [success] - function executed on ajax success
+ * @param {function} [error] - functon executed on ajax error
*/
Session.prototype.list = function (success, error) {
$.ajax(this.session_service_url, {
@@ -46,6 +70,12 @@ define([
/**
* POST /api/sessions
+ *
+ * Start a new session. This function can only executed once.
+ *
+ * @function start
+ * @param {function} [success] - function executed on ajax success
+ * @param {function} [error] - functon executed on ajax error
*/
Session.prototype.start = function (success, error) {
if (this.kernel !== null) {
@@ -83,6 +113,12 @@ define([
/**
* GET /api/sessions/[:session_id]
+ *
+ * Get information about a session.
+ *
+ * @function get_info
+ * @param {function} [success] - function executed on ajax success
+ * @param {function} [error] - functon executed on ajax error
*/
Session.prototype.get_info = function (success, error) {
$.ajax(this.session_url, {
@@ -97,20 +133,24 @@ define([
/**
* PATCH /api/sessions/[:session_id]
+ *
+ * Rename or move a notebook. If the given name or path are
+ * undefined, then they will not be changed.
+ *
+ * @function rename_notebook
+ * @param {string} [name] - new notebook name
+ * @param {string} [path] - new path to notebook
+ * @param {function} [success] - function executed on ajax success
+ * @param {function} [error] - functon executed on ajax error
*/
- Session.prototype.change = function (notebook_name, notebook_path, kernel_name, success, error) {
- if (notebook_name !== undefined) {
- this.notebook_model.name = notebook_name;
- }
- if (notebook_path !== undefined) {
- this.notebook_model.path = notebook_path;
+ Session.prototype.rename_notebook = function (name, path, success, error) {
+ if (name !== undefined) {
+ this.notebook_model.name = name;
}
- if (kernel_name !== undefined) {
- this.kernel_model.name = kernel_name;
+ if (path !== undefined) {
+ this.notebook_model.path = path;
}
- console.log(JSON.stringify(this._get_model()));
-
$.ajax(this.session_url, {
processData: false,
cache: false,
@@ -122,12 +162,14 @@ define([
});
};
- Session.prototype.rename_notebook = function (name, path, success, error) {
- this.change(name, path, undefined, success, error);
- };
-
/**
* DELETE /api/sessions/[:session_id]
+ *
+ * Kill the kernel and shutdown the session.
+ *
+ * @function delete
+ * @param {function} [success] - function executed on ajax success
+ * @param {function} [error] - functon executed on ajax error
*/
Session.prototype.delete = function (success, error) {
if (this.kernel) {
@@ -143,7 +185,16 @@ define([
error: this._on_error(error)
});
};
-
+
+ // Helper functions
+
+ /**
+ * Get the data model for the session, which includes the notebook
+ * (name and path) and kernel (name and id).
+ *
+ * @function _get_model
+ * @returns {Object} - the data model
+ */
Session.prototype._get_model = function () {
return {
notebook: this.notebook_model,
@@ -151,6 +202,15 @@ define([
};
};
+ /**
+ * Update the data model from the given JSON object, which should
+ * have attributes of `id`, `notebook`, and/or `kernel`. If
+ * provided, the notebook data must include name and path, and the
+ * kernel data must include name and id.
+ *
+ * @function _update_model
+ * @param {Object} data - updated data model
+ */
Session.prototype._update_model = function (data) {
if (data && data.id) {
this.id = data.id;
@@ -166,6 +226,14 @@ define([
}
};
+ /**
+ * Handle a successful AJAX request by updating the session data
+ * model with the response, and then optionally calling a provided
+ * callback.
+ *
+ * @function _on_success
+ * @param {function} success - callback
+ */
Session.prototype._on_success = function (success) {
var that = this;
return function (data, status, xhr) {
@@ -176,6 +244,13 @@ define([
};
};
+ /**
+ * Handle a failed AJAX request by logging the error message, and
+ * then optionally calling a provided callback.
+ *
+ * @function _on_error
+ * @param {function} error - callback
+ */
Session.prototype._on_error = function (error) {
return function (xhr, status, err) {
utils.log_ajax_error(xhr, status, err);
@@ -185,12 +260,13 @@ define([
};
};
-
+ /**
+ * Error type indicating that the session is already starting.
+ */
var SessionAlreadyStarting = function (message) {
this.name = "SessionAlreadyStarting";
this.message = (message || "");
};
-
SessionAlreadyStarting.prototype = Error.prototype;
// For backwards compatability.