Package nzilbb.labbcat

Class LabbcatView

java.lang.Object
nzilbb.labbcat.LabbcatView
All Implemented Interfaces:
nzilbb.ag.GraphStoreQuery
Direct Known Subclasses:
LabbcatEdit
public class LabbcatView extends Object implements nzilbb.ag.GraphStoreQuery
Client-side implementation of nzilbb.ag.GraphStoreQuery.

This class provides only read-only operations, i.e. those that can be performed by users with view permission.

e.g. 

 // create LaBB-CAT client
 LabbcatView labbcat = new LabbcatView("https://labbcat.canterbury.ac.nz", "demo", "demo");
 // get some basic information
 String id = lbbcat.getId();
 String[] layers = labbcat.getLayerIds();
 String[] corpora = labbcat.getCorpusIds();
 String[] documents = labbcat.getTranscriptIdsInCorpus(corpora[0]);
 // search for tokens of "and"
 Matches[] matches = labbcat.getMatches(
     labbcat.search(
        new PatternBuilder().addMatchLayer("orthography", "and").build(),
        participantIds, null, true, false, null, 5), 1);
Author:
Robert Fromont robert@fromont.net.nz

  • Constructor Details

    • LabbcatView

      public LabbcatView()
      Default constructor.

    • LabbcatView

      public LabbcatView(String labbcatUrl) throws MalformedURLException
      Constructor from string URL.
      Parameters:
      labbcatUrl - The base URL of the LaBB-CAT server - e.g. https://labbcat.canterbury.ac.nz/demo/
      Throws:
      MalformedURLException - If the URl is invalid.

    • LabbcatView

      public LabbcatView(String labbcatUrl, String username, String password) throws MalformedURLException
      Constructor with String attributes.
      Parameters:
      labbcatUrl - The base URL of the LaBB-CAT server - e.g. https://labbcat.canterbury.ac.nz/demo/
      username - LaBB-CAT username.
      password - LaBB-CAT password.
      Throws:
      MalformedURLException - If the URl is invalid.

    • LabbcatView

      public LabbcatView(URL labbcatUrl)
      Constructor from URL.
      Parameters:
      labbcatUrl - The base URL of the LaBB-CAT server - e.g. https://labbcat.canterbury.ac.nz/demo/

    • LabbcatView

      public LabbcatView(URL labbcatUrl, String username, String password)
      Constructor with attributes.
      Parameters:
      labbcatUrl - The base URL of the LaBB-CAT server - e.g. https://labbcat.canterbury.ac.nz/demo/
      username - LaBB-CAT username.
      password - LaBB-CAT password.

  • Method Details

    • getLabbcatUrl

      public URL getLabbcatUrl()
      Getter for labbcatUrl: The base URL of the LaBB-CAT server - e.g. https://labbcat.canterbury.ac.nz/demo/
      Returns:
      The base URL of the LaBB-CAT server - e.g. https://labbcat.canterbury.ac.nz/demo/

    • setLabbcatUrl

      public LabbcatView setLabbcatUrl(URL newLabbcatUrl)
      Setter for labbcatUrl: The base URL of the LaBB-CAT server - e.g. https://labbcat.canterbury.ac.nz/demo/
      Parameters:
      newLabbcatUrl - The base URL of the LaBB-CAT server - e.g. https://labbcat.canterbury.ac.nz/demo/
      Returns:
      A reference to this object, so that setters can be chained.

    • getUsername

      public String getUsername()
      Getter for username: LaBB-CAT username.
      Returns:
      LaBB-CAT username.

    • setUsername

      public LabbcatView setUsername(String newUsername)
      Setter for username: LaBB-CAT username.
      Parameters:
      newUsername - LaBB-CAT username.
      Returns:
      A reference to this object, so that setters can be chained.

    • getPassword

      public String getPassword()
      Getter for password: LaBB-CAT password.
      Returns:
      LaBB-CAT password.

    • setPassword

      public LabbcatView setPassword(String newPassword)
      Setter for password: LaBB-CAT password.
      Parameters:
      newPassword - LaBB-CAT password.
      Returns:
      A reference to this object, so that setters can be chained.

    • getBatchMode

      public boolean getBatchMode()
      Getter for batchMode: Whether to run in batch mode or not. If false, the user may be asked to enter username/password if required. Default is false.
      Returns:
      Whether to run in batch mode or not. If false, the user may be asked to enter username/password if required.

    • setBatchMode

      public LabbcatView setBatchMode(boolean newBatchMode)
      Setter for batchMode: Whether to run in batch mode or not. If false, the user may be asked to enter username/password if required.
      Parameters:
      newBatchMode - Whether to run in batch mode or not. If false, the user may be asked to enter username/password if required.
      Returns:
      A reference to this object, so that setters can be chained.

    • getVerbose

      public boolean getVerbose()
      Getter for verbose: Whether to print verbose output or not.
      Returns:
      Whether to print verbose output or not.

    • setVerbose

      public LabbcatView setVerbose(boolean newVerbose)
      Setter for verbose: Whether to print verbose output or not.
      Parameters:
      newVerbose - Whether to print verbose output or not.
      Returns:
      A reference to this object, so that setters can be chained.

    • getMinLabbcatVersion

      public String getMinLabbcatVersion()
      Getter for minLabbcatVersion: Minimum server version required for this API to work properly.
      Returns:
      Minimum server version required for this API to work properly.

    • getResponse

      public Response getResponse()
      Getter for response: The last response received from the server.
      Returns:
      The last response received from the server.

    • setResponse

      public LabbcatView setResponse(Response newResponse)
      Setter for response: The last response received from the server.
      Parameters:
      newResponse - The last response received from the server.
      Returns:
      A reference to this object, so that setters can be chained.

    • getLanguage

      public String getLanguage()
      Getter for language: The language code for server message localization, e.g. "es-AR" for Argentine Spanish.
      Returns:
      The language code for server message localization, e.g. "es-AR" for Argentine Spanish.

    • setLanguage

      public LabbcatView setLanguage(String newLanguage)
      Setter for language: The language code for server message localization, e.g. "es-AR" for Argentine Spanish.
      Parameters:
      newLanguage - The language code for server message localization, e.g. "es-AR" for Argentine Spanish.
      Returns:
      A reference to this object, so that setters can be chained.

    • getRequiredHttpAuthorization

      public String getRequiredHttpAuthorization() throws IOException, nzilbb.ag.StoreException
      Determines whether an authorization string is required for HTTP requests (i.e. whether a username/password is required)
      Returns:
      The authorization string that's required, if any
      Throws:
      IOException - If an IO error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • url

      public URL url(String resource) throws nzilbb.ag.StoreException
      Constructs a URL for the given resource.
      Parameters:
      resource - The relative name of the resource.
      Returns:
      A URL for the given resource.
      Throws:
      nzilbb.ag.StoreException - If the URL is malformed.

    • makeUrl

      public URL makeUrl(String resource) throws nzilbb.ag.StoreException
      Constructs a URL for the given resource.
      Parameters:
      resource - The resource, which must be URLEncoded if necessary. This can be a full URL (e.g. as returned by getMedia(String,String,String,Double,Double)) as long as from the same LaBB-CAT instance.
      Returns:
      A URL for the given resource.
      Throws:
      nzilbb.ag.StoreException - If the URL is malformed.

    • get

      public HttpRequestGet get(String resource) throws IOException, nzilbb.ag.StoreException
      Constructs a GET request for the given resource. The resulting request will be authorized if required, but otherwise has no headers or parameters set.
      Parameters:
      resource - The path to the resource.
      Returns:
      The request.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • post

      public HttpRequestPost post(String resource) throws IOException, nzilbb.ag.StoreException
      Constructs a POST request for the given resource. The resulting request will be authorized if required, but otherwise has no headers or parameters set.
      Parameters:
      resource - The path to the resource.
      Returns:
      The request.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • put

      public HttpRequestPost put(String resource) throws IOException, nzilbb.ag.StoreException
      Constructs a PUT request for the given resource. The resulting request will be authorized if required, but otherwise has no headers or parameters set.
      Parameters:
      resource - The path to the resource.
      Returns:
      The request.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • delete

      public HttpRequestPost delete(String resource) throws IOException, nzilbb.ag.StoreException
      Constructs a DELETE request for the given resource. The resulting request will be authorized if required, but otherwise has no headers or parameters set.
      Parameters:
      resource - The path to the resource.
      Returns:
      The request.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • postMultipart

      public HttpRequestPostMultipart postMultipart(String resource) throws IOException, nzilbb.ag.StoreException
      Constructs a multipart POST request for the given resource. The resulting request will be authorized if required, but otherwise has no headers or parameters set.

      The post-request is remembered, so subsequent calls to cancel() will cancel the request if it's in-course.

      Parameters:
      resource - The path to the resource.
      Returns:
      The request.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • getId

      public String getId() throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets the store's ID.
      Specified by:
      getId in interface nzilbb.ag.GraphStoreQuery
      Returns:
      The annotation store's ID.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getInfo

      public String getInfo() throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets the store's information document.
      Returns:
      An HTML document providing information about the corpus.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getLayerIds

      public String[] getLayerIds() throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets a list of layer IDs (annotation 'types').
      Specified by:
      getLayerIds in interface nzilbb.ag.GraphStoreQuery
      Returns:
      A list of layer IDs.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getLayers

      public nzilbb.ag.Layer[] getLayers() throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets a list of layer definitions.
      Specified by:
      getLayers in interface nzilbb.ag.GraphStoreQuery
      Returns:
      A list of layer definitions.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getSchema

      public nzilbb.ag.Schema getSchema() throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      NOT YET IMPLEMENTED - Gets the layer schema.
      Specified by:
      getSchema in interface nzilbb.ag.GraphStoreQuery
      Returns:
      A schema defining the layers and how they relate to each other.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getLayer

      public nzilbb.ag.Layer getLayer(String id) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets a layer definition.
      Specified by:
      getLayer in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - ID of the layer to get the definition for.
      Returns:
      The definition of the given layer.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getCorpusIds

      public String[] getCorpusIds() throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets a list of corpus IDs.
      Specified by:
      getCorpusIds in interface nzilbb.ag.GraphStoreQuery
      Returns:
      A list of corpus IDs.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getParticipantIds

      public String[] getParticipantIds() throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets a list of participant IDs.
      Specified by:
      getParticipantIds in interface nzilbb.ag.GraphStoreQuery
      Returns:
      A list of participant IDs.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getParticipant

      public nzilbb.ag.Annotation getParticipant(String id, String[] layerIds) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets the participant record specified by the given identifier.
      Specified by:
      getParticipant in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - The ID of the participant, which could be their name or their database annotation ID.
      layerIds - The IDs of the participant attribute layers to load, or null if only participant data is required.
      Returns:
      An annotation representing the participant, or null if the participant was not found.
      Throws:
      nzilbb.ag.StoreException - If an error prevents the operation.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • countMatchingParticipantIds

      public int countMatchingParticipantIds(String expression) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Counts the number of participants that match a particular pattern.
      Specified by:
      countMatchingParticipantIds in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      expression - An expression that determines which participants match.

      The expression language is loosely based on JavaScript; expressions such as the following can be used:

      • /Ada.+/.test(id)
      • labels('corpus').includes('CC')
      • labels('participant_languages').includes('en')
      • labels('transcript_language').includes('en')
      • !/Ada.+/.test(id) && first('corpus').label == 'CC'
      • all('transcript_rating').length > 2
      • all('participant_rating').length = 0
      • !annotators('transcript_rating').includes('labbcat')
      • first('participant_gender').label == 'NA'
      Returns:
      The number of matching participants.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getMatchingParticipantIds

      public String[] getMatchingParticipantIds(String expression, Integer pageLength, Integer pageNumber) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets a list of IDs of participants that match a particular pattern.
      Specified by:
      getMatchingParticipantIds in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      expression - An expression that determines which participants match.

      The expression language is loosely based on JavaScript; expressions such as the following can be used:

      • /Ada.+/.test(id)
      • labels('corpus').includes('CC')
      • labels('participant_languages').includes('en')
      • labels('transcript_language').includes('en')
      • !/Ada.+/.test(id) && first('corpus').label == 'CC'
      • all('transcript_rating').length > 2
      • all('participant_rating').length = 0
      • !annotators('transcript_rating').includes('labbcat')
      • first('participant_gender').label == 'NA'
      pageLength - The maximum number of IDs to return, or null to return all.
      pageNumber - The zero-based page number to return, or null to return the first page.
      Returns:
      A list of participant IDs.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getTranscriptIds

      public String[] getTranscriptIds() throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets a list of transcript IDs.
      Specified by:
      getTranscriptIds in interface nzilbb.ag.GraphStoreQuery
      Returns:
      A list of transcript IDs.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getTranscriptIdsInCorpus

      public String[] getTranscriptIdsInCorpus(String id) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets a list of transcript IDs in the given corpus.
      Specified by:
      getTranscriptIdsInCorpus in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - A corpus ID.
      Returns:
      A list of transcript IDs.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getTranscriptIdsWithParticipant

      public String[] getTranscriptIdsWithParticipant(String id) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets a list of IDs of transcripts that include the given participant.
      Specified by:
      getTranscriptIdsWithParticipant in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - A participant ID.
      Returns:
      A list of transcript IDs.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • countMatchingTranscriptIds

      public int countMatchingTranscriptIds(String expression) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Counts the number of transcripts that match a particular pattern.
      Specified by:
      countMatchingTranscriptIds in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      expression - An expression that determines which transcripts match.

      The expression language is loosely based on JavaScript; expressions such as the following can be used:

      • /Ada.+/.test(id)
      • labels('participant').includes('Robert')
      • ('CC', 'IA', 'MU').includes(first('corpus').label)
      • first('episode').label == 'Ada Aitcheson'
      • first('transcript_scribe').label == 'Robert'
      • first('participant_languages').label == 'en'
      • first('noise').label == 'bell'
      • labels('transcript_languages').includes('en')
      • labels('participant_languages').includes('en')
      • labels('noise').includes('bell')
      • all('transcript_languages').length gt; 1
      • all('participant_languages').length gt; 1
      • all('transcript').length gt; 100
      • annotators('transcript_rating').includes('Robert')
      • !/Ada.+/.test(id) && first('corpus').label == 'CC' && labels('participant').includes('Robert')
      Returns:
      The number of matching transcripts.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getMatchingTranscriptIds

      public String[] getMatchingTranscriptIds(String expression, Integer pageLength, Integer pageNumber, String order) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException

      Gets a list of IDs of transcripts that match a particular pattern.

      The results can be exhaustive, by omitting pageLength and pageNumber, or they can be a subset (a 'page') of results, by given pageLength and pageNumber values.

      The order of the list can be specified. If ommitted, the transcripts are listed in ID order.

      Specified by:
      getMatchingTranscriptIds in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      expression - An expression that determines which transcripts match.

      The expression language is loosely based on JavaScript; expressions such as the following can be used:

      • /Ada.+/.test(id)
      • labels('participant').includes('Robert')
      • ('CC', 'IA', 'MU').includes(first('corpus').label)
      • first('episode').label == 'Ada Aitcheson'
      • first('transcript_scribe').label == 'Robert'
      • first('participant_languages').label == 'en'
      • first('noise').label == 'bell'
      • labels('transcript_languages').includes('en')
      • labels('participant_languages').includes('en')
      • labels('noise').includes('bell')
      • all('transcript_languages').length gt; 1
      • all('participant_languages').length gt; 1
      • all('transcript').length gt; 100
      • annotators('transcript_rating').includes('Robert')
      • !/Ada.+/.test(id) && first('corpus').label == 'CC' && labels('participant').includes('Robert')
      pageLength - The maximum number of IDs to return, or null to return all.
      pageNumber - The zero-based page number to return, or null to return the first page.
      order - The ordering for the list of IDs, a string containing a comma-separated list of expressions, which may be appended by " ASC" or " DESC", or null for transcript ID order.
      Returns:
      A list of transcript IDs.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • countMatchingAnnotations

      public int countMatchingAnnotations(String expression) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Counts the number of annotations that match a particular pattern.
      Specified by:
      countMatchingAnnotations in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      expression - An expression that determines which participants match.

      The expression language is loosely based on JavaScript; expressions such as the following can be used:

      • id == 'ew_0_456'
      • !/th[aeiou].//.test(label)
      • first('participant').label == 'Robert' && first('utterances').start.offset == 12.345
      • graph.id == 'AdaAicheson-01.trs' && layer.id == 'orthography' && start.offset > 10.5
      • previous.id == 'ew_0_456'

      NB all expressions must match by either id or layer.id.

      Returns:
      The number of matching annotations.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getMatchingAnnotations

      public nzilbb.ag.Annotation[] getMatchingAnnotations(String expression, Integer pageLength, Integer pageNumber) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets a list of annotations that match a particular pattern.
      Specified by:
      getMatchingAnnotations in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      expression - An expression that determines which transcripts match.

      The expression language is loosely based on JavaScript; expressions such as the following can be used:

      • id == 'ew_0_456'
      • !/th[aeiou].//.test(label)
      • first('participant').label == 'Robert' && first('utterances').start.offset == 12.345
      • graph.id == 'AdaAicheson-01.trs' && layer.id == 'orthography' && start.offset > 10.5
      • previous.id == 'ew_0_456'

      NB all expressions must match by either id or layer.id.

      pageLength - The maximum number of annotations to return, or null to return all.
      pageNumber - The zero-based page number to return, or null to return the first page.
      Returns:
      A list of matching Annotations.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • aggregateMatchingAnnotations

      public String[] aggregateMatchingAnnotations(String operation, String expression) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Identifies a list of annotations that match a particular pattern, and aggregates their labels.

      This allows for counting, listing distinct labels, etc.

      Specified by:
      aggregateMatchingAnnotations in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      operation - The aggregation operation(s) - e.g.
      DISTINCT
      List the distinct labels.
      MAX
      Return the highest label.
      MIN
      Return the lowest label.
      COUNT
      Return the number of annotations.
      COUNT DISTINCT
      Return the number of distinct labels.
      More than one operation can be specified, by using a comma delimiter. e.g. "DISTINCT,COUNT" will return each distinct label, followed by its count (i.e. the array will have twice the number of elements as there are distinct words, even-indexed elements are the word labels, and odd-indexed elements are the counts).
      expression - An expression that determines which annotations match.

      The expression language is loosely based on JavaScript; expressions such as the following can be used:

      • layer.id == 'orthography'
      • graph.id == 'AdaAicheson-01.trs' && layer.id == 'orthography'

      NB all expressions must match by either id or layer.id.

      Returns:
      A list of results. This may have a single element (e.g. when operation == COUNT), or may be a (long) list of labels (e.g. when operation == DISTINCT. If there are multiple operations then the array will contain a multiple of the number of matching annotations. (e.g. if operation == DISTINCT,COUNT then the array will have twice the number of elements as there are distinct words, even-indexed elements are the word labels, and odd-indexed elements are the counts.)
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • countAnnotations

      public long countAnnotations(String id, String layerId, Integer maxOrdinal) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      Gets the number of annotations on the given layer of the given transcript, but only those with an ordinal less than or equal to the given maximum.
      Specified by:
      countAnnotations in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - The ID of the transcript.
      layerId - The ID of the layer.
      maxOrdinal - The maximum ordinal for the counted annotations. e.g. a maxOrdinal of 1 will ensure that only the first annotation for each parent is counted. If maxOrdinal is null, then all annotations are counted, regardless of their ordinal.
      Returns:
      A (possibly empty) array of annotations.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getAnnotations

      public nzilbb.ag.Annotation[] getAnnotations(String id, String layerId, Integer maxOrdinal, Integer pageLength, Integer pageNumber) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      Gets the annotations on the given layer of the given transcript, but only those with an ordinal less than or equal to the given maximum.
      Specified by:
      getAnnotations in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - The ID of the transcript.
      layerId - The ID of the layer.
      maxOrdinal - The maximum ordinal for the returned annotations. e.g. a maxOrdinal of 1 will ensure that only the first annotation for each parent is returned. If maxOrdinal is null, then all annotations are returned, regardless of their ordinal.
      pageLength - The maximum number of IDs to return, or null to return all.
      pageNumber - The zero-based page number to return, or null to return the first page.
      Returns:
      A (possibly empty) array of annotations.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getMatchAnnotations

      public void getMatchAnnotations(Iterator<String> matchIds, String[] layerIds, int targetOffset, int annotationsPerLayer, Consumer<nzilbb.ag.Annotation[]> consumer) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      NOT YET IMPLEMENTED - Gets the annotations on given layers for a set of match IDs.
      Specified by:
      getMatchAnnotations in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      matchIds - An iterator that supplies match IDs - these may be the contents of the MatchId column in exported search results, token URLs, or annotation IDs.
      layerIds - The layer IDs of the layers to get.
      targetOffset - Which token to get the annotations of; 0 means the match target itself, 1 means the token after the target, -1 means the token before the target, etc.
      annotationsPerLayer - The number of annotations per layer to get; if there's a smaller number of annotations available, the unfilled array elements will be null.
      consumer - A consumer for handling the resulting annotations. Consumer.accept() will be invoked once for each element returned by the matchIds iterator, with an array of Annotation objects. The size of this array will be layerIds.length * annotationsPerLayer, and will be filled in with the available annotations for each layer; when annotations are not available, null is supplied.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getAnchors

      public nzilbb.ag.Anchor[] getAnchors(String id, String[] anchorIds) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      Gets the given anchors in the given transcript.
      Specified by:
      getAnchors in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - The ID of the transcript.
      anchorIds - A list of anchor IDs.
      Returns:
      A (possibly empty) array of anchors.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getTranscript

      public nzilbb.ag.Graph getTranscript(String id) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      Gets a transcript given its ID.
      Specified by:
      getTranscript in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - The given transcript ID.
      Returns:
      The identified transcript.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getTranscript

      public nzilbb.ag.Graph getTranscript(String id, String[] layerIds) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      Gets a transcript given its ID, containing only the given layers.
      Specified by:
      getTranscript in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - The given transcript ID.
      layerIds - The IDs of the layers to load, or null if only transcript data is required.
      Returns:
      The identified transcript.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getFragment

      public nzilbb.ag.Graph getFragment(String transcriptId, String annotationId) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      NOT YET IMPLEMENTED - Gets a fragment of a transcript, given its ID and the ID of an annotation in it that defines the desired fragment.
      Specified by:
      getFragment in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      transcriptId - The ID of the transcript.
      annotationId - The ID of an annotation that defines the bounds of the fragment.
      Returns:
      The identified transcript fragment.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getFragment

      public nzilbb.ag.Graph getFragment(String transcriptId, String annotationId, String[] layerIds) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      NOT YET IMPLEMENTED - Gets a fragment of a graph, given its ID and the ID of an annotation in it that defines the desired fragment, and containing only the given layers.
      Specified by:
      getFragment in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      transcriptId - The ID of the transcript.
      annotationId - The ID of an annotation that defines the bounds of the fragment.
      layerIds - The IDs of the layers to load, or null if only transcript data is required.
      Returns:
      The identified transcript fragment.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getFragment

      public nzilbb.ag.Graph getFragment(String transcriptId, double start, double end, String[] layerIds) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      NOT YET IMPLEMENTED - Gets a fragment of a transcript, given its ID and the start/end offsets that define the desired fragment, and containing only the given layers.
      Specified by:
      getFragment in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      transcriptId - The ID of the transcript.
      start - The start offset of the fragment.
      end - The end offset of the fragment.
      layerIds - The IDs of the layers to load, or null if only transcript data is required.
      Returns:
      The identified transcript fragment.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getFragmentSeries

      public nzilbb.util.MonitorableSeries<nzilbb.ag.Graph> getFragmentSeries(String seriesId, String[] layerIds) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      NOT YET IMPLEMENTED - Gets a series of fragments, given the series' ID, and only the given layers.
      Specified by:
      getFragmentSeries in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      seriesId - The ID of the series.
      layerIds - The IDs of the layers to load, or null if only transcript data is required.
      Returns:
      An enumeratable series of fragments.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getMediaTracks

      public nzilbb.ag.MediaTrackDefinition[] getMediaTracks() throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      List the predefined media tracks available for transcripts.
      Specified by:
      getMediaTracks in interface nzilbb.ag.GraphStoreQuery
      Returns:
      An ordered list of media track definitions.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getAvailableMedia

      public nzilbb.ag.MediaFile[] getAvailableMedia(String id) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      List the media available for the given transcript.
      Specified by:
      getAvailableMedia in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - The transcript ID.
      Returns:
      List of media files available for the given transcript.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getMedia

      public String getMedia(String id, String trackSuffix, String mimeType) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      Gets a given media track for a given transcript.
      Specified by:
      getMedia in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - The transcript ID.
      trackSuffix - The track suffix of the media - see MediaTrackDefinition.suffix.
      mimeType - The MIME type of the media, which may include parameters for type conversion, e.g. "text/wav; samplerate=16000".
      Returns:
      A URL to the given media for the given transcript, or null if the given media doesn't exist.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getMediaFile

      public File getMediaFile(String id, String trackSuffix, String mimeType, File dir) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      Gets a given media track for a given transcript.

      This method calls getMedia(String,String,String) and then downloads the media of the given URL to a file.

      Parameters:
      id - The transcript ID.
      trackSuffix - The track suffix of the media - see MediaTrackDefinition.suffix.
      mimeType - The MIME type of the media, which may include parameters for type conversion, e.g. "text/wav; samplerate=16000".
      dir - A directory in which the files should be stored, or null for a temporary folder. If specified, and the directory doesn't exist, it will be created.
      Returns:
      A file containing the given media, or null if the given media doesn't exist. The caller is responsible for deleting this file once processing is complete.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getMedia

      public String getMedia(String id, String trackSuffix, String mimeType, Double startOffset, Double endOffset) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      Gets a given media track for a given transcript.
      Specified by:
      getMedia in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - The transcript ID.
      trackSuffix - The track suffix of the media - see MediaTrackDefinition.suffix.
      mimeType - The MIME type of the media, which may include parameters for type conversion, e.g. "text/wav; samplerate=16000"
      startOffset - The start offset of the media sample, or null for the start of the whole recording.
      endOffset - The end offset of the media sample, or null for the end of the whole recording.
      Returns:
      A URL to the given media for the given transcript, or null if the given media doesn't exist.
      Throws:
      nzilbb.ag.StoreException - If an error occurs.
      nzilbb.ag.PermissionException - If the operation is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript was not found in the store.

    • getEpisodeDocuments

      public nzilbb.ag.MediaFile[] getEpisodeDocuments(String id) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException, nzilbb.ag.GraphNotFoundException
      Get a list of documents associated with the episode of the given transcript.
      Specified by:
      getEpisodeDocuments in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      id - The transcript ID.
      Returns:
      List of URLs to documents.
      Throws:
      nzilbb.ag.StoreException - If an error prevents the media from being saved.
      nzilbb.ag.PermissionException - If saving the media is not permitted.
      nzilbb.ag.GraphNotFoundException - If the transcript doesn't exist.

    • taskStatus

      public TaskStatus taskStatus(String threadId) throws IOException, nzilbb.ag.StoreException
      Gets the current state of the given task.
      Parameters:
      threadId - The ID of the task.
      Returns:
      The status of the task
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • waitForTask

      public TaskStatus waitForTask(String threadId, int maxSeconds) throws IOException, nzilbb.ag.StoreException
      Wait for the given task to finish.
      Parameters:
      threadId - The ID of the task.
      maxSeconds - The maximum time to wait for the task, or 0 for forever.
      Returns:
      The final task status.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • cancelTask

      public void cancelTask(String threadId) throws IOException, nzilbb.ag.StoreException
      Cancels a running task.
      Parameters:
      threadId - The ID of the task.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • releaseTask

      public void releaseTask(String threadId) throws IOException, nzilbb.ag.StoreException
      Release a finished task, to free up server resources.
      Parameters:
      threadId - The ID of the task.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • getTasks

      public Map<String,TaskStatus> getTasks() throws IOException, nzilbb.ag.StoreException
      Gets a list of all tasks on the server.
      Returns:
      A list of all task statuses.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • cancel

      public void cancel()
      Cancel the current request, if possible.

    • isCancelling

      public boolean isCancelling()
      Determines whether or not the request is being cancelled.
      Returns:
      true, if the last request has been asked to cancel, false otherwise

    • search

      public String search(javax.json.JsonObject pattern, String[] participantIds, String[] transcriptTypes, boolean mainParticipantOnly, Integer offsetThreshold, Integer matchesPerTranscript, Integer overlapThreshold) throws IOException, nzilbb.ag.StoreException
      Searches for tokens that match the given pattern.

      The pattern must match the structure of the search matrix in the browser interface of LaBB-CAT. This is a JSON object with one attribute called columns, which is an array of JSON objects.

      Each element in the columns array contains a JSON object named layers, whose value is a JSON object for patterns to match on each layer, and optionally an element named adj, whose value is a number representing the maximum distance, in tokens, between this column and the next column - if adj is not specified, the value defaults to 1, so tokens are contiguous. Each element in the layers JSON object is named after the layer it matches, and the value is a named list with the following possible attributes:

      pattern
      A regular expression to match against the label
      min
      An inclusive minimum numeric value for the label
      max
      An exclusive maximum numeric value for the label
      not
      TRUE to negate the match
      anchorStart
      TRUE to anchor to the start of the annotation on this layer (i.e. the matching word token will be the first at/after the start of the matching annotation on this layer)
      anchorEnd
      TRUE to anchor to the end of the annotation on this layer (i.e. the matching word token will be the last before/at the end of the matching annotation on this layer)
      target
      TRUE to make this layer the target of the search; the results will contain one row for each match on the target layer

      Examples of valid pattern objects include: 

      // words starting with 'ps...'
  JsonObject pattern = new JsonObject()
     .put("columns", new JsonArray()
          .put(new JsonObject()
               .put("layers", new JsonObject()
                    .put("orthography", new JsonObject()
                         .put("pattern", "ps.*")))));
 
 // the word 'the' followed immediately or with one intervening word by
 // a hapax legomenon (word with a frequency of 1) that doesn't start with a vowel
 JsonObject pattern2 = new JsonObject()
    .put("columns", new JsonArray()
         .put(new JsonObject()
              .put("layers", new JsonObject()
                   .put("orthography", new JsonObject()
                        .put("pattern", "the"))),
              .put("adj", 2)),
         .put(new JsonObject()
              .put("layers", new JsonObject()
                   .put("phonemes", new JsonObject()
                        .put("not", Boolean.TRUE)
                        .put("pattern","[cCEFHiIPqQuUV0123456789~#\\$@].*")),
                   .put("frequency", new JsonObject()
                        .put("max", "2")))));

      The PatternBuilder class is designed to make constructing valid patterns easier: 

       // words starting with 'ps...'
 JsonObject pattern = new PatternBuilder().addMatchLayer("orthography", "ps.*").build();
 
 // the word 'the' followed immediately or with one intervening word by
 // a hapax legomenon (word with a frequency of 1) that doesn't start with a vowel
 JsonObject pattern2 = new PatternBuilder()
    .addColumn()
    .addMatchLayer("orthography", "the")
    .addColumn()
    .addNotMatchLayer("phonemes", "[cCEFHiIPqQuUV0123456789~#\\$@].*")
    .addMaxLayer("frequency", 2)
    .build();
      Parameters:
      pattern - An object representing the pattern to search for, which mirrors the Search Matrix in the browser interface.
      participantIds - An optional list of participant IDs to search the utterances of. If null, all utterances in the corpus will be searched.
      transcriptTypes - An optional list of transcript types to limit the results to. If null, all transcript types will be searched.
      mainParticipantOnly - true to search only main-participant utterances, false to search all utterances.
      offsetThreshold - Optional minimum alignment confidence for matching word or segment annotations. A value of 50 means that annotations that were at least automatically aligned will be returned. Use 100 for manually-aligned annotations only, and 0 or no value to return all matching annotations regardless of alignment confidence.
      matchesPerTranscript - Optional maximum number of matches per transcript to return. null means all matches.
      overlapThreshold - Optional percentage overlap with other utterances before simultaneous speech is excluded. null means include all overlapping utterances.
      Returns:
      The threadId of the resulting task, which can be passed in to getMatches(String,int), taskStatus(String), waitForTask(String,int), etc.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.
      See Also:

    • getMatches

      public Match[] getMatches(String threadId, int wordsContext) throws IOException, nzilbb.ag.StoreException
      Gets a list of tokens that were matched by search(JsonObject,String[],String[],boolean,Integer,Integer,Integer).

      If the task is still running, then this function will wait for it to finish.

      This means calls can be stacked like this: 

      Matches[] matches = labbcat.getMatches(
     labbcat.search(
        new PatternBuilder().addMatchLayer("orthography", "and").build(),
        participantIds, true, true, null, null), 1);
      Parameters:
      threadId - A task ID returned by search(JsonObject,String[],String[],boolean,Integer,Integer,Integer).
      wordsContext - Number of words context to include in the Before Match and After Match columns in the results.
      Returns:
      A list of IDs that can be used to identify utterances/tokens that were matched by search(JsonObject,String[],String[],boolean,Integer,Integer,Integer), or null if the task was cancelled.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.
      See Also:

    • getMatches

      public Match[] getMatches(String threadId, int wordsContext, Integer pageLength, Integer pageNumber) throws IOException, nzilbb.ag.StoreException
      Gets a list of tokens that were matched by search(JsonObject,String[],String[],boolean,Integer,Integer,Integer).

      If the task is still running, then this function will wait for it to finish.

      This means calls can be stacked like this: 

      Matches[] matches = labbcat.getMatches(
     labbcat.search(
        new PatternBuilder().addMatchLayer("orthography", "and").build(),
        participantIds, true, false, null, 5), 1);
      Parameters:
      threadId - A task ID returned by search(JsonObject,String[],String[],boolean,Integer,Integer,Integer).
      wordsContext - Number of words context to include in the Before Match and After Match columns in the results.
      pageLength - The maximum number of matches to return, or null to return all.
      pageNumber - The zero-based page number to return, or null to return the first page.
      Returns:
      A list of IDs that can be used to identify utterances/tokens that were matched by search(JsonObject,String[],String[],boolean,Integer,Integer,Integer), or null if the task was cancelled.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.
      See Also:

    • getMatches

      public Match[] getMatches(javax.json.JsonObject pattern, String[] participantIds, String[] transcriptTypes, boolean mainParticipant, Integer offsetThreshold, Integer matchesPerTranscript, Integer overlapThreshold, int wordsContext) throws IOException, nzilbb.ag.StoreException
      Searches for tokens that match the givem pattern and returns a list of matches.

      This is similar to invoking: 

       Matches[] matches = labbcat.getMatches(
     labbcat.search(pattern, participantIds, mainParticipant, aligned,
                    matchesPerTranscript, overlapThreshold),
     wordsContext);

      As with search(JsonObject,String[],String[],boolean,Integer,Integer,Integer) the pattern must match the structure of the search matrix in the browser interface of LaBB-CAT.

      The PatternBuilder class is designed to make constructing valid patterns easier: 

       // words starting with 'ps...'
 JsonObject pattern = new PatternBuilder().addMatchLayer("orthography", "ps.*").build();
 
 // the word 'the' followed immediately or with one intervening word by
 // a hapax legomenon (word with a frequency of 1) that doesn't start with a vowel
 JsonObject pattern2 = new PatternBuilder()
    .addColumn()
    .addMatchLayer("orthography", "the")
    .addColumn()
    .addNotMatchLayer("phonemes", "[cCEFHiIPqQuUV0123456789~#\\$@].*")
    .addMaxLayer("frequency", 2)
    .build();
      Parameters:
      pattern - An object representing the pattern to search for, which mirrors the Search Matrix in the browser interface.
      participantIds - An optional list of participant IDs to search the utterances of. If not null, all utterances in the corpus will be searched.
      transcriptTypes - An optional list of transcript types to limit the results to. If null, all transcript types will be searched.
      mainParticipant - true to search only main-participant utterances, false to search all utterances.
      offsetThreshold - The minimum confidence for alignments, e.g.
      • 0 - return all alignments, regardless of confidence;
      • 50 - return only alignments that have been at least automatically aligned;
      • 100 - return only manually-set alignments.
      matchesPerTranscript - Optional maximum number of matches per transcript to return. null means all matches.
      overlapThreshold - Optional percentage overlap with other utterances before simultaneous speech is excluded. null means include all overlapping utterances.
      wordsContext - Number of words context to include in the Before Match and After Match columns in the results.
      Returns:
      A list of IDs that can be used to identify utterances/tokens that were matched by search(JsonObject,String[],String[],boolean,Integer,Integer,Integer), or null if the task was cancelled.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.
      See Also:

    • getMatches

      public Match[] getMatches(javax.json.JsonObject pattern, String[] participantIds, String[] transcriptTypes, boolean mainParticipant, Integer offsetThreshold, Integer matchesPerTranscript, Integer overlapThreshold, int wordsContext, Integer maxMatches) throws IOException, nzilbb.ag.StoreException
      Searches for tokens that match the given pattern and returns the first maxMatches matches.

      This is similar to invoking: 

       Matches[] matches = labbcat.getMatches(
     labbcat.search(pattern, participantIds, mainParticipant, aligned,
                    matchesPerTranscript, overlapThreshold), 
     wordsContext);

      As with search(JsonObject,String[],String[],boolean,Integer,Integer,Integer) the pattern must match the structure of the search matrix in the browser interface of LaBB-CAT.

      The PatternBuilder class is designed to make constructing valid patterns easier: 

       // words starting with 'ps...'
 JsonObject pattern = new PatternBuilder().addMatchLayer("orthography", "ps.*").build();
 
 // the word 'the' followed immediately or with one intervening word by
 // a hapax legomenon (word with a frequency of 1) that doesn't start with a vowel
 JsonObject pattern2 = new PatternBuilder()
    .addColumn()
    .addMatchLayer("orthography", "the")
    .addColumn()
    .addNotMatchLayer("phonemes", "[cCEFHiIPqQuUV0123456789~#\\$@].*")
    .addMaxLayer("frequency", 2)
    .build();
      Parameters:
      pattern - An object representing the pattern to search for, which mirrors the Search Matrix in the browser interface.
      participantIds - An optional list of participant IDs to search the utterances of. If not null, all utterances in the corpus will be searched.
      transcriptTypes - An optional list of transcript types to limit the results to. If null, all transcript types will be searched.
      mainParticipant - true to search only main-participant utterances, false to search all utterances.
      offsetThreshold - The minimum confidence for alignments, e.g.
      • 0 - return all alignments, regardless of confidence;
      • 50 - return only alignments that have been at least automatically aligned;
      • 100 - return only manually-set alignments.
      matchesPerTranscript - Optional maximum number of matches per transcript to return. null means all matches.
      overlapThreshold - Optional percentage overlap with other utterances before simultaneous speech is excluded. null means include all overlapping utterances.
      wordsContext - Number of words context to include in the Before Match and After Match columns in the results.
      maxMatches - The maximum number of matches to return, or null to return all.
      Returns:
      A list of IDs that can be used to identify utterances/tokens that were matched by search(JsonObject,String[],String[],boolean,Integer,Integer,Integer), or null if the task was cancelled.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.
      See Also:

    • getMatchAnnotations

      public nzilbb.ag.Annotation[][] getMatchAnnotations(Match[] matches, String[] layerIds, int targetOffset, int annotationsPerLayer) throws IOException, nzilbb.ag.StoreException
      Gets annotations on selected layers related to search results returned by a previous call to getMatches(String,int).
      Parameters:
      matches - A list of Matches.
      layerIds - A vector of layer IDs.
      targetOffset - The distance from the original target of the match, e.g.
      • 0 - find annotations of the match target itself
      • 1 - find annotations of the token immediately after match target
      • -1 - find annotations of the token immediately before match target
      annotationsPerLayer - The number of annotations on the given layer to retrieve. In most cases, there's only one annotation available. However, tokens may, for example, be annotated with `all possible phonemic transcriptions', in which case using a value of greater than 1 for this parameter provides other phonemic transcriptions, for tokens that have more than one.
      Returns:
      An array of arrays of Annotations, of dimensions matchIds.length × (layerIds.length * annotationsPerLayer). The first index matches the corresponding index in matchIds.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.
      See Also:

    • getMatchAnnotations

      public nzilbb.ag.Annotation[][] getMatchAnnotations(String[] matchIds, String[] layerIds, int targetOffset, int annotationsPerLayer) throws IOException, nzilbb.ag.StoreException
      Gets annotations on selected layers related to search results returned by a previous call to getMatches(String,int), taskStatus(String).
      Parameters:
      matchIds - A list of Match.getMatchId()s.
      layerIds - A vector of layer IDs.
      targetOffset - The distance from the original target of the match, e.g.
      • 0 - find annotations of the match target itself
      • 1 - find annotations of the token immediately after match target
      • -1 - find annotations of the token immediately before match target
      annotationsPerLayer - The number of annotations on the given layer to retrieve. In most cases, there's only one annotation available. However, tokens may, for example, be annotated with `all possible phonemic transcriptions', in which case using a value of greater than 1 for this parameter provides other phonemic transcriptions, for tokens that have more than one.
      Returns:
      An array of arrays of Annotations, of dimensions matchIds.length × (layerIds.length * annotationsPerLayer). The first index matches the corresponding index in matchIds.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.
      See Also:

    • getSoundFragments

      public File[] getSoundFragments(Match[] matches, Integer sampleRate, File dir) throws IOException, nzilbb.ag.StoreException
      Downloads WAV sound fragments.

      This utility method translates a Match array of the kind returned by getMatches(String,int) to the parallel arrays required by getSoundFragments(String[],Double[],Double[],Integer,File), using MatchId.

      Parameters:
      matches - A list of Matches, perhaps returned by getMatches(String,int).
      sampleRate - The desired sample rate, or null for no preference.
      dir - A directory in which the files should be stored, or null for a temporary folder. If specified, and the directory doesn't exist, it will be created.
      Returns:
      A list of WAV files. If dir is null, these files will be stored under the system's temporary directory, so once processing is finished, they should be deleted by the caller, or moved to a more permanent location.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • getSoundFragments

      public File[] getSoundFragments(String[] transcriptIds, Double[] startOffsets, Double[] endOffsets, Integer sampleRate, File dir) throws IOException, nzilbb.ag.StoreException
      Downloads WAV sound fragments.
      Parameters:
      transcriptIds - A list of transcript IDs (transcript names).
      startOffsets - A list of start offsets, with one element for each element in transcriptIds.
      endOffsets - A list of end offsets, with one element for each element in transcriptIds.
      sampleRate - The desired sample rate, or null for no preference.
      dir - A directory in which the files should be stored, or null for a temporary folder. If specified, and the directory doesn't exist, it will be created.
      Returns:
      A list of WAV files. If dir is null, these files will be stored under the system's temporary directory, so once processing is finished, they should be deleted by the caller, or moved to a more permanent location.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • getFragments

      public File[] getFragments(Match[] matches, String[] layerIds, String mimeType, File dir) throws IOException, nzilbb.ag.StoreException
      Get transcript fragments in a specified format.

      This utility method translates a Match array of the kind returned by getMatches(String,int) to the parallel arrays required by getFragments(String[],Double[],Double[],String[],String,File), using MatchId.

      Parameters:
      matches - A list of Matches, perhaps returned by getMatches(String,int).
      layerIds - A list of IDs of annotation layers to include in the fragment.
      mimeType - The desired format, for example "text/praat-textgrid" for Praat TextGrids, "text/plain" for plain text, etc.
      dir - A directory in which the files should be stored, or null for a temporary folder. If specified, and the directory doesn't exist, it will be created.
      Returns:
      A list of files. If dir is null, these files will be stored under the system's temporary directory, so once processing is finished, they should be deleted by the caller, or moved to a more permanent location.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • getFragments

      public File[] getFragments(String[] transcriptIds, Double[] startOffsets, Double[] endOffsets, String[] layerIds, String mimeType, File dir) throws IOException, nzilbb.ag.StoreException
      Get transcript fragments in a specified format.
      Parameters:
      transcriptIds - A list of transcript IDs (transcript names).
      startOffsets - A list of start offsets, with one element for each element in transcriptIds.
      endOffsets - A list of end offsets, with one element for each element in transcriptIds.
      layerIds - A list of IDs of annotation layers to include in the fragment.
      mimeType - The desired format, for example "text/praat-textgrid" for Praat TextGrids, "text/plain" for plain text, etc.
      dir - A directory in which the files should be stored, or null for a temporary folder. If specified, and the directory doesn't exist, it will be created.
      Returns:
      A list of files. If dir is null, these files will be stored under the system's temporary directory, so once processing is finished, they should be deleted by the caller, or moved to a more permanent location.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • processWithPraat

      public String processWithPraat(String[] matchIds, Double[] startOffsets, Double[] endOffsets, String praatScript, Double windowOffset, String[] attributes) throws IOException, nzilbb.ag.StoreException
      Executes Praat on the server in order to perform acoustic analysis on a given collection of sound fragments.
      Parameters:
      matchIds - An array of annotation IDs, e.g. the MatchId column, or the URL column, of a results set.
      startOffsets - An array of start times in seconds, which must have the same number of elements as matchIds.
      endOffsets - An array of end times in seconds, which must have the same number of elements as matchIds.
      praatScript - Script to run on each match.
      windowOffset - In many circumstances, you will want some context before and after the sample start/end time. For this reason, you can specify a "window offset" - this is a number of seconds to subtract from the sample start and add to the sample end time, before extracting that part of the audio for processing. For example, if the sample starts at 2.0s and ends at 3.0s, and you set the window offset to 0.5s, then Praat will extract a sample of audio from 1.5s to 3.5s, and do the selected processing on that sample. The best value for this depends on what the praat.script is doing; if you are getting formants from vowels, including some context ensures that the formants at the edges are more accurate (in LaBB-CAT's web interface, the default value for this 0.025), but if you're getting max pitch or COG during a segment, most likely you want a window.offset of 0 to ensure neighbouring segments doesn't influence the measurement.
      attributes - Array of participant attributes to make available to the script. For example, if you want to use different acoustic parameters depending on what the gender of the speaker is, including the "participant_gender" attribute will make a variable called participant_gender$ available to the praat script, whose value will be the gender of the speaker for that segment.
      Returns:
      The threadId of the resulting task, the result of which will be a CSV file containing acoustic measurs. The threadId can be passed in to taskStatus(String), waitForTask(String,int), etc.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • processWithPraat

      public String processWithPraat(String[] transcriptIds, String[] participantIds, Double[] startOffsets, Double[] endOffsets, String script, Double windowOffset, String[] attributes) throws IOException, nzilbb.ag.StoreException
      Executes Praat on the server in order to perform acoustic analysis on a given collection of sound fragments.
      Parameters:
      transcriptIds - An array of Transcript IDs identifying the recording that the sample comes from.
      participantIds - An array of Participant IDs, which must have the same number of elements as transcriptIds, identifying the speaker of the speech sample (e.g. so that their gender can be identified, for calibrating script parameters).
      startOffsets - An array of start times in seconds, which must have the same number of elements as transcriptIds.
      endOffsets - An array of end times in seconds, which must have the same number of elements as transcriptIds.
      script - Praat script to run on each match.
      windowOffset - In many circumstances, you will want some context before and after the sample start/end time. For this reason, you can specify a "window offset" - this is a number of seconds to subtract from the sample start and add to the sample end time, before extracting that part of the audio for processing. For example, if the sample starts at 2.0s and ends at 3.0s, and you set the window offset to 0.5s, then Praat will extract a sample of audio from 1.5s to 3.5s, and do the selected processing on that sample. The best value for this depends on what the praat.script is doing; if you are getting formants from vowels, including some context ensures that the formants at the edges are more accurate (in LaBB-CAT's web interface, the default value for this 0.025), but if you're getting max pitch or COG during a segment, most likely you want a window.offset of 0 to ensure neighbouring segments doesn't influence the measurement.
      attributes - Array of participant attributes to make available to the script. For example, if you want to use different acoustic parameters depending on what the gender of the speaker is, including the "participant_gender" attribute will make a variable called participant_gender$ available to the praat script, whose value will be the gender of the speaker for that segment.
      Returns:
      The threadId of the resulting task, the result of which will be a CSV file containing acoustic measurs. The threadId can be passed in to taskStatus(String), waitForTask(String,int), etc.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • getTranscriptAttributes

      public File getTranscriptAttributes(String[] transcriptIds, String[] layerIds) throws IOException, nzilbb.ag.StoreException
      Gets transcript attribute values for given transcript IDs.
      Parameters:
      transcriptIds - A list of transcript IDs (transcript names).
      layerIds - A list of layer IDs corresponding to transcript attributes. In general, these are layers whose ID is prefixed 'transcript_', however formally it's any layer where layer.getParentId().equals("graph") && layer.getAlignment() == 0, which includes "corpus" as well as transcript attribute layers.
      Returns:
      A CSV file with the attribute values, which it is the caller's responsibility to delete once processing is finished.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • getParticipantAttributes

      public File getParticipantAttributes(String[] participantIds, String[] layerIds) throws IOException, nzilbb.ag.StoreException
      Gets participant attribute values for given participant IDs.
      Parameters:
      participantIds - A list of participant IDs (participant names).
      layerIds - A list of layer IDs corresponding to participant attributes. In general, these are layers whose ID is prefixed 'participant_', however formally it's any layer where layer.getParentId().equals("parent") && layer.getAlignment() == 0.
      Returns:
      A CSV file with the attribute values, which it is the caller's responsibility to delete once processing is finished.
      Throws:
      IOException - If a communications error occurs.
      nzilbb.ag.StoreException - If the server returns an error.

    • getSerializerDescriptors

      public nzilbb.ag.serialize.SerializationDescriptor[] getSerializerDescriptors() throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Lists the descriptors of all registered serializers.

      Serializers are modules that export annotation structures as a specific file format, e.g. Praat TextGrid, plain text, etc., so the SerializationDescriptor.getMimeType() of descriptors reflects what mimeTypes can be specified for getFragments(String[],Double[],Double[],String[],String,File) and getFragments(Match[],String[],String,File).

      Specified by:
      getSerializerDescriptors in interface nzilbb.ag.GraphStoreQuery
      Returns:
      A list of the descriptors of all registered serializers.
      Throws:
      nzilbb.ag.StoreException - If an error prevents the operation from completing.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getDeserializerDescriptors

      public nzilbb.ag.serialize.SerializationDescriptor[] getDeserializerDescriptors() throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Lists the descriptors of all registered deserializers.

      Deserializers are modules that import annotation structures from a specific file format, e.g. Praat TextGrid, plain text, etc.

      Specified by:
      getDeserializerDescriptors in interface nzilbb.ag.GraphStoreQuery
      Returns:
      A list of the descriptors of all registered deserializers.
      Throws:
      nzilbb.ag.StoreException - If an error prevents the descriptors from being listed.
      nzilbb.ag.PermissionException - If listing the deserializers is not permitted.

    • serializerForFilesSuffix

      public nzilbb.ag.serialize.GraphSerializer serializerForFilesSuffix(String suffix) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      NOT YET IMPLEMENTED - Gets the serializer for the given file suffix (extension).
      Specified by:
      serializerForFilesSuffix in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      suffix - The file extension.
      Returns:
      The serializer for the given suffix, or null if none is registered.
      Throws:
      nzilbb.ag.StoreException - If an error prevents the operation.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • deserializerForMimeType

      public nzilbb.ag.serialize.GraphDeserializer deserializerForMimeType(String mimeType) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      NOT YET IMPLEMENTED - Gets the deserializer for the given MIME type.
      Specified by:
      deserializerForMimeType in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      mimeType - The MIME type.
      Returns:
      The deserializer for the given MIME type, or null if none is registered.
      Throws:
      nzilbb.ag.StoreException - If an error prevents the operation.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • deserializerForFilesSuffix

      public nzilbb.ag.serialize.GraphDeserializer deserializerForFilesSuffix(String suffix) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      NOT YET IMPLEMENTED - Gets the deserializer for the given file suffix (extension).
      Specified by:
      deserializerForFilesSuffix in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      suffix - The file extension.
      Returns:
      The deserializer for the given suffix, or null if none is registered.
      Throws:
      nzilbb.ag.StoreException - If an error prevents the operation.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • serializerForMimeType

      public nzilbb.ag.serialize.GraphSerializer serializerForMimeType(String mimeType) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      NOT YET IMPLEMENTED - Gets the serializer for the given MIME type.
      Specified by:
      serializerForMimeType in interface nzilbb.ag.GraphStoreQuery
      Parameters:
      mimeType - The MIME type.
      Returns:
      The serializer for the given MIME type, or null if none is registered.
      Throws:
      nzilbb.ag.StoreException - If an error prevents the operation.
      nzilbb.ag.PermissionException - If the operation is not permitted.

    • getAnnotatorDescriptor

      public nzilbb.ag.automation.util.AnnotatorDescriptor getAnnotatorDescriptor(String annotatorId) throws nzilbb.ag.StoreException, ResponseException
      Gets a descriptor of the annotator with the given ID.
      Parameters:
      annotatorId - The ID of the annotator.
      Returns:
      A descriptor of the given annotator, or null if there is no registered annotator with the given ID.
      Throws:
      nzilbb.ag.StoreException - If the server returns an error.
      ResponseException - If some other error occurs.

    • getTranscriberDescriptors

      public nzilbb.ag.automation.util.AnnotatorDescriptor[] getTranscriberDescriptors()
      Lists descriptors of all transcribers that are installed.
      Specified by:
      getTranscriberDescriptors in interface nzilbb.ag.GraphStoreQuery
      Returns:
      A list of descriptors of all transcribers that are installed.

    • getSystemAttribute

      public String getSystemAttribute(String attribute) throws nzilbb.ag.StoreException, nzilbb.ag.PermissionException
      Gets the value of the given system attribute.
      Parameters:
      attribute - Name of the attribute.
      Returns:
      The value of the given attribute.
      Throws:
      nzilbb.ag.StoreException - If an error prevents the descriptors from being listed.
      nzilbb.ag.PermissionException - If listing the deserializers is not permitted.

    • getUserInfo

      public User getUserInfo() throws nzilbb.ag.StoreException
      Gets information about the current user, including the roles or groups they are in.
      Returns:
      The user record.
      Throws:
      nzilbb.ag.StoreException - If an error occurs while trying to retrieve the user information.

    • getDictionaries

      public Map<String,List<String>> getDictionaries() throws nzilbb.ag.StoreException
      List dictionaries available.
      Returns:
      A map of layer manager IDs to lists of dictionary IDs.
      Throws:
      nzilbb.ag.StoreException - If an error prevents the operation.

    • getDictionaryEntries

      public File getDictionaryEntries(String managerId, String dictionaryId, String[] keys) throws nzilbb.ag.StoreException
      Lookup entries in a dictionary.
      Parameters:
      managerId - The ID of the layer manager.
      dictionaryId - The ID of the dictionary.
      keys - The keys to fetch entries for.
      Returns:
      A CSV file with the entries, which it is the caller's responsibility to delete once processing is finished.
      Throws:
      nzilbb.ag.StoreException - If an error prevents the operation.

    • FileNameFromContentDisposition

      public static String FileNameFromContentDisposition(String contentDisposition)
      Infers the filename from a given Content-Disposition header.
      Parameters:
      contentDisposition - The Content-Disposition header, or null.
      Returns:
      Suggested file name, or null if none could be determined.