Package controllers.gui

Class Api

  • All Implemented Interfaces:
    play.mvc.Http.HeaderNames, play.mvc.Http.Status
    @Singleton
public class Api
extends play.mvc.Controller
    JATOS API Controller

    • Field Summary

      • 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

      • 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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      play.mvc.Result addMemberToStudy​(java.lang.String id, java.lang.Long userId)  
      play.mvc.Result allApiTokenMetadataByUser​(java.lang.Long userId)
      List the metadata of all tokens that belong to a user.
      play.mvc.Result allMembersOfStudy​(java.lang.String id)
      Get user IDs of all members of a study.
      play.mvc.Result allUsers()
      Get information about all users.
      play.mvc.Result apiTokenMetadata​(java.lang.Long id)
      Get the metadata of an API token specified by its ID.
      play.mvc.Result changeMemberOfStudy​(java.lang.String id, java.lang.Long userId, boolean isMember)  
      play.mvc.Result changeUserRole​(play.mvc.Http.Request request, java.lang.Long id)  
      play.mvc.Result checkStudyExists​(java.lang.String id)
      HEAD requests: checks if a study exists in the system by its ID or UUID.
      play.mvc.Result checkUserExists​(java.lang.Long id)
      HEAD requests: checks if a user exists
      play.mvc.Result createBatch​(play.mvc.Http.Request request, java.lang.String studyId)  
      play.mvc.Result createComponent​(play.mvc.Http.Request request, java.lang.String studyId)
      Creates a component within the specified study
      play.mvc.Result createStudy​(play.mvc.Http.Request request)
      Handels deprecated endpoint to create a new study
      play.mvc.Result createUser​(play.mvc.Http.Request request)  
      play.mvc.Result currentApiTokenMetadata()
      Returns metadata of the API token used in this request
      play.mvc.Result deleteApiToken​(java.lang.Long id)
      Admins can delete tokens of non-admin users.
      play.mvc.Result deleteBatch​(java.lang.String id)  
      play.mvc.Result deleteComponent​(java.lang.String id)  
      play.mvc.Result deleteStudy​(java.lang.String id)  
      play.mvc.Result deleteStudyAssetsFile​(java.lang.String id, java.lang.String filepath)
      Deletes a file in the study assets directory.
      play.mvc.Result deleteUser​(java.lang.Long id)  
      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 download, 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, boolean download, 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 the study archive (.jzip) as a file
      play.mvc.Result generateApiToken​(play.mvc.Http.Request request, java.lang.Long userId)
      Generate API tokens.
      play.mvc.Result getAllStudyPropertiesOfSignedinUser​(java.lang.Boolean withComponentProperties, java.lang.Boolean withBatchProperties)
      Returns all study properties a user can access.
      play.mvc.Result getBatch​(java.lang.String id)  
      play.mvc.Result getBatchesByStudy​(java.lang.String studyId)  
      play.mvc.Result getBatchSession​(java.lang.String id, boolean asText)  
      play.mvc.Result getComponent​(java.lang.String id)  
      play.mvc.Result getComponentsByStudy​(java.lang.String studyIdOrUuid)  
      play.mvc.Result getGroupSession​(java.lang.Long id, boolean asText)  
      play.mvc.Result getGroupsOfBatch​(java.lang.String id)  
      play.mvc.Result getOrGenerateStudyCodes​(play.mvc.Http.Request request, java.lang.String studyId, scala.Option<java.lang.Long> batchIdOption, java.lang.String type, java.lang.String comment, scala.Option<java.lang.Integer> amountOption)
      Get or generate study codes for the given study, batch, and worker type.
      play.mvc.Result getStudyAssetsStructure​(java.lang.String id, boolean flatten)
      Gets the study assets directory structure as JSON
      play.mvc.Result getStudyCode​(java.lang.String code)  
      play.mvc.Result getStudyProperties​(java.lang.String id, java.lang.Boolean withComponentProperties, java.lang.Boolean withBatchProperties)
      Get study properties
      play.mvc.Result getUser​(java.lang.Long id)
      Get info of a user.
      play.mvc.Result importOrCreateStudy​(play.mvc.Http.Request request, boolean keepProperties, boolean keepAssets, boolean keepCurrentAssetsName, boolean renameAssets)
      Dispatches the request based on the Content-Type header: 1) ZIP / multipart upload → import a study archive 2) JSON → create a new study from the request body.
      play.mvc.Result importStudy​(play.mvc.Http.Request request, boolean keepProperties, boolean keepAssets, boolean keepCurrentAssetsName, boolean renameAssets)
      Imports a JATOS study archive
      play.mvc.Result listLogs()
      Returns the content of the logs directory as JSON
      play.mvc.Result logs​(java.lang.String filename, java.lang.Integer lineLimit, boolean reverse)
      Returns the log file specified by 'filename'.
      play.mvc.Result removeMemberFromStudy​(java.lang.String id, java.lang.Long userId)  
      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 toggleApiTokenActive​(play.mvc.Http.Request request, java.lang.Long id)
      Activate or deactivate a token specified by its ID.
      play.mvc.Result toggleStudyCodeActive​(play.mvc.Http.Request request, java.lang.String code)  
      play.mvc.Result updateBatch​(play.mvc.Http.Request request, java.lang.String id)  
      play.mvc.Result updateBatchSession​(play.mvc.Http.Request request, java.lang.String id, scala.Option<java.lang.Long> version)
      Updates the batch session.
      play.mvc.Result updateComponent​(play.mvc.Http.Request request, java.lang.String id)  
      play.mvc.Result updateGroupSession​(play.mvc.Http.Request request, java.lang.Long id, scala.Option<java.lang.Long> version)
      Updates the group session.
      play.mvc.Result updateStudyProperties​(play.mvc.Http.Request request, java.lang.String id)
      Updates the study properties.
      play.mvc.Result updateUser​(play.mvc.Http.Request request, java.lang.Long id)  
      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

      • currentApiTokenMetadata

        public play.mvc.Result currentApiTokenMetadata()
        Returns metadata of the API token used in this request

      • status

        public play.mvc.Result status()
        Returns admin status information in JSON. Only with admin tokens.

      • listLogs

        public play.mvc.Result listLogs()
                         throws java.io.IOException
        Returns the content of the logs directory as JSON
        Throws:
        java.io.IOException

      • logs

        public play.mvc.Result logs​(java.lang.String filename,
                            java.lang.Integer lineLimit,
                            boolean reverse)
                     throws NotFoundException
        Returns the log file specified by 'filename'. If 'reverse' is true, it returns the content of the file in reverse order and as 'Transfer-Encoding:chunked'. It limits the number of lines to the given lineLimit. If 'reverse' is false, it returns the file for download.
        Throws:
        NotFoundException

      • allUsers

        public play.mvc.Result allUsers()
                         throws java.io.IOException
        Get information about all users. Only with admin tokens.
        Throws:
        java.io.IOException

      • checkUserExists

        public play.mvc.Result checkUserExists​(java.lang.Long id)
        HEAD requests: checks if a user exists

      • getUser

        public play.mvc.Result getUser​(java.lang.Long id)
                        throws HttpException,
                               java.io.IOException
        Get info of a user.
        Throws:
        HttpException
        java.io.IOException

      • updateUser

        public play.mvc.Result updateUser​(play.mvc.Http.Request request,
                                  java.lang.Long id)
                           throws HttpException,
                                  java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • changeUserRole

        public play.mvc.Result changeUserRole​(play.mvc.Http.Request request,
                                      java.lang.Long id)
                               throws HttpException,
                                      java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • deleteUser

        public play.mvc.Result deleteUser​(java.lang.Long id)
                           throws java.io.IOException,
                                  HttpException
        Throws:
        java.io.IOException
        HttpException

      • generateApiToken

        public play.mvc.Result generateApiToken​(play.mvc.Http.Request request,
                                        java.lang.Long userId)
                                 throws HttpException
        Generate API tokens. It returns the token and the token metadata.
        Throws:
        HttpException

      • allApiTokenMetadataByUser

        public play.mvc.Result allApiTokenMetadataByUser​(java.lang.Long userId)
                                          throws HttpException
        List the metadata of all tokens that belong to a user.
        Throws:
        HttpException

      • apiTokenMetadata

        public play.mvc.Result apiTokenMetadata​(java.lang.Long id)
                                 throws HttpException
        Get the metadata of an API token specified by its ID.
        Throws:
        HttpException

      • toggleApiTokenActive

        public play.mvc.Result toggleApiTokenActive​(play.mvc.Http.Request request,
                                            java.lang.Long id)
                                     throws HttpException
        Activate or deactivate a token specified by its ID. Admins can update tokens of non-admin users. Users (including admins) can update their own tokens.
        Throws:
        HttpException

      • checkStudyExists

        public play.mvc.Result checkStudyExists​(java.lang.String id)
        HEAD requests: checks if a study exists in the system by its ID or UUID. Only with admin tokens.

      • getAllStudyPropertiesOfSignedinUser

        public play.mvc.Result getAllStudyPropertiesOfSignedinUser​(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

      • createStudy

        public play.mvc.Result createStudy​(play.mvc.Http.Request request)
                            throws java.io.IOException,
                                   HttpException
        Handels deprecated endpoint to create a new study
        Throws:
        java.io.IOException
        HttpException

      • importOrCreateStudy

        public play.mvc.Result importOrCreateStudy​(play.mvc.Http.Request request,
                                           boolean keepProperties,
                                           boolean keepAssets,
                                           boolean keepCurrentAssetsName,
                                           boolean renameAssets)
                                    throws HttpException,
                                           java.io.IOException,
                                           ValidationException,
                                           ImportExportException
        Dispatches the request based on the Content-Type header: 1) ZIP / multipart upload → import a study archive 2) JSON → create a new study from the request body. This endpoint supports multiple, mutually exclusive body formats, so it cannot be handled by a single fixed BodyParser annotation. Body parsing is therefore performed explicitly in the respective branches.
        Throws:
        HttpException
        java.io.IOException
        ValidationException
        ImportExportException

      • importStudy

        public play.mvc.Result importStudy​(play.mvc.Http.Request request,
                                   boolean keepProperties,
                                   boolean keepAssets,
                                   boolean keepCurrentAssetsName,
                                   boolean renameAssets)
                            throws HttpException,
                                   java.io.IOException,
                                   ValidationException,
                                   ImportExportException
        Imports a JATOS study archive
        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 from 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:
        HttpException
        java.io.IOException
        ValidationException
        ImportExportException

      • exportStudy

        public play.mvc.Result exportStudy​(java.lang.String id)
                            throws HttpException,
                                   java.io.IOException
        Returns the study archive (.jzip) as a file
        Throws:
        HttpException
        java.io.IOException

      • getStudyProperties

        public play.mvc.Result getStudyProperties​(java.lang.String id,
                                          java.lang.Boolean withComponentProperties,
                                          java.lang.Boolean withBatchProperties)
                                   throws java.io.IOException,
                                          HttpException
        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:
        java.io.IOException
        HttpException

      • updateStudyProperties

        public play.mvc.Result updateStudyProperties​(play.mvc.Http.Request request,
                                             java.lang.String id)
                                      throws java.io.IOException,
                                             HttpException
        Updates the study properties. Regular users may update only studies they own. Admins may update only the activation status of any study.
        Throws:
        java.io.IOException
        HttpException

      • deleteStudy

        public play.mvc.Result deleteStudy​(java.lang.String id)
                            throws HttpException,
                                   java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • getStudyAssetsStructure

        public play.mvc.Result getStudyAssetsStructure​(java.lang.String id,
                                               boolean flatten)
                                        throws java.io.IOException,
                                               HttpException
        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 a tree-like structure and include directories. Default is `false`.
        Returns:
        JSON with study assets directory structure
        Throws:
        java.io.IOException
        HttpException

      • downloadStudyAssetsFile

        public play.mvc.Result downloadStudyAssetsFile​(java.lang.String id,
                                               java.lang.String filepath)
                                        throws HttpException,
                                               java.io.IOException
        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:
        HttpException
        java.io.IOException

      • uploadStudyAssetsFile

        public play.mvc.Result uploadStudyAssetsFile​(play.mvc.Http.Request request,
                                             java.lang.String id,
                                             java.lang.String filepath)
                                      throws HttpException
        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:
        HttpException

      • deleteStudyAssetsFile

        public play.mvc.Result deleteStudyAssetsFile​(java.lang.String id,
                                             java.lang.String filepath)
                                      throws HttpException
        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:
        HttpException

      • allMembersOfStudy

        public play.mvc.Result allMembersOfStudy​(java.lang.String id)
                                  throws HttpException
        Get user IDs of all members of a study.
        Throws:
        HttpException

      • addMemberToStudy

        public play.mvc.Result addMemberToStudy​(java.lang.String id,
                                        java.lang.Long userId)
                                 throws HttpException
        Throws:
        HttpException

      • removeMemberFromStudy

        public play.mvc.Result removeMemberFromStudy​(java.lang.String id,
                                             java.lang.Long userId)
                                      throws HttpException
        Throws:
        HttpException

      • changeMemberOfStudy

        public play.mvc.Result changeMemberOfStudy​(java.lang.String id,
                                           java.lang.Long userId,
                                           boolean isMember)
                                    throws HttpException
        Throws:
        HttpException

      • studyLog

        public play.mvc.Result studyLog​(java.lang.String id,
                                int entryLimit,
                                boolean download)
                         throws HttpException
        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 the 'download' flag returns the whole study log file - or only part of it (until entryLimit) in reverse order and 'Transfer-Encoding:chunked'
        Throws:
        HttpException

      • createComponent

        public play.mvc.Result createComponent​(play.mvc.Http.Request request,
                                       java.lang.String studyId)
                                throws java.io.IOException,
                                       HttpException
        Creates a component within the specified study
        Throws:
        java.io.IOException
        HttpException

      • getComponentsByStudy

        public play.mvc.Result getComponentsByStudy​(java.lang.String studyIdOrUuid)
                                     throws HttpException,
                                            java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • getComponent

        public play.mvc.Result getComponent​(java.lang.String id)
                             throws HttpException,
                                    java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • updateComponent

        public play.mvc.Result updateComponent​(play.mvc.Http.Request request,
                                       java.lang.String id)
                                throws HttpException,
                                       java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • getBatchesByStudy

        public play.mvc.Result getBatchesByStudy​(java.lang.String studyId)
                                  throws HttpException,
                                         java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • getBatch

        public play.mvc.Result getBatch​(java.lang.String id)
                         throws HttpException,
                                java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • createBatch

        public play.mvc.Result createBatch​(play.mvc.Http.Request request,
                                   java.lang.String studyId)
                            throws HttpException,
                                   java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • updateBatch

        public play.mvc.Result updateBatch​(play.mvc.Http.Request request,
                                   java.lang.String id)
                            throws HttpException,
                                   java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • getBatchSession

        public play.mvc.Result getBatchSession​(java.lang.String id,
                                       boolean asText)
                                throws HttpException,
                                       java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • updateBatchSession

        public play.mvc.Result updateBatchSession​(play.mvc.Http.Request request,
                                          java.lang.String id,
                                          scala.Option<java.lang.Long> version)
                                   throws HttpException,
                                          java.io.IOException
        Updates the batch session. Uses `BodyParser.Raw` to handle JSON payloads with potential malformed content gracefully and give detailed error messages to the user.
        Throws:
        HttpException
        java.io.IOException

      • getGroupSession

        public play.mvc.Result getGroupSession​(java.lang.Long id,
                                       boolean asText)
                                throws HttpException,
                                       java.io.IOException
        Throws:
        HttpException
        java.io.IOException

      • updateGroupSession

        public play.mvc.Result updateGroupSession​(play.mvc.Http.Request request,
                                          java.lang.Long id,
                                          scala.Option<java.lang.Long> version)
                                   throws HttpException,
                                          java.io.IOException
        Updates the group session. Uses `BodyParser.Raw` to handle JSON payloads with potential malformed content gracefully and give detailed error messages to the user.
        Throws:
        HttpException
        java.io.IOException

      • getOrGenerateStudyCodes

        public play.mvc.Result getOrGenerateStudyCodes​(play.mvc.Http.Request request,
                                               java.lang.String studyId,
                                               scala.Option<java.lang.Long> batchIdOption,
                                               java.lang.String type,
                                               java.lang.String comment,
                                               scala.Option<java.lang.Integer> amountOption)
                                        throws HttpException
        Get or generate study codes for the given study, batch, and worker type. Either get the properties from the query parameters or the JSON body.
        Parameters:
        studyId - Study's ID or UUID
        batchIdOption - 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.
        amountOption - Number of study codes that have to be generated. If empty, 1 is assumed.
        Throws:
        HttpException

      • toggleStudyCodeActive

        public play.mvc.Result toggleStudyCodeActive​(play.mvc.Http.Request request,
                                             java.lang.String code)
                                      throws HttpException
        Throws:
        HttpException

      • 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,
                                            boolean download,
                                            java.lang.Boolean isApiCall)
                                     throws HttpException,
                                            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
        download - If true, the response JSON is in a file, otherwise in the response body
        Throws:
        HttpException
        java.io.IOException

      • exportResultData

        public play.mvc.Result exportResultData​(play.mvc.Http.Request request,
                                        boolean asPlainText,
                                        boolean download,
                                        boolean isApiCall)
                                 throws HttpException
        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:
        HttpException

      • exportResultFiles

        public play.mvc.Result exportResultFiles​(play.mvc.Http.Request request)
                                  throws BadRequestException
        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:
        BadRequestException

      • exportSingleResultFile

        public play.mvc.Result exportSingleResultFile​(java.lang.Long componentResultId,
                                              java.lang.String filename)
                                       throws HttpException,
                                              java.io.IOException
        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:
        HttpException
        java.io.IOException

      • removeResults

        public play.mvc.Result removeResults​(play.mvc.Http.Request request)
                              throws HttpException
        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 StudyResult becomes empty (no more ComponentResults), it will be deleted too.
        Throws:
        HttpException