Package nzilbb.labbcat.server.api.serialize

Class Fragments

  • public class Fragments
extends APIRequestHandler
    /api/serialize/fragments : Converts transcript fragments to specific formats.

    Converts parts of transcripts to annotation file formats.

    The request method can be GET or POST The servlet expects an array of graph ids, start times and end times, a list of layerIds in include, and a mimetype.

    Input HTTP parameters:

    • mimeType - content-type of the format to serialize to.
    • layerId - a list of layer IDs to include in the serialization.
    • id - one or more graph IDs.
    • start - one or more start times (in seconds).
    • end - one or more end times (in seconds).
    • filter - (optional) one or more annotation IDs to filter by. e.g. a turn annotation ID, which would ensure that only words within the specified turn are included, not words from other turns.
    • threadId - (optional) The search task ID returned by a previous call to /api/search.
    • utterance - (optional) MatchIds for the selected results to return, if only a subset is required. This can be specifed instead of id/start/end parameters. This parameter is specified multiple times for multiple values.
    • name - (optional) name of the collection.
    • prefix - (optional) prefix fragment names with a numeric serial number.
    • tag - (optional) add a tag identifying the target annotation.
    • async - (optional) "true" to start a serialization server task and immediately it's threadId rather than return the actual serialization results.

    Output: if async is ommited, the result is each of the transcript fragments specified by the input parameters converted to the given format. This may be a single file or multiple files, depending on the converter behaviour and how many fragments are specified. If there is only one, the file in returned as the response to the request. If there are more than one, the response is a zip file containing the output files.
    If async == true, the result is a JSON-encoded response object of the usual structure for which the "model" is an object with a "threadId" attribute, which is the ID of the server task to monitor for results. e.g. 
    {
    "title":"Fragments",
    "version" : "20220303.1143",
    "code" : 0,
    "errors" : [],
    "messages" : [],
    "model" : {
        "threadId" : 80
    }
 }

    The task, when finished, will output the same as above (a zip or other file with the fragments in the given format).

    In general, async should not be specified, as it uses more resources (results files must be stored on the server until the whole serialization is finished).

    However, for some serializers (e.g. "text/x-kaldi-text"), it's not possible to return any content until all fragments are processed anyway. In these cases, if the set of fragments is very large, the delay between making the request and receiving the response can be so long that client libraries time out. In such cases, using async=true is preferable, as the serialization can be monitored with a long series of short requests, and then the data tranferred when finally ready.

    Author:
    Robert Fromont

    • Constructor Detail

      • Fragments

        public Fragments()
        Constructor

    • Method Detail

      • getPercentComplete

        public int getPercentComplete()
        PercentComplete accessor
        Returns:
        How far through the speakers.

      • setPercentComplete

        public void setPercentComplete​(int iNewPercentComplete)
        PercentComplete mutator
        Parameters:
        iNewPercentComplete - How far through the speakers.

      • get

        public void get​(RequestParameters parameters,
                OutputStream out,
                Consumer<String> contentType,
                Consumer<String> fileName,
                Consumer<Integer> httpStatus)
        The GET method for the servlet - this expects an array of graph ids, start times and end times, a list of layerIds in include, and a mimetype.

        Input HTTP parameters:

        • mimeType - content-type of the format to serialize to.
        • layerId - a list of layer IDs to include in the serialization.
        • id - one or more graph IDs.
        • start - one or more start times (in seconds).
        • end - one or more end times (in seconds).
        • filter - (optional) one or more annotation IDs to filter by. e.g. a turn annotation ID, which would ensure that only words within the specified turn are included, not words from other turns.
        • name or collection_name - (optional) name of the collection.
        • prefix - (optional) prefix fragment names with a numeric serial number.
        • tag - (optional) add a tag identifying the target annotation.

        Output: A each of the transcript fragments specified by the input parameters converted to the given format. This may be a single file or multiple files, depending on the converter behaviour and how many fragments are specified. If there is only one, the file in returned as the response to the request. If there are more than one, the response is a zipfile containing the output files.
        Parameters:
        parameters - Request parameter map.
        out - Response body stream.
        contentType - Receives the content type for specification in the response headers.
        fileName - Receives the filename for specification in the response headers.
        httpStatus - Receives the response status code, in case or error.

      • cancel

        public void cancel()
        Cancels the currently running exportTextGrids() method.

      • serializeFragments

        public void serializeFragments​(String name,
                               nzilbb.util.MonitorableSeries<nzilbb.ag.Graph> utterances,
                               nzilbb.ag.serialize.GraphSerializer serializer,
                               Consumer<nzilbb.ag.serialize.util.NamedStream> streamConsumer,
                               Consumer<nzilbb.ag.serialize.SerializationException> errorConsumer,
                               String[] layerIds,
                               String mimeType,
                               nzilbb.ag.GraphStoreAdministration store)
                        throws Exception
        Serializes the given series of utterances using the given serializer.
        Parameters:
        name - The name of the collection.
        utterances - Utterances to serialize.
        serializer - The serialization module.
        streamConsumer - Consumer for receiving the serialized streams.
        errorConsumer - Consumer for handling serialization errors.
        layerIds - A list of layer names.
        mimeType -
        store - Graph store.
        Throws:
        Exception