Package nzilbb.labbcat.server.api.edit.fragment

Class Upload

  • @RequiredRole("edit")
public class Upload
extends APIRequestHandler
    /api/edit/fragment/upload[/*] : Handler for receiving, analysing, and processing one fragment annotation file.

    /api/edit/fragment/upload

    POST method requests start the process by uploading a fragment file, e.g. a Praat TextGrid representing several layers of annotation for a single utterance in a transcript.

    The multipart-encoded parameters are:

    fragment (or 'uploadfile', for backward compatibility)
    Fragment annotation file to upload. The name must include the transcript name, and the time range of the fragment, e.g. to update layers in interview01.trs for the fragment from 12.345s to 678.910s, the file should be called something like interview01__12.345-678.910.TextGrid
    automaticMapping
    If present and set to "true", this parameter indicates that default parameters for processing the upload (e.g. mappings from TextGrid tiers to LaBB-CAT layers) should be automatically applied, and the resulting data should be immediately saved, instead of using the two-step process of first uploading the file via POST and then setting parameters via PUT.

    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/fragment/upload/... for finalizing the upload parameters.
    transcript
    The name of the transcript, inferred from the fragment file name.
    start
    The start time of the fragment, inferred from the fragment file name.
    end
    The end time of the fragment, inferred from the fragment file name.
    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/fragment/upload/.... This subsequent call must be made to finish the upload process, even if parameters is an empty array.

    The parameters e.g. mappings from tiers to LaBB-CAT layers.

    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/fragment/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/fragment/upload/...

    PUT method requests receive parameters required to finish parsing the uploaded fragment file and save changes to LaBB-CAT's annotation graph store.

    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(e.g. mappings from tiers to LaBB-CAT layers).

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

    id
    The upload ID passed in.
    transcript
    The name of the transcript, inferred from the fragment file name.
    start
    The start time of the fragment, inferred from the fragment file name.
    end
    The end time of the fragment, inferred from the fragment file name.
    url
    The URL for the fragment, in the context of the whole transcript.
    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 of error.
        Returns:
        JSON-encoded object representing the response

      • put

        public javax.json.JsonObject put​(String pathInfo,
                                 RequestParameters requestParameters,
                                 Consumer<Integer> httpStatus)
        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 of error.
        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 of error.
        Returns:
        JSON-encoded object representing the response