controllers.gui

Class Api

java.lang.Object

play.mvc.Results

play.mvc.Controller

controllers.gui.Api

All Implemented Interfaces:

play.mvc.Http.HeaderNames, play.mvc.Http.Status

@Singleton
public class Api
extends play.mvc.Controller

JATOS API Controller: all requests possible via JATOS' API

Field Summary

Fields inherited from interface play.mvc.Http.Status

ACCEPTED, BAD_GATEWAY, BAD_REQUEST, CONFLICT, CONTINUE, CREATED, EXPECTATION_FAILED, FAILED_DEPENDENCY, FORBIDDEN, FOUND, GATEWAY_TIMEOUT, GONE, HTTP_VERSION_NOT_SUPPORTED, IM_A_TEAPOT, INSUFFICIENT_STORAGE, INTERNAL_SERVER_ERROR, LENGTH_REQUIRED, LOCKED, METHOD_NOT_ALLOWED, MOVED_PERMANENTLY, MULTI_STATUS, MULTIPLE_CHOICES, NETWORK_AUTHENTICATION_REQUIRED, NO_CONTENT, NON_AUTHORITATIVE_INFORMATION, NOT_ACCEPTABLE, NOT_FOUND, NOT_IMPLEMENTED, NOT_MODIFIED, OK, PARTIAL_CONTENT, PAYMENT_REQUIRED, PERMANENT_REDIRECT, PRECONDITION_FAILED, PRECONDITION_REQUIRED, PROXY_AUTHENTICATION_REQUIRED, REQUEST_ENTITY_TOO_LARGE, REQUEST_HEADER_FIELDS_TOO_LARGE, REQUEST_TIMEOUT, REQUEST_URI_TOO_LONG, REQUESTED_RANGE_NOT_SATISFIABLE, RESET_CONTENT, SEE_OTHER, SERVICE_UNAVAILABLE, SWITCHING_PROTOCOLS, TEMPORARY_REDIRECT, TOO_MANY_REQUESTS, UNAUTHORIZED, UNPROCESSABLE_ENTITY, UNSUPPORTED_MEDIA_TYPE, UPGRADE_REQUIRED, USE_PROXY

Fields inherited from interface play.mvc.Http.HeaderNames

ACCEPT, ACCEPT_CHARSET, ACCEPT_ENCODING, ACCEPT_LANGUAGE, ACCEPT_RANGES, ACCESS_CONTROL_ALLOW_CREDENTIALS, ACCESS_CONTROL_ALLOW_HEADERS, ACCESS_CONTROL_ALLOW_METHODS, ACCESS_CONTROL_ALLOW_ORIGIN, ACCESS_CONTROL_EXPOSE_HEADERS, ACCESS_CONTROL_MAX_AGE, ACCESS_CONTROL_REQUEST_HEADERS, ACCESS_CONTROL_REQUEST_METHOD, AGE, ALLOW, AUTHORIZATION, CACHE_CONTROL, CONNECTION, CONTENT_DISPOSITION, CONTENT_ENCODING, CONTENT_LANGUAGE, CONTENT_LENGTH, CONTENT_LOCATION, CONTENT_MD5, CONTENT_RANGE, CONTENT_SECURITY_POLICY, CONTENT_SECURITY_POLICY_REPORT_ONLY, CONTENT_TRANSFER_ENCODING, CONTENT_TYPE, COOKIE, DATE, ETAG, EXPECT, EXPIRES, FORWARDED, FROM, HOST, IF_MATCH, IF_MODIFIED_SINCE, IF_NONE_MATCH, IF_RANGE, IF_UNMODIFIED_SINCE, LAST_MODIFIED, LINK, LOCATION, MAX_FORWARDS, ORIGIN, PRAGMA, PROXY_AUTHENTICATE, PROXY_AUTHORIZATION, RANGE, REFERER, REFERRER_POLICY, RETRY_AFTER, SERVER, SET_COOKIE, SET_COOKIE2, STRICT_TRANSPORT_SECURITY, TE, TRAILER, TRANSFER_ENCODING, UPGRADE, USER_AGENT, VARY, VIA, WARNING, WWW_AUTHENTICATE, X_CONTENT_SECURITY_POLICY_NONCE_HEADER, X_CONTENT_TYPE_OPTIONS, X_FORWARDED_FOR, X_FORWARDED_HOST, X_FORWARDED_PORT, X_FORWARDED_PROTO, X_FRAME_OPTIONS, X_PERMITTED_CROSS_DOMAIN_POLICIES, X_REQUESTED_WITH, X_XSS_PROTECTION

Method Summary

Modifier and Type	Method and Description
play.mvc.Result	deleteStudy(java.lang.String id) Deletes a study
play.mvc.Result	deleteStudyAssetsFile(java.lang.String id, java.lang.String filepath) Deletes a file in the study assets directory.
play.mvc.Result	downloadStudyAssetsFile(java.lang.String id, java.lang.String filepath) Download a file from a study assets folder.
play.mvc.Result	exportResultData(play.mvc.Http.Request request, boolean asPlainText, boolean isApiCall) Returns result data only (not the result files, not the metadata).
play.mvc.Result	exportResultFiles(play.mvc.Http.Request request) Returns all result files (not result data and not metadata) belonging to results in a zip.
play.mvc.Result	exportResultMetadata(play.mvc.Http.Request request, java.lang.Boolean isApiCall) Returns all result's metadata (but not result files and not metadata) in a zip file.
play.mvc.Result	exportResults(play.mvc.Http.Request request, java.lang.Boolean isApiCall) Returns results (including metadata, data, and files) in a zip file.
play.mvc.Result	exportSingleResultFile(java.lang.Long componentResultId, java.lang.String filename) Exports a single result file.
play.mvc.Result	exportStudy(java.lang.String id) Returns a JATOS study archive (.jzip)
play.mvc.Result	getAllStudyPropertiesByUser(java.lang.Boolean withComponentProperties, java.lang.Boolean withBatchProperties) Returns all study properties a user can access.
play.mvc.Result	getStudyAssetsStructure(java.lang.String id, boolean flatten) Gets the study assets directory structure as JSON
play.mvc.Result	getStudyCodes(java.lang.String id, scala.Option<java.lang.Long> batchId, java.lang.String type, java.lang.String comment, java.lang.Integer amount) Get study codes for the given batch and worker type
play.mvc.Result	getStudyProperties(java.lang.String id, java.lang.Boolean withComponentProperties, java.lang.Boolean withBatchProperties) Get study properties
play.mvc.Result	importStudy(play.mvc.Http.Request request, boolean keepProperties, boolean keepAssets, boolean keepCurrentAssetsName, boolean renameAssets) Imports a JATOS study archive (.jzip).
play.mvc.Result	logs(java.lang.String filename) Returns a JATOS application log file.
play.mvc.Result	removeResults(play.mvc.Http.Request request) Removes results from the database (ComponentResults and StudyResults) and result files from the file system.
play.mvc.Result	status() Returns admin status information in JSON
play.mvc.Result	studyLog(java.lang.String id, int entryLimit, boolean download) Returns a study log.
play.mvc.Result	testToken() Returns information about the API token used in the request in JSON.
play.mvc.Result	uploadStudyAssetsFile(play.mvc.Http.Request request, java.lang.String id, java.lang.String filepath) Upload a file to a study assets folder.

Methods inherited from class play.mvc.Controller

changeLang, changeLang, clearLang, ctx, flash, flash, flash, lang, request, response, session, session, session, TODO, TODO

Methods inherited from class play.mvc.Results

badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, badRequest, contentDispositionHeader, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, created, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, forbidden, found, found, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, internalServerError, movedPermanently, movedPermanently, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, networkAuthenticationRequired, noContent, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notAcceptable, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, notFound, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, ok, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, paymentRequired, permanentRedirect, permanentRedirect, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, preconditionRequired, redirect, redirect, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, requestHeaderFieldsTooLarge, seeOther, seeOther, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, status, temporaryRedirect, temporaryRedirect, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, tooManyRequests, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unauthorized, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType, unsupportedMediaType

Methods inherited from class java.lang.Object

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

Method Detail

testToken

public play.mvc.Result testToken()

Returns information about the API token used in the request in JSON.

status

public play.mvc.Result status()

Returns admin status information in JSON

logs

public play.mvc.Result logs(java.lang.String filename)

Returns a JATOS application log file.

Parameters:

filename - Log's filename

Returns:

Returns the log file

studyLog

public play.mvc.Result studyLog(java.lang.String id,
                                int entryLimit,
                                boolean download)
                         throws ForbiddenException,
                                NotFoundException

Returns a study log.

Parameters:

id - Study's ID or UUID

entryLimit - It cuts the log after the number of lines given in entryLimit. Only if 'download' is false.

download - If true streams the whole study log file - if not only until entryLimit

Returns:

Depending on 'download' flag returns the whole study log file - or only part of it (until entryLimit) in reverse order and 'Transfer-Encoding:chunked'

Throws:

ForbiddenException

NotFoundException

getAllStudyPropertiesByUser

public play.mvc.Result getAllStudyPropertiesByUser(java.lang.Boolean withComponentProperties,
                                                   java.lang.Boolean withBatchProperties)
                                            throws java.io.IOException

Returns all study properties a user can access.

Parameters:

withComponentProperties - Flag if true all component properties of the study will be included

withBatchProperties - Flag if true all batch properties will be included

Returns:

All study properties the user has access to (is member of) in JSON

Throws:

java.io.IOException

getStudyProperties

public play.mvc.Result getStudyProperties(java.lang.String id,
                                          java.lang.Boolean withComponentProperties,
                                          java.lang.Boolean withBatchProperties)
                                   throws ForbiddenException,
                                          NotFoundException,
                                          java.io.IOException

Get study properties

Parameters:

id - Study's ID or UUID

withComponentProperties - Flag if true all component properties of the study will be included

withBatchProperties - Flag if true all batch properties will be included

Returns:

The study properties in JSON

Throws:

ForbiddenException

NotFoundException

java.io.IOException

getStudyAssetsStructure

public play.mvc.Result getStudyAssetsStructure(java.lang.String id,
                                               boolean flatten)
                                        throws ForbiddenException,
                                               NotFoundException,
                                               java.io.IOException

Gets the study assets directory structure as JSON

Parameters:

id - Study's ID or UUID

flatten - Flag, if set to `true` the returned JSON will be a flat list of files (no tree, no directories). If `false`, the returned JSON will have tree-like structure and include directories. Default is `false`.

Returns:

JSON with study assets directory structure

Throws:

ForbiddenException

NotFoundException

java.io.IOException

downloadStudyAssetsFile

public play.mvc.Result downloadStudyAssetsFile(java.lang.String id,
                                               java.lang.String filepath)
                                        throws ForbiddenException,
                                               NotFoundException

Download a file from a study assets folder.

Parameters:

id - Study's ID or UUID

filepath - Path to the file in the study assets directory that is supposed to be downloaded. The path can be URL encoded but doesn't have to be. Directories cannot be downloaded.

Throws:

ForbiddenException

NotFoundException

uploadStudyAssetsFile

public play.mvc.Result uploadStudyAssetsFile(play.mvc.Http.Request request,
                                             java.lang.String id,
                                             java.lang.String filepath)
                                      throws ForbiddenException,
                                             NotFoundException

Upload a file to a study assets folder.

Parameters:

id - Study's ID or UUID

filepath - Supposed path of the uploaded file in the study assets directory. If it is null, "", "/" or "." it will be ignored and the uploaded file saved in the top-level of the assets under the uploaded file's name. If it is a directory, the filename is taken from the uploaded file. If it ends with a filename the uploaded file will be renamed to this name. All non-existing subdirectories will be created. Existing files will be overwritten. The path can be URL encoded but doesn't have to be.

Throws:

ForbiddenException

NotFoundException

deleteStudyAssetsFile

public play.mvc.Result deleteStudyAssetsFile(java.lang.String id,
                                             java.lang.String filepath)
                                      throws ForbiddenException,
                                             NotFoundException

Deletes a file in the study assets directory.

Parameters:

id - Study's ID or UUID

filepath - Path to the file in the study assets directory that is supposed to be deleted. The path can be URL encoded but doesn't have to be. Directories cannot be deleted.

Throws:

ForbiddenException

NotFoundException

getStudyCodes

public play.mvc.Result getStudyCodes(java.lang.String id,
                                     scala.Option<java.lang.Long> batchId,
                                     java.lang.String type,
                                     java.lang.String comment,
                                     java.lang.Integer amount)
                              throws ForbiddenException,
                                     NotFoundException,
                                     BadRequestException

Get study codes for the given batch and worker type

Parameters:

id - Study's ID or UUID

batchId - Optional specify the batch ID to which the study codes should belong to. If it is not specified the default batch of this study will be used.

type - Worker type: `PersonalSingle` (or `ps`), `PersonalMultiple` (or `pm`), `GeneralSingle` (or `gs`), `GeneralMultiple` (or `gm`), `MTurk` (or `mt`)

comment - Some comment that will be associated with the worker.

amount - Number of study codes that have to be generated. If empty 1 is assumed.

Throws:

ForbiddenException

NotFoundException

BadRequestException

exportStudy

public play.mvc.Result exportStudy(java.lang.String id)
                            throws ForbiddenException,
                                   NotFoundException

Returns a JATOS study archive (.jzip)

Parameters:

id - Study's ID or UUID

Throws:

ForbiddenException

NotFoundException

deleteStudy

public play.mvc.Result deleteStudy(java.lang.String id)
                            throws ForbiddenException,
                                   NotFoundException,
                                   java.io.IOException

Deletes a study

Parameters:

id - Study's ID or UUID

Throws:

ForbiddenException

NotFoundException

java.io.IOException

importStudy

public play.mvc.Result importStudy(play.mvc.Http.Request request,
                                   boolean keepProperties,
                                   boolean keepAssets,
                                   boolean keepCurrentAssetsName,
                                   boolean renameAssets)
                            throws ForbiddenException,
                                   NotFoundException,
                                   java.io.IOException

Imports a JATOS study archive (.jzip).

Parameters:

keepProperties - If true and the study exists already in JATOS the current properties are kept. Default is `false` (properties are overwritten by default). If the study doesn't already exist this parameter has no effect.

keepAssets - If true and the study exists already in JATOS the current study assets directory is kept. Default is `false` (assets are overwritten by default). If the study doesn't already exist this parameter has no effect.

keepCurrentAssetsName - If the assets are going to be overwritten (`keepAssets=false`), this flag indicates if the study assets directory name is taken form the current or the uploaded one. In the common case that both names are the same this has no effect. But if the current asset directory name is different from the uploaded one a `keepCurrentAssetsName=true` indicates that the name of the currently installed assets directory should be kept. A `false` indicates that the name should be taken from the uploaded one. Default is `true`.

renameAssets - If the study assets directory already exists in JATOS but belongs to a different study it cannot be overwritten. In this case you can set `renameAssets=true` to let JATOS add a suffix to the assets directory name (original name + "_" + a number). Default is `true`.

Throws:

ForbiddenException

NotFoundException

java.io.IOException

removeResults

public play.mvc.Result removeResults(play.mvc.Http.Request request)
                              throws BadRequestException,
                                     ForbiddenException,
                                     NotFoundException

Removes results from the database (ComponentResults and StudyResults) and result files from the file system. Which results are to be removed are indicated by query parameters and/or JSON in the request's body. Different IDs can be used, e.g. study ID (to delete all results of this study), component results (all of this component), batch ID (all of this batch). Of course component result IDs or study result IDs can be specified directly. It primarily removes the ComponentResults since results are associated with them, but if in the process a StudyResults becomes empty (no more ComponentResults) it will be deleted too.

Throws:

BadRequestException

ForbiddenException

NotFoundException

exportResults

public play.mvc.Result exportResults(play.mvc.Http.Request request,
                                     java.lang.Boolean isApiCall)
                              throws BadRequestException

Returns results (including metadata, data, and files) in a zip file. The results are specified by IDs (can be nearly any kind) in the request's body or as query parameters. Streaming is used to reduce memory and disk usage.

Parameters:

isApiCall - If true the response JSON gets an additional 'apiVersion' field

Throws:

BadRequestException

exportResultMetadata

public play.mvc.Result exportResultMetadata(play.mvc.Http.Request request,
                                            java.lang.Boolean isApiCall)
                                     throws ForbiddenException,
                                            BadRequestException,
                                            NotFoundException,
                                            java.io.IOException

Returns all result's metadata (but not result files and not metadata) in a zip file. The results are specified by IDs (can be any kind) in the request's body or query parameters. Streaming is used to reduce memory and disk usage.

Parameters:

isApiCall - If true the response JSON gets an additional 'apiVersion' field

Throws:

ForbiddenException

BadRequestException

NotFoundException

java.io.IOException

exportResultData

public play.mvc.Result exportResultData(play.mvc.Http.Request request,
                                        boolean asPlainText,
                                        boolean isApiCall)
                                 throws ForbiddenException,
                                        BadRequestException,
                                        NotFoundException

Returns result data only (not the result files, not the metadata). Data is stored in ComponentResults. Returns the result data as plain text (each result data in a new line) or in a zip file (each result data in its own file). The results are specified by IDs (can be any kind) in the request's body or as query parameters. Both options use streaming to reduce memory and disk usage.

Parameters:

asPlainText - If true the results will be returned in one single text file, each result in a new line.

isApiCall - If true the response JSON gets an additional 'apiVersion' field

Throws:

ForbiddenException

BadRequestException

NotFoundException

exportResultFiles

public play.mvc.Result exportResultFiles(play.mvc.Http.Request request)
                                  throws java.io.IOException,
                                         ForbiddenException,
                                         BadRequestException,
                                         NotFoundException

Returns all result files (not result data and not metadata) belonging to results in a zip. The results are specified by IDs (can be any kind) in the request's body or as query parameters. Streaming is used to reduce memory and disk usage.

Throws:

java.io.IOException

ForbiddenException

BadRequestException

NotFoundException

exportSingleResultFile

public play.mvc.Result exportSingleResultFile(java.lang.Long componentResultId,
                                              java.lang.String filename)
                                       throws ForbiddenException,
                                              NotFoundException

Exports a single result file.

Parameters:

componentResultId - ID of the component result that the file belongs to

filename - Filename of the file to be exported

Throws:

ForbiddenException

NotFoundException