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.
    • csv_layers - (Optional) Alternative to csv_layer which is a single value for all IDs, where the IDs are delimited by a newline character.
    • 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).
    • annotationsPerLayer - (Optional) Alternative to include_count_... which specifies the number of annotations on all layers to return. The value must be an integer.
    • 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
      • data_version - the version of the data, which is the value of the dataVerson system attribute, or if that is unset, the current time.
      • 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. If the parameter is not specified, 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.
      If no offsets should be returned at all, specify a value of "none".
    • targetOffset - (Optional) The distance from the original target of the match, e.g.
      • 0 - find annotations of the match target itself (the default if absent)
      • 1 - find annotations of the token immediately after match target
      • -1 - find annotations of the token immediately before match target
    • plus - (Optional) When targetOffset is a positive value, offset columns are labelled like "Token+1 phonemes" etc. But some consumers (I'm looking at you, R) mutate non-alphanumerics, converting these into "Token.1.phonemes", removing the sign so positive and negative values are indistinguishable. So this parameter allows substitutes for "Token+", e.g. Token.plus."
    • minus - (Optional) When targetOffset is a negative value, offset columns are labelled like "Token-1 phonemes" etc. But some consumers (I'm looking at you, R) mutate non-alphanumerics, converting these into "Token.1.phonemes", removing the sign so positive and negative values are indistinguishable. So this parameter allows substitutes for "Token-", e.g. Token.minus."
    • 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 of 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