Package nzilbb.labbcat.server.api.edit.transcript

Class Upload

  • public class Upload
extends APIRequestHandler
    /api/edit/transcript/upload[/*] : Handler for receiving, analysing, and processing one transcript file with associated media/document files.

    /api/edit/transcript/upload

    POST method requests start the process by uploading a transcript and optionally associated media files.

    The multipart-encoded parameters are:

    transcript
    Transcript file to upload. (Normally the file will correspond to a single transcript, but for some formats a single file will contain multiple transcripts.)
    media...
    Media file(s) associated with the transcript(s). The parameter can be repeated for multiple files, and the name of the parameter is media followed by the track suffix; by default there is one track defined with a suffix of (empty string), corresponding to a parameter name media, but there may be other tracks defined, e.g. there may be a track with suffix _interviewer, which would correspond to a parameter name media_interviewer.
    See Store.getMediaTracks(nzilbb.labbcat.server.api.RequestParameters, nzilbb.labbcat.server.db.SqlGraphStoreAdministration) for a list of defined track suffixes.
    merge
    If present, this parameter indicates that the upload corresponds to updates to an existing transcript (or transcripts). If absent, the upload is assumed to represent (a) new transcript(s).

    Output: A JSON-encoded response containing a model with the following attributes:

    id
    A unique identifier for the upload which can be passed into subsequent PUT calls to /api/edit/transcript/upload/... for finalizing the upload parameters.
    parameters
    An array of parameter objects representing information that's still required to finalize the upload. These represent parameters that must be passed into a subsequent PUT call to /api/edit/transcript/upload/.... This subsequent call must be made to finish the upload process, even if parameters is an empty array.

    The parameters returned may include both information required by the format deserializer (e.g. mappings from tiers to LaBB-CAT layers) and also general information required by LaBB-CAT (e.g. the corpus, episode, and type of the transcript).

    Each parameter may contain the following attributes:

    name
    The name that should be used when specifying the value for the parameter when PUTting /api/edit/transcript/upload/....
    label
    A label for the parameter intended for display to the user.
    hint
    A description of the purpose of the parameter, for display to the user.
    type
    The type of the parameter, e.g. String, Double, Integer, Boolean.
    required
    true if the value must be specified, false if it is optional.
    value
    A default value for the parameter.
    possibleValues
    A list of possible values, if the possibilities are limited to a finite set.

    /api/edit/transcript/upload/...

    PUT method requests receive parameters required to finish parsing the uploaded transcript file and save changes to LaBB-CAT's annotation graph store. It may be the case that, for a single POST request, multiple calls to PUT requests are required, depending on what information is required during finalization; e.g. after specifying serialization parameters, LaBB-CAT may still want information about who the main participant is (but may not because the transcript specifies it, or there's only one participant). A thread ID may be returned with parameters that are still required; this means that although further information can be supplied, there is sufficient information to merge/add the transcript and generate annotation layers, etc.

    The request method must be PUT and the URL path following .../upload/ must be the id that was returned by the earlier POST.

    The URL-encoded parameters should include values for the parameters returned by the earlier POST request. These may include both information required by the format deserializer (e.g. mappings from tiers to LaBB-CAT layers) and also general information required by LaBB-CAT, such as:

    labbcat_corpus
    The corpus the new transcript(s) belong(s) to.
    labbcat_episode
    The episode the new transcript(s) belong(s) to.
    labbcat_transcript_type
    The transcript type for the new transcript(s).
    labbcat_generate
    Whether to re-regenerate layers of automated annotations or not.

    Output: A JSON-encoded response containing a model with the following attributes:

    id
    The upload ID passed in, which can be passed into subsequent calls if necessary.
    parameters
    An array of parameter objects representing information that's still required to finalize the upload. These represent parameters that must be passed into a subsequent PUT request. This subsequent request must be made to finish the upload process, even if parameters is an empty array.
    transcripts
    An object for which each attribute key is the name of a transcript, with the value set to the taskId of layer generation, for passing into subsequent calls to thread.

    The parameters returned have the same structure as used by the POST request.

    Author:
    Robert Fromont robert@fromont.net.nz

    • Constructor Detail

      • Upload

        public Upload()
        Default constructor.

    • Method Detail

      • post

        public javax.json.JsonObject post​(RequestParameters requestParameters,
                                  Consumer<Integer> httpStatus)
        The POST method for the servlet.
        Parameters:
        requestParameters - Request parameter map.
        httpStatus - Receives the response status code, in case or error.
        Returns:
        JSON-encoded object representing the response

      • put

        public javax.json.JsonObject put​(String pathInfo,
                                 RequestParameters requestParameters,
                                 Consumer<Integer> httpStatus,
                                 Function<nzilbb.ag.Graph,​String> layerGenerator)
        The PUT method for the servlet.
        Parameters:
        pathInfo - The URL path from which the upload ID can be inferred.
        requestParameters - Request parameter map.
        httpStatus - Receives the response status code, in case or error.
        layerGenerator - A function that will start a layer generation thread for the given transcript, and return the thread ID.
        Returns:
        JSON-encoded object representing the response

      • delete

        public javax.json.JsonObject delete​(String pathInfo,
                                    Consumer<Integer> httpStatus)
        The DELETE method for the servlet.
        Parameters:
        pathInfo - The URL path from which the upload ID can be inferred.
        httpStatus - Receives the response status code, in case or error.
        Returns:
        JSON-encoded object representing the response