Executing Services

Interactive and Batch requests

Services can be called in two ways: Manually via a browser web interface, or programmatically via a client program running on your side. See below for details on each of them.

Both ways allow submitting either interactive or batch requests.

Interactive requests are served immediately (or an error is returned if it is not possible to attend the request). The client is blocked until the end of the request. Interactive requests are intended for analyzing relatively short documents where processing time is a vital factor.

Batch requests are queued and processed as soon as possible. The client receives a job id code that can be used later to retrieve the results of the processing. Batch requests are intended to analyze long documents or large multidocument collections, or when processing time is not a vital factor.

Batch requests take as input ZIP files containing one or more plain text files. Interactive requests take as input plain text (in a form text box) or a single plain text file.

Submitting Jobs via Web Browser

A registered user can submit a text for analysis from the "Execute" form in the Service Catalog. The form will require the user to select the type of request (Interactive/Batch), to provide the service parameters (e.g. language, desired output format...), and the text to be analyzed (either writting it in a text box or uploading a file).

When clicking "Execute" the request will be sent. If it is a batch request, the user will get a job id for later result retrieval. If it is an interactive request, the user will get a file in the desired output format (XML, json, etc.)

Submitting Jobs via a Remote Client

TextServer becomes most useful when used from a remote client. This allows you to integrate into your application the results of our language analyzers.

To call TextServer services from a remote client you need a program that sends a POST request with the right parameters to the right URL. Since this is easier to say than to do, we provide a set of example clients you can use as a basis to write your own.

Retrieving Results for a Batch Request

When the user submits a batch request, TextServer responds with a Token ID that will identify the job and allow retrieval of the results when it is done.

The user can retrieve the results manually in the web page, or programmatically from a remote client. Example clients to retrieve batch requests results are provided.

TextServer will notify the user via email when the job is finished. Alteratively, the user can poll TextServer periodically to find out whether job results are ready.

When the user attempts to retrieve the results of an unfinished job, TextServer will respond with a HTTP 503 error message (Service Unavailable) containing the TextServer error code TS-125 (job not finished) in the message body.

The retrieval can be done to the user convenience (e.g. the same client can send the request and sleep for a while before polling the server to get the results, or you can have an independent cron job that polls for all sent requests once every hour, or you can add a trigger in your mail that will launch the retrieval when the "job completed" mail is received, etc.)

What if I get "NO SERVERS AVAILABLE" ?

TextServer keeps an array of loaded servers for each provided service. If the service is not requested, the servers are stopped to save resources. If a request arrives and there are no running servers (or all loaded servers are busy), the user may get the "no servers available, try again later" error. However, when this happens, TextServer launches new servers. So, if the request is sent again after a short time, it will be attended by those newly created servers.

Notice that depending on the service, loading a server may take some time (from a few seconds to a couple of minutes), so it is wise to wait a reasonable time before sending the request again.