Package nzilbb.labbcat.server.api

Class Results

  • public class Results
extends APIRequestHandler
    /api/results : Provides access to search results.

    Input HTTP parameters:

    • threadId - The search task ID returned by a previous call to /api/search.
    • utterance - MatchIds for the selected results to return, if only a subset is required. This parameter is specified multiple times for multiple values.
    • words_context - How many words of context before and after the match to include in the result text.
    • pageLength - How many results to return at a time.
    • pageNumber - The zero-based number of the page of results to return.
    • content-type - (Optional) A parameter to specify the content type of the response, whose value can be text/csv or application/json - this can also be achieved by setting the value of the Accept request header. If neither the request parameter nor the requets header are set, the response is application/json
    • csv_layer - (Optional) IDs of which layers to include in the CSV output. This parameter is specified multiple times for multiple values.
    • include_count_... - (Optional) Parameters that specify the number of annotations on a given layer to return. The name of the paramater is "include_count_" followed by the layer ID, and the value must be an integer. Layers for which no include_count_ parameter is specified will include one annotation in the output (i.e. the first one, if any).
    • csv_option - (Optional) Additional fields to include in the output. This parameter is specified multiple times for multiple values, which can include:
      • labbcat_title - the title of this LaBB-CAT instance
      • labbcat_version - the current version of this LaBB-CAT instance
      • collection_name - the name/description of the search
      • result_number - the ordinal of each result/match
      • series_offset - how far through the episode, in seconds, this transcript occurs.
      • series_length - the total duration, in seconds, of all transcripts in the episode
      • line_time - the start offset of the utterance
      • line_end_time - the end offset of the utterance
      • match - the unique ID of the match
      • target - the unique ID of the match's target annotation
      • word_url - the URL for locating the word token in the transcript
      • result_text - the match text, and the context before and after if required
    • offsetThreshold - the minimum anchor confidence for returning anchor offsets. The default is 50, which means that offsets that are at least automatically aligned will be returned. Use 100 for manually-aligned offsets only, and 0 to return all offsets regardless of confidence.
    • todo - (Optional) A legacy parameter whose value can be csv to specify that the content-type of the result be text/csv

    At least one of threadId or utterance must be specified.
    Output: a JSON-encoded response object of the usual structure for which the "model" contains the results of the search, e.g. 

    {
    "title":"search",
    "version" : "20230502.0924",
    "code" : 0,
    "errors" : [],
    "messages" : [],
    "model" : {
        "name" : "_^(test)$",
        "matches" : [{
             "MatchId" : "g_22;em_12_73;n_1130-n_1130;p_7;#=ew_2_8110;prefix=1-;[0]=ew_0_641",
             "Transcript" : "mop03-2b-06.trs",
             "Participant" : "mop03-2b",
             "Corpus" : "CC",
             "Line" : 89.627,
             "LineEnd" : 92.532,
             "BeforeMatch" : "and",
             "Text" : "test -",
             "AfterMatch" : "the",
        },{
             "MatchId" : "g_24;em_12_86;n_1486-n_1486;p_2;#=ew_2_8116;prefix=2-;[0]=ew_0_806",
             "Transcript" : "mop03-2b-07.trs",
             "Participant" : "mop03-2b",
             "Corpus" : "CC",
             "Line" : 318.485,
             "LineEnd" : 322.282,
             "BeforeMatch" : "impairment",
             "Text" : "test",
             "AfterMatch" : "on",
        }]
    }
 }

    The task, when finished, will output a URL for accessing the matches of the search.
    Author:
    Robert Fromont

    • Constructor Detail

      • Results

        public Results()
        Constructor

    • Method Detail

      • get

        public void get​(RequestParameters parameters,
                UnaryOperator<String> requestHeaders,
                OutputStream out,
                Consumer<String> contentTypeConsumer,
                Consumer<String> fileName,
                Consumer<Integer> httpStatus)
        The GET method for the servlet.
        Parameters:
        parameters - Request parameter map.
        requestHeaders - Access to HTTP request headers.
        out - Response body output stream.
        contentTypeConsumer - 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.

      • outputMatchLayerLabels

        public void outputMatchLayerLabels​(org.apache.commons.csv.CSVPrinter csvOut,
                                   nzilbb.ag.Schema schema,
                                   PreparedStatement sqlMatchLayerLabels,
                                   boolean multiWordMatches,
                                   IdMatch result,
                                   nzilbb.ag.Layer layer)
                            throws SQLException,
                                   IOException
        Outputs the concatenated labels of the match for the given layer.
        Parameters:
        csvOut -
        schema -
        sqlMatchLayerLabels -
        multiWordMatches -
        result -
        layer -
        Throws:
        SQLException
        IOException