# ServerManager

## core ServerManager

This manager handles all communications between the experiment running in the participant's browser and the `pavlovia.org` server, in an asynchronous manner.

It is responsible for reading the configuration file of an experiment, for opening and closing a session, for listing and downloading resources, and for uploading results, logs, and audio recordings.

## Constructor

#### new ServerManager(options)

Source:
  - core/ServerManager.js, line 24

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | Object | ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`psychoJS` | module:core.PsychoJS |  |  | the PsychoJS instance
`autoLog` | boolean | <optional> | `false` | whether or not to log

### Extends

- PsychObject

### Members

#### (static, readonly) Event :Symbol

Source:
  - core/ServerManager.js, line 1376

##### Properties:

Name | Type | Description
--- | --- | ---
`RESOURCE` | Symbol | Event type: resource event
`DOWNLOADING_RESOURCES` | Symbol | Event: resources have started to download
`DOWNLOADING_RESOURCE` | Symbol | Event: a specific resource download has started
`RESOURCE_DOWNLOADED` | Symbol | Event: a specific resource has been downloaded
`DOWNLOAD_COMPLETED` | Symbol | Event: resources have all downloaded
`STATUS` | Symbol | Event type: status event

Server event

A server event is emitted by the manager to inform its listeners of either a change of status, or of a resource related event (e.g. download started, download is completed).

##### Type:

- Symbol

#### (static, readonly) ResourceStatus :Symbol

Source:
  - core/ServerManager.js, line 1437

##### Properties:

Name | Type | Description
--- | --- | ---
`ERROR` | Symbol | There was an error during downloading, or the resource is in an unknown state.
`REGISTERED` | Symbol | The resource has been registered.
`DOWNLOADING` | Symbol | The resource is currently downloading.
`DOWNLOADED` | Symbol | The resource has been downloaded.

Resource status

##### Type:

- Symbol

#### (static, readonly) Status :Symbol

Source:
  - core/ServerManager.js, line 1414

##### Properties:

Name | Type | Description
--- | --- | ---
`READY` | Symbol | The manager is ready.
`BUSY` | Symbol | The manager is busy, e.g. it is downloaded resources.
`ERROR` | Symbol | The manager has encountered an error, e.g. it was unable to download a resource.

Server status

##### Type:

- Symbol

#### (readonly) ALL_RESOURCES :Symbol

Source:
  - core/ServerManager.js, line 34

Used to indicate to the ServerManager that all resources must be registered (and subsequently downloaded)

##### Type:

- Symbol

### Methods

#### (async, protected) _downloadResources(resources)

Source:
  - core/ServerManager.js, line 1010

Download the specified resources.

Note: we use the `preloadjs library`.

##### Parameters:

Name | Type | Description
--- | --- | ---
`resources` | Set | a set of names of previously registered resources

#### (protected) _listResources()

Source:
  - core/ServerManager.js, line 950

List the resources available to the experiment.

#### (protected) _queryServerAPI(method, path, data, contentTypeopt)

Source:
  - core/ServerManager.js, line 1303

Query the pavlovia server API.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`method` |  |  |  | the HTTP method, i.e. GET, PUT, POST, or DELETE
`path` |  |  |  | the resource path, without the server address
`data` |  |  |  | the data to be sent
`contentType` | string | <optional> | `"JSON"` | the content type, either JSON or FORM

#### (protected) _setupPreloadQueue()

Source:
  - core/ServerManager.js, line 1209

Setup the preload.js queue, and the associated callbacks.

#### (async) closeSession(isCompletedopt, syncopt) → {Promise.<ServerManager.CloseSessionPromise>|void}

Source:
  - core/ServerManager.js, line 224

Close the session for this experiment on the remote PsychoJS manager.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`isCompleted` | boolean | <optional> | `false` | whether or not the experiment was completed
`sync` | boolean | <optional> | `false` | whether or not to communicate with the server in a synchronous manner

##### Returns:

the response

Type
  Promise.<ServerManager.CloseSessionPromise> | void

#### getConfiguration(configURL) → {Promise.<ServerManager.GetConfigurationPromise>}

Source:
  - core/ServerManager.js, line 75

Read the configuration file for the experiment.

##### Parameters:

Name | Type | Description
--- | --- | ---
`configURL` | string | the URL of the configuration file

##### Returns:

the response

Type
  Promise.<ServerManager.GetConfigurationPromise>

#### getResource(name, errorIfNotDownloadedopt) → {Object}

Source:
  - core/ServerManager.js, line 292

Get the value of a resource.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`name` | string |  |  | name of the requested resource
`errorIfNotDownloaded` | boolean | <optional> | `false` | whether or not to throw an exception if the resource status is not DOWNLOADED

##### Throws:

exception if no resource with that name has previously been registered

Type
  Object.<string, *>

##### Returns:

value of the resource, or undefined if the resource has been registered but not downloaded yet.

Type
  Object

#### getResourceStatus(names) → {module:core.ServerManager.ResourceStatus}

Source:
  - core/ServerManager.js, line 338

Get the status of a single resource or the reduced status of an array of resources.

If an array of resources is given, getResourceStatus returns a single, reduced status that is the status furthest away from DOWNLOADED, with the status ordered as follow: ERROR (furthest from DOWNLOADED), REGISTERED, DOWNLOADING, and DOWNLOADED

For example, given three resources:

- if at least one of the resource status is ERROR, the reduced status is ERROR
- if at least one of the resource status is DOWNLOADING, the reduced status is DOWNLOADING
- if the status of all three resources is REGISTERED, the reduced status is REGISTERED
- if the status of all three resources is DOWNLOADED, the reduced status is DOWNLOADED

##### Parameters:

Name | Type | Description
--- | --- | ---
`names` | string | Array.<string> | names of the resources whose statuses are requested

##### Throws:

if at least one of the names is not that of a previously registered resource

Type
  Object.<string, *>

##### Returns:

status of the resource if there is only one, or reduced status otherwise

Type
  module:core.ServerManager.ResourceStatus

#### openSession() → {Promise.<ServerManager.OpenSessionPromise>}

Source:
  - core/ServerManager.js, line 131

Open a session for this experiment on the remote PsychoJS manager.

##### Returns:

the response

Type
  Promise.<ServerManager.OpenSessionPromise>

#### (async) prepareResources(resourcesopt)

Source:
  - core/ServerManager.js, line 438

Prepare resources for the experiment: register them with the server manager and possibly start downloading them right away.

- For an experiment running locally: the root directory for the specified resources is that of index.html unless they are prepended with a protocol, such as http:// or https://.
- For an experiment running on the server: if no resources are specified, all files in the resources directory of the experiment are downloaded, otherwise we only download the specified resources. All resources are assumed local to index.html unless they are prepended with a protocol.
- If resources is null, then we do not download any resources

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`resources` | String | Array.<({name: string, path: string, download: boolean}|String|Symbol)> | <optional> | `[]` | the list of resources or a single resource

#### resetStatus() → {ServerManager.Status.READY}

Source:
  - core/ServerManager.js, line 418

Reset the resource manager status to ServerManager.Status.READY.

##### Returns:

the new status

Type
  ServerManager.Status.READY

#### setStatus()

Source:
  - core/ServerManager.js, line 387

Set the resource manager status.

#### (async) uploadAudioVideo(@param) → {Promise.<ServerManager.UploadDataPromise>}

Source:
  - core/ServerManager.js, line 825

Synchronously or asynchronously upload audio data to the pavlovia server.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`@param` | Object |  |  | options
`options.mediaBlob` | Blob |  |  | the audio or video blob to be uploaded
`options.tag` | string |  |  | additional tag
`options.waitForCompletion` | boolean | <optional> | `false` | whether or not to wait for completion before returning
`options.showDialog` | boolean | <optional> | `false` | whether or not to open a dialog box to inform the participant to wait for the data to be uploaded to the server
`options.dialogMsg` | string | <optional> | `"Please wait a few moments while the data is uploading to the server"` | default message informing the participant to wait for the data to be uploaded to the server

##### Returns:

the response

Type
  Promise.<ServerManager.UploadDataPromise>

#### uploadData(key, value, syncopt) → {Promise.<ServerManager.UploadDataPromise>}

Source:
  - core/ServerManager.js, line 698

Asynchronously upload experiment data to the pavlovia server.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`key` | string |  |  | the data key (e.g. the name of .csv file)
`value` | string |  |  | the data value (e.g. a string containing the .csv header and records)
`sync` | boolean | <optional> | `false` | whether or not to communicate with the server in a synchronous manner

##### Returns:

the response

Type
  Promise.<ServerManager.UploadDataPromise>

#### uploadLog(logs, compressedopt) → {Promise.<ServerManager.UploadDataPromise>}

Source:
  - core/ServerManager.js, line 760

Asynchronously upload experiment logs to the pavlovia server.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`logs` | string |  |  | the base64 encoded, compressed, formatted logs
`compressed` | boolean | <optional> | `false` | whether or not the logs are compressed

##### Returns:

the response

Type
  Promise.<ServerManager.UploadDataPromise>

#### waitForResources(resourcesopt)

Source:
  - core/ServerManager.js, line 590

Block the experiment until the specified resources have been downloaded.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`resources` | Array.<{name: string, path: string}> | <optional> | `[]` | the list of resources

### Type Definitions

#### CloseSessionPromise

Source:
  - core/ServerManager.js, line 211

##### Properties:

Name | Type | Attributes | Description
--- | --- | --- | ---
`origin` | string |  | the calling method
`context` | string |  | the context
`error` | Object.<string, *> | <optional> | an error message if we could not close the session (e.g. if it has not previously been opened)

#### GetConfigurationPromise

Source:
  - core/ServerManager.js, line 62

##### Properties:

Name | Type | Attributes | Description
--- | --- | --- | ---
`origin` | string |  | the calling method
`context` | string |  | the context
`config` | Object.<string, *> | <optional> | the configuration
`error` | Object.<string, *> | <optional> | an error message if we could not read the configuration file

#### OpenSessionPromise

Source:
  - core/ServerManager.js, line 119

##### Properties:

Name | Type | Attributes | Description
--- | --- | --- | ---
`origin` | string |  | the calling method
`context` | string |  | the context
`token` | string | <optional> | the session token
`error` | Object.<string, *> | <optional> | an error message if we could not open the session

#### UploadDataPromise

Source:
  - core/ServerManager.js, line 684

##### Properties:

Name | Type | Attributes | Description
--- | --- | --- | ---
`origin` | string |  | the calling method
`context` | string |  | the context
`error` | Object.<string, *> | <optional> | an error message if we could not upload the data