USING gate FROM A COMMAND LINE

Last updated: 28-Sep-2023

Each entry on this page includes a code block showing an example command line. This may be copied into an editor of choice (such as notepad++) and changed as needed.

Each of these examples uses the "wget" command for simplicity. Other choices like "curl" or even "postman" also work. The URL of each "wget" command must be enclosed in double-quote (") characters because many of the URLs include characters that are otherwise interpreted as special characters by the "bash" command-line shell.

The modified result can be pasted into a standard SSH client like putty in order to get the result of running the (modified) command.

Each successful (200) response is a JSON-encoded Javascript literal object containing the requested information.

NOTE: A prefix of @ in this document means that the identifier refers to a query-string parameter in the URL of an endpoint. For example, "@prName" refers to the left-hand side of a query string pair like "prName=anndeletePR", where the right-hand side is the value of the query-string parameter.

Each query-string of each endpoint is sequence of query-string pairs separated by an ampersand ("&") character.

The value of each query-string pair must be URL-encoded. One convenient tool for obtaining a URL-encoded string is (URlEncoder).

• Setup

  • Load ANNIE Plugin

  wget "https://hoyo.zeetix.com:5101/gate/v0/plugin/mavenPlugin?group=uk.ac.gate.plugins&artifact=annie&version=9.1"
  

• Operations

  • GateCorpus

    • withName

      Answers the instance of GateCorpus with @corpusName, creating it only if needed.

      This example uses a corpusName of "testCorpus1".

      Answers a 400 "Bad Request" if a corpusName is not provided

      wget "https://hoyo.zeetix.com:5101/gate/v0/corpus/withName?corpusName=testCorpus1"
      

    • names

      Answers a list containing the names of the currently loaded instances of GateCorpus

      wget "https://hoyo.zeetix.com:5101/gate/v0/corpus/names"
      

    • named

      Answers the currently-loaded instance of GateCorpus with @corpusName.

      Answers a 400 "Bad Request" if a corpusName is not provided

      Answers a 404 "Not Found" if the given corpusName is not currently loaded.

      This example uses the corpusName "testCorpus1".

      wget "https://hoyo.zeetix.com:5101/gate/v0/corpus/named?corpusName=testCorpus1"
      

    • addDocument

      Adds a loaded instance of GateDocument with @documentName into the loaded instance of GateCorpus with @corpusName.

      The documentName is the URL or path used to create the instance of GateDocument.

      NOTE: The value of documentName must be URL-encoded. The tool used to create these examples is URlEncoder.

      Answers a 400 "Bad Request" if either a corpusName or a documentName is not provided.

      Answers a 404 "Not Found" if either the given corpusName or the given documentName is not currently loaded.

      This example uses the following corpusName and documentName:

      corpusName: "testCorpus1"

      documentName: "%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html"

      wget "https://hoyo.zeetix.com:5101/gate/v0/corpus/addDocument?corpusName=testCorpus1&documentName=%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html"
      

    • cleanup

      Removes any references to @corpusName from both gate and gated.

      NOTE: This endpoint is NOT idempotent -- it is an error to call this endpoint more than once with the same corpusName without an intervening call to the withName endpoint.

      Answers a 400 "Bad Request" if a corpusName is not provided

      Answers a 404 "Not Found" if the given corpusName is not currently loaded.

      wget "https://hoyo.zeetix.com:5101/gate/v0/corpus/cleanup?corpusName=testCorpus1"
      

  • GateDocument

    • withURL

      Answers an instance of GateDocument with @url, creating it only if needed.

      The provided url is used as the documentName in future endpoint calls that reference the result.

      This example uses a url of "https%3A%2F%2Fgate.ac.uk". This the URL-encoded form of "https://gate.ac.uk"

      Answers a 400 "Bad Request" if a url is not provided

      wget "https://hoyo.zeetix.com:5101/gate/v0/document/withURL?url=https%3A%2F%2Fgate.ac.uk"
      

    • withPath

      Answers an instance of GateDocument with @path, creating it only if needed.

      The provided path is used as the documentName in future endpoint calls that reference the result.

      This example uses a path of "%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html". This the URL-encoded form of "/home/tms/backend/gate/test_classes/GateClasses/GateObject/GateComponent/inputData/gateDocumentTest_sample.html"

      wget "https://hoyo.zeetix.com:5101/gate/v0/document/withPath?path=%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html"
      

    • names

      Answers a list containing the name of each currently loaded instance of GateDocument

      wget "https://hoyo.zeetix.com:5101/gate/v0/document/names"
      

    • named

      Answers the currently-loaded instance of GateDocument with @documentName.

      Answers a 400 "Bad Request" if a documentName is not provided

      Answers a 404 "Not Found" if the given documentName is not currently loaded.

      This example uses the documentName "%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html".

      wget "https://hoyo.zeetix.com:5101/gate/v0/document/named?documentName=%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html"
      

    • content

      Answers the full (text) content of the currently-loaded instance of GateDocument with @documentName.

      Answers a 400 "Bad Request" if a documentName is not provided

      Answers a 404 "Not Found" if the given documentName is not currently loaded.

      This example uses the documentName "%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html".

      wget "https://hoyo.zeetix.com:5101/gate/v0/document/content?documentName=%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html"
      

    • annotationSetNames

      Answers the annotationSetNames of the currently-loaded instance of GateDocument with @documentName.

      Answers a 400 "Bad Request" if a documentName is not provided

      Answers a 404 "Not Found" if the given documentName is not currently loaded.

      This example uses the documentName "%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html".

      wget "https://hoyo.zeetix.com:5101/gate/v0/document/annotationSetNames?documentName=%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html"
      

    • annotations (default)

      Answers an instance of AnnotationSet containing the default annotations of the currently-loaded instance of GateDocument with @documentName.

      An instance of AnnotationSet has a possibly empty list of unique instances of Annotation.

      Each instance of Annotation has a type (such as "Token" or "SpaceToken"), a startNode and endNode (each an instance of Node with a unique ID and offset within the document content), and a features object.

      Each features object has a "kind" whose value describes the annotation (such as "control" or "word"), a "string" that contains the document fragment that the annotation pertains to and a length of that fragment.

      Answers a 400 "Bad Request" if a documentName is not provided

      Answers a 404 "Not Found" if the given documentName is not currently loaded.

      This example uses the documentName "%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html".

      wget "https://hoyo.zeetix.com:5101/gate/v0/document/annotations?documentName=%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html"
      

    • annotations (specified)

      Answers an instance of AnnotationSet containing the annotations of the @annotationSet for the currently-loaded instance of GateDocument with @documentName.

      An instance of AnnotationSet has a possibly empty list of unique instances of Annotation.

      Each instance of Annotation has a type (such as "Token" or "SpaceToken"), a startNode and endNode (each an instance of Node with a unique ID and offset within the document content), and a features object.

      Each features object has a "kind" whose value describes the annotation (such as "control" or "word"), a "string" that contains the document fragment that the annotation pertains to and a length of that fragment.

      Answers a 400 "Bad Request" if a documentName is not provided

      Answers a 404 "Not Found" if the given documentName is not currently loaded.

      This example uses a documentName of: "%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html".

      This example uses an annotationSet of: "Original%20markups", the URL-encoded form of "Original markups".

      wget "https://hoyo.zeetix.com:5101/gate/v0/document/annotations?documentName=%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html&annotationSetName=Original%20markups"
      

    • cleanup

      Removes any references to @documentName from both gate and gated.

      NOTE: This endpoint is NOT idempotent -- it is an error to call this endpoint more than once with the same documentName without an intervening call to the withURL or withPath endpoint.

      Answers a 400 "Bad Request" if a documentName is not provided

      Answers a 404 "Not Found" if the given documentName is not currently loaded.

      wget "https://hoyo.zeetix.com:5101/gate/v0/document/cleanup?documentName=%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineTest_sample.html"
      

  • GatePipeline

    • corpusGet

      Answers the instance of GateCorpus referenced by @pipelineName. Fails if no corpus has been set in the specifed pipeline.

      This example uses a pipelineName of "pipelineForTesting".

      Answers a 400 "Bad Request" if a pipelineName is not provided

      Answers a 404 "Not Found" if no pipeline named pipelineName exists.

      Answers a 404 "Not Found" if the pipeline has no corpus

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/corpusGet?pipelineName=pipelineForTesting"
      

    • corpusName

      Answers the name of the GateCorpus referenced by @pipelineName. Fails if no corpus has been set in the specifed pipeline.

      This example uses a pipelineName of "pipelineForTesting".

      Answers a 400 "Bad Request" if a pipelineName is not provided

      Answers a 404 "Not Found" if no pipeline named pipelineName exists.

      Answers a 404 "Not Found" if the pipeline has no corpus

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/corpusName?pipelineName=pipelineForTesting"
      

    • corpusSet

      Makes the loaded corpus named @corpusName be the corpus of the GatePipeline referenced by @pipelineName.

      This example uses a pipelineName of "pipelineForTesting" and a corpusName of "testCorpus1".

      Answers a 400 "Bad Request" if a pipelineName is not provided

      Answers a 400 "Bad Request" if a corpusName is not provided

      Answers a 404 "Not Found" if no pipeline named pipelineName exists.

      Answers a 404 "Not Found" if no corpus named corpusName exists.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/corpusSet?pipelineName=pipelineForTesting&corpusName=testCorpus1"
      

    • load

      Makes the existing pipeline named @pipelineName match the stored pipeline with full filesystem path of the provided path.

      This example uses a pipelineName of "pipelineForTesting".

      This example uses a path of "%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineForTesting.xgapp". This the URL-encoded form of "/home/tms/backend/gate/test_classes/GateClasses/GateObject/GateComponent/inputData/gatePipelineForTesting.xgapp"

      Answers a 400 "Bad Request" if a pipelineName is not provided.

      Answers a 400 "Bad Request" if a path is not provided.

      Answers a 404 "Not Found" if no pipeline named pipelineName exists.

      Answers a 404 "Not Found" if the file at the specified path cannot be loaded.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/load?pipelineName=pipelineForTesting&path=%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FinputData%2FgatePipelineForTesting.xgapp"
      

    • names

      Answers a list containing the name of each currently loaded instance of GatePipeline

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/names"
      

    • named

      Answers the currently-loaded instance of GatePipeline with the given pipelineName.

      This example uses a pipelineName of "pipelineForTesting".

      Answers a 400 "Bad Request" if a pipelineName is not provided

      Answers a 404 "Not Found" if the given pipelineName is not currently loaded.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/named?pipelineName=pipelineForTesting"
      

    • parameterValueGet

      Answers the current value of the parameter named @parameterName of the processing resource named @prName already added to the instance of GatePipeline named @pipelineName.

      This example uses a pipelineName of "pipelineForTesting", a prName of "anndeletePR", and a parameterName of "setsToKeep".

      Answers a 400 "Bad Request" if any of pipelineName, prName, or parameterName is not provided.

      Answers a 404 "Not Found" if no pipeline named pipelineName exists, no ProcessingResource named prName is contained by the pipeline, or if the specified ProcessingResource has no parameter named paramaterName.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/parameterValueGet?pipelineName=pipelineForTesting&prName=anndeletePR&parameterName=setsToKeep"
      

    • parameterValueSet

      Sets the current value of the parameter named @parameterName of the processing resource named @prName already added to the instance of GatePipeline with @pipelineName. The value of the designated parameter is changed to @parameterValue with type @parameterType.

      This example uses a pipelineName of "pipelineForTesting", a prName of "anndeletePR", a parameterName of "setsToKeep", a parameterValue of "Key, Target" ("Key%2C%20Target"), and a parameterType of "List" ("List%3CString%3E").

      NOTE: For list types (such as "List"), the provided parameter value should NOT include the list delimiters ("[", "]").

      Answers a 400 "Bad Request" if any of pipelineName, prName, parameterName, parameterValue, or parameterType is not provided.

      The parameterValue and parameterType arguments are URL-encoded strings that correspond to Key, Target and List<String>.

      Answers a 404 "Not Found" if

      • no pipeline named pipelineName exists, or
      • no ProcessingResource named prName is contained by the pipeline, or
      • the specified ProcessingResource has no parameter named parameterName, or
      • the provided parameterValue has the wrong type, or
      • the provided parameterType is invalid for the specified parameterName.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/parameterValueSet?pipelineName=pipelineForTesting&prName=anndeletePR&parameterName=setsToKeep&parameterValue=Key%2C%20Target&parameterType=List%3CString%3E"
      

    • prAdd (anndeletePR)

      Adds the already loaded instance of ProcessingResource named @prName to the GatePipeline referenced by @pipelineName. Fails if @prName does not reference an already-loaded instance of ProcessingResource.

      This example uses a pipelineName of "pipelineForTesting" and a prName of "anndeletePR".

      Answers a 400 "Bad Request" if a pipelineName is not provided

      Answers a 400 "Bad Request" if a prName is not provided

      Answers a 404 "Not Found" if no pipeline named pipelineName exists.

      Answers a 404 "Not Found" if no ProcessingResource named prName exists.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/prAdd?pipelineName=pipelineForTesting&prName=anndeletePR"
      

    • prAdd (defToken)

      This example uses a pipelineName of "pipelineForTesting" and a prName of "defToken". It is provided as a convenience so that the example pipeline produces non-trivial annotations.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/prAdd?pipelineName=pipelineForTesting&prName=defToken"
      

    • prNames

      Answers a list containing the name of each currently loaded ProcessingResource of the instance of GatePipeline specified by @pipelineName.

      Answers a 400 "Bad Request" if a @pipelineName is not provided

      Answers a 404 "Not Found" if no pipeline named @pipelineName exists.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/prNames?pipelineName=pipelineForTesting"
      

    • run

      Runs the GatePipeline specified by @pipelineName. Each instance of ProcessingResource added to the pipeline will be applied to each instance of GateDocument contained by the corpus of the pipeline. Fails if the specified pipeline is not runnable.

      Answers a 400 "Bad Request" if a @pipelineName is not provided

      Answers a 404 "Not Found" if no pipeline named @pipelineName exists.

      Answers a 404 "Not Found" if the pipeline named @pipelineName is not runnable.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/run?pipelineName=pipelineForTesting"
      

    • store

      Stores the pipeline named @pipelineName to full filesystem path of the provided @path, replacing any existing file at that path. Fails if the designated path is not writable.

      This example uses a pipelineName of "pipelineForTesting".

      This example uses a path of "%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FoutputData%2FgatePipelineForTesting.xgapp". This the URL-encoded form of "/home/tms/backend/gate/test_classes/GateClasses/GateObject/GateComponent/outputData/gatePipelineForTesting.xgapp"

      Answers a 400 "Bad Request" if @pipelineName is not provided

      Answers a 400 "Bad Request" if @path is not provided

      Answers a 404 "Not Found" if no pipeline named @pipelineName exists.

      Answers a 404 "Not Found" if the file at @path cannot be stored.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/store?pipelineName=pipelineForTesting&path=%2Fhome%2Ftms%2Fbackend%2Ftests%2Ftest_classes%2FBackendServices%2FGateService%2FoutputData%2FgatePipelineForTesting.xgapp"
      

    • withName

      Answers an instance of GatePipeline with @pipelineName, creating it only if needed.

      This example uses a pipelineName of "pipelineForTesting".

      Answers a 400 "Bad Request" if a pipelineName is not provided

      wget "https://hoyo.zeetix.com:5101/gate/v0/pipeline/withName?pipelineName=pipelineForTesting"
      

  • ProcessingResource (PR)

    • withPR (anndeletePR)

      Answers an instance of ProcessingResource with @prName and @resourcePath, creating it only if needed. The value of @path is a dot-separated Java class name that specifies the a CREOLE resource within the loaded plugin that contains it. Fails if the containing plugin is not loaded.

      The value of @prName is arbitrary and is used to identify the loaded ProcessingResource for the remainder of the session.

      This example uses a prName of "pipelineForTesting" and a resourcePath of "gate.creole.annotdelete.AnnotationDeletePR"

      Answers a 400 "Bad Request" if either @pipelineName or @resourcePath is not provided.

      Answers a 404 "Not Found" if no ProcessingResource can be loaded from @resourcePath.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pr/withPR?prName=anndeletePR&resourcePath=gate.creole.annotdelete.AnnotationDeletePR"
      

    • withPR (defToken)

      Answers an instance of the "DefaultTokeniser". This is provided for convenience, because it is used by the example pipeline.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pr/withPR?prName=defToken&gate.creole.tokeniser.DefaultTokeniser"
      

    • reinitPR

      Reinitializes the loaded instance of ProcessingResource with @prName and @resourcePath. Restores each runtime parameter of @prName to its default value.

      This operation allows the parameters of the loaded instance of ProcessingResource to be reset while preserving each internal reference within any other CREOLE resource that references the designated instance of ProcessingResource.

      The value of @path is a dot-separated Java class name that specifies a CREOLE resource within the loaded plugin that provides it. Fails if the containing plugin is not loaded.

      The value of @prName is arbitrary and is used to identify the loaded ProcessingResource for the remainder of the session.

      This example uses a prName of "anndeletePR" and a resourcePath of "gate.creole.annotdelete.AnnotationDeletePR"

      Answers a 400 "Bad Request" if either @pipelineName or @resourcePath is not provided.

      Answers a 404 "Not Found" if no ProcessingResource can be loaded from @resourcePath.

      wget "https://hoyo.zeetix.com:5101/gate/v0/pr/reinitPR?prName=anndeletePR&resourcePath=gate.creole.annotdelete.AnnotationDeletePR"
      

• Cleanup

  • Cleanup gated

    Reinitializes the GateDaemon used by gated. Cleans up and discards each GATE-core resource currently referenced by gated. This is an idempotent operation and therefore can be safely called more than once.

    This endpoint has no operation or arguments.

    wget "https://hoyo.zeetix.com:5101/gate/v0/cleanup"
    

  • Reset Shared state

    Reinitializes the shared state of gate service. Cleans up and discards each Javascript resource currently referenced by gate. This is an idempotent operation and therefore can be safely called more than once.

    This endpoint has no operation or arguments.

    wget "https://hoyo.zeetix.com:5101/gate/v0/resetSharedState"