edu.stanford.nlp.pipeline

Class WebServiceAnnotator

java.lang.Object

edu.stanford.nlp.pipeline.WebServiceAnnotator

All Implemented Interfaces:

Annotator

Direct Known Subclasses:

GenericWebServiceAnnotator

public abstract class WebServiceAnnotator
extends java.lang.Object
implements Annotator

A common base class for annotators that talk to other web servers. The important things to do to implement this is:

1. Implement annotateImpl(Annotation) with the code to actually call the server.
2. Implement ready(boolean initialTest) with code to check if the server is available. ping(String) may be useful for this.
3. Optionally implement startCommand() with a command to start a local server. If this is specified, we will start a local server before we start checking for readiness. Note that the ready(boolean initialTest) endpoint does still have to point to this local server in that case, or else lifecycle won't be managed properly.

Author:

Gabor Angeli

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	WebServiceAnnotator.PermanentlyFailedException An exception thrown if we could not connect to the server, and shouldn't retry / recreate the server.
static class	WebServiceAnnotator.ShouldRetryException Thrown if we could not annotate, but there's hope to either reconnect or restart the server.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	everLive If true, we have connected to the server at some point.
protected boolean	serverWasActive If true, the server was active last time checked

Fields inherited from interface edu.stanford.nlp.pipeline.Annotator

DEFAULT_REQUIREMENTS, STANFORD_CDC_TOKENIZE, STANFORD_CLEAN_XML, STANFORD_COLUMN_DATA_CLASSIFIER, STANFORD_COREF, STANFORD_COREF_MENTION, STANFORD_DEPENDENCIES, STANFORD_DETERMINISTIC_COREF, STANFORD_DOCDATE, STANFORD_ENTITY_MENTIONS, STANFORD_GENDER, STANFORD_KBP, STANFORD_LEMMA, STANFORD_LINK, STANFORD_MWT, STANFORD_NATLOG, STANFORD_NER, STANFORD_OPENIE, STANFORD_PARSE, STANFORD_POS, STANFORD_QUOTE, STANFORD_QUOTE_ATTRIBUTION, STANFORD_REGEXNER, STANFORD_RELATION, STANFORD_SENTIMENT, STANFORD_SSPLIT, STANFORD_TOKENIZE, STANFORD_TOKENSREGEX, STANFORD_TRUECASE, STANFORD_UD_FEATURES

Constructor Summary

Constructors

Constructor and Description
WebServiceAnnotator()

Method Summary

Modifier and Type	Method and Description
void	annotate(Annotation annotation) Given an Annotation, perform a task on this Annotation.
protected abstract void	annotateImpl(Annotation ann) Actually annotate a document with the server.
protected void	ensureServer() Ensure that the server we're trying to connect to exists.
protected boolean	live() Check if the server is live.
static void	main(java.lang.String[] args) A quick script to debug server lifecycle.
protected boolean	ping(java.lang.String uri) A utility to ping an endpoint.
protected abstract boolean	ready(boolean initialTest) Check if the server is ready to accept annotations.
protected abstract java.util.Optional<java.lang.String[]>	startCommand() The command to run to start the server, if any.
protected abstract java.util.Optional<java.lang.String[]>	stopCommand() An optional command provided to run to shut down the server.
void	unmount() A block of code called when this annotator unmounts from the AnnotatorPool.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface edu.stanford.nlp.pipeline.Annotator

exactRequirements, requirementsSatisfied, requires

Field Detail

everLive

protected boolean everLive

If true, we have connected to the server at some point.

serverWasActive

protected boolean serverWasActive

If true, the server was active last time checked

Constructor Detail

WebServiceAnnotator

public WebServiceAnnotator()

Method Detail

startCommand

protected abstract java.util.Optional<java.lang.String[]> startCommand()

The command to run to start the server, if any. If no command is given, we assume it's being managed by someone else (e.g., an external running service).

Returns:

The command we should start, or Optional.empty() if we don't want CoreNLP to manage the server.

stopCommand

protected abstract java.util.Optional<java.lang.String[]> stopCommand()

An optional command provided to run to shut down the server.

ready

protected abstract boolean ready(boolean initialTest)

Check if the server is ready to accept annotations. This client will wait until the ready endpoint returns true.

Parameters:

initialTest - testing a server that has just been started?

Returns:

True if the server is ready to accept documents to annotate.

annotateImpl

protected abstract void annotateImpl(Annotation ann)
                              throws WebServiceAnnotator.ShouldRetryException,
                                     WebServiceAnnotator.PermanentlyFailedException

Actually annotate a document with the server.

Parameters:

ann - The document to annotate.

Throws:

WebServiceAnnotator.ShouldRetryException - Thrown if we could not annotate the document, but we could plausibly retry.

WebServiceAnnotator.PermanentlyFailedException - Thrown if we could not annotate the document and should not retry.

live

protected boolean live()

Check if the server is live. Can be overwritten if it differs from ready(boolean initialTest).

Returns:

True if the server is live.

ping

protected boolean ping(java.lang.String uri)

A utility to ping an endpoint. Useful for live() and ready(boolean initialTest).

Parameters:

uri - The URL we are trying to ping.

Returns:

True if we got any non-5XX response from the endpoint.

ensureServer

protected void ensureServer()
                     throws java.util.concurrent.TimeoutException,
                            java.io.IOException

Ensure that the server we're trying to connect to exists. This is certainly called from annotate(Annotation), but can also be called from the constructor of the annotator to cache startup times.

Throws:

java.util.concurrent.TimeoutException - Thrown if we could not connect to the server for the timeout period.

java.io.IOException - Thrown if we could not start the server process.

unmount

public void unmount()

A block of code called when this annotator unmounts from the AnnotatorPool. By default, nothing is done.

Specified by:

unmount in interface Annotator

annotate

public void annotate(Annotation annotation)

Given an Annotation, perform a task on this Annotation.

Specified by:

annotate in interface Annotator

main

public static void main(java.lang.String[] args)
                 throws java.lang.InterruptedException

A quick script to debug server lifecycle.

Throws:

java.lang.InterruptedException