SYNOPSIS
use PMLTQ::CGI;
PMLTQ::CGI::Configure({
# options
});
my $cgi = CGI->new();
...
if ($request eq 'query') {
resp_query($cgi);
} elsif ($request eq 'svg') {
resp_svg($cgi);
} elsif ...
DESCRIPTION
This module is intended to be used in a FastCGI or Net::HTTPServer
environment (see pmltq_http). It implements a REST web service and a
web application to the PML-TQ engine driven by an SQL database
(PMLTQ::SQLEvaluator).
WEB SERVICE
Individual types of request are implemented by the resp_* family of
functions, which all assume a CGI-like object as their first and only
argument.
The web service uses URLs of the form
http(s)://<host>:<port>/<method_prefix><method_name>?<arguments>
or
http(s)://<host>:<port>/<method_prefix><method_name>/<resource-path>?<arguments>
where method_prefix is an optional path prefix, typically empty (see
method-prefix configuration option).
It is up to the HTTP server to do both user authentication and
authorization to the individual web service methods.
WEB APPLICATION
Individual types of request are implemented by a wrapper app()
function, whose first argument is a reference to a corresponding resp_*
function (see "WEB SERVICE") and the second argument is a CGI-like
object.
The web service uses URLs of the form
http(s)://<host>:<port>/<app_prefix>/<method_prefix><method_name>?<arguments>
or
http(s)://<host>:<port>/<app_prefix>/<method_prefix><method_name>/<resource-path>?<arguments>
where <app_prefix> is 'app' by default.
AUTHENTICATION AND AUTHORIZATION
The authorization to the web application depends on the HTTP server to
do both autentication and authorization for all the web service
requests and also the <app_prefix>/<method_prefix>login web application
request. It is not required to do authorization for other
<app_prefix>/<method_prefix>* requests.
The autentication and authorization data are stored in the <auth-file>
configuration file, which contains user names, unencrypted passwords
(optional), and server-ID based access lists for each user.
The HTTP server may use the auth() method provided by this module in
order to obtain a password stored in the <auth-file> (this is what
pmltq_http does). Alternatively, the passwords can be stored in the
server's configuration, e,g. the .htaccess file, and the <auth-file>
can be used just for authorization.
Each web application method (<app_prefix>/<method_prefix>*) first
checks the user and session ID arguments (u and s) for validity and
consults <auth-file> in order to determine if the user is authorized
for the running instance. If the session is valid and the user
authorized, the request is performed. Otherwise the client is
redirected to the <app_prefix>/<method_prefix>login request.
The HTTP server should be configured so as to require HTTP password
authentication for the <app_prefix>/<method_prefix>login request. If
the HTTP server authorizes the client for the
<app_prefix>/<method_prefix>login request, a new session is created for
the user and the client is redirected to the web application start page
(<app_prefix>/<method_prefix>form).
Updates to the <auth-file> apply immediately without needing to restart
the service.
Each line in the <auth-file> may have one the following forms (empty
and invalid lines are ignored):
# <comment> <username> : : <authorization> <username>: <password>
<username>: <password> : <authorization>
where <authorization> is a comma-separated list of server IDs (see the
server configuration option). If the list is preceded by the minus (-)
sign, the user is authorized this service unless the server ID is
present in the list. If this list is preceded by the plus (+) sign or
no sign at all, the user is authorized to connect to this service, if
and only if the server ID is present in the list. If the list
<authorization> list is not present, the user is authorized to connect
to any service.
The information about other services is also used when responding to
the method "other"" in ", which returns basic information about other
running instances (sharing the same <pid-dir> and <auth-file>, but
typically running on different ports or using different prefixes) and
whether the current user is authorized to use them or not.
INITIALIZATION
The module is initialized using a call to the Configure() function:
PMLTQ::CGI::Configure({...options...});
In a forking FastCGI or Net::HTTPServer implementation, this
configuration is typically called just once prior to forking, so as
only one PID file is created for this service (even if the service is
handled by several forked instances).
The configuration options are:
static-dir => $dirname
Directory from which static content is to be served.
config-file => $filename
PML-TQ configuration file (in the PML format described by the
pmltq_cgi_conf_schema.xml schema.
server => $conf_id
ID of the server configuration in the configuration file (see above).
pid-dir => $dirname
Directory where to store a PID file containing basic information
about this running instance (to be used by other instances in order
to provide a list of available services).
This directory is also used to create user session files which may be
reused by other running services as well to provide a single-login
access to a family of related PML-TQ services.
port => $port_number
Port number of this instance. This information is stored into a PID
file and can be used by other running instances in order to determine
the correct URL for the service provided by this instance.
query-log-dir => $dirname
Directory where individual user's queries are logged. The content of
this directory is also used to retrieve previous user's queries.
auth-file => $filename
Path to a file containing user access configuration (note that
cooperation with the HTTP server is required), see "AUTHENTICATION
AND AUTHORIZATION".
tmp-dir => $dirname
A directory to use for temporary files.
google-translate => $bool
Add Google Translator service to the Toolbar of the sentence
displayed with the result tree.
ms-translate => $api_key
Add Microsoft Bing Translator service to the Toolbar of the sentence
displayed with the result tree. The argument must be a valid API key
issued from Microsoft for the host that runs this HTTP service.
method-prefix => $path_prefix
Optional path to be used as a prefix to all method parts in the URLs.
It is not recommended to use this parameter. If you must, make sure
you add a trailing /. If set to foo/, the path part of the URL for
the web service method 'query' (for example), will have the form of
'foo/query'. The corresponding web application path will be
'app/foo/query'.
debug => $bool
If true, the service logs some extra debugging information into the
error log (STDERR).
FUNCTIONS
auth($unused,$user)
This helper function is designed for use with the RegisterAuth method
of Net::HTTPServer. It retrieves password for a given user from the
<auth-file> and returns ("401","") if user not found or not
authorized to access this service instance (server ID), and
("200",$unencrypted_password) otherwise.
app($resp_sub, $cgi)
This function is intended as a wrapper for the requests handlers when
called from the "WEB APPLICATION". It calls $resp_sub if valid
authorized username and session-id were passed in the s and u
parameters of the request, otherwise redirects the client to the URL
of the login request.
Requests handled by this function accept the following additional
parameters:
s - sessionID
u - username
resp_login($cgi)
This method implements response to the
<app_prefix>/<method_prefix>login request. The request is assumed to
be be protected by a HTTP authorization and should only be used in
connection with the WEB APPLICATION.
It checks that a valid session file exists for the user exists in the
pid_dir and creates a new one (pruning all invalid or expired session
files for the user). Then it redirects the user to the "form"" in "
method (providing a user name and session-id in the u and s
arguments).
Note: this function does not implement authorization or
authentication. It just creates a session for any user to which the
HTTP server granted access to the login request; the HTTP server is
responsible for granting access to authenticated users only and
session validity checking mechanisms used by the app() function
implementing the WEB APPLICATION are responsible for particular
instance authorization based on the <auth-file> data.
resp_root($cgi)
This function is used to implement a request to the base URL (/). It
redirects to <app-prefix>/form if a valid username and session-id is
passed in the s and u URL parameters, otherwise redirects to
<app-prefix>/login.
resp_<method>($cgi)
This family of functions implements individual types of WEB SERVICE
requests described below. For the WEB APPLICATION, they should be
called through the app() function documented above.
WEB APPLICATION API
The web application API is the same as that for the web service,
described below, except that
s - sessionID
u - username
WEB SERVICE API
All methods of the web service accept both GET and POST requests; in
the latter case, parameters can be passed both as URL parameters or as
data. In both cases, the parameters must be encoded using th
application/x-www-form-urlencoded format.
NOTE: we write method names as /METHOD, omitting any <method_prefix>
specified in the configuration and adding a leading slash (to indicate
that we are describing the REST web service API rather than Perl API).
However, if a request method A returns (possibly embedded in some HTML
code) an URL to a method B on this instance, the returned URL has the
form of a relative ( B ) rather than absolute URL ( /B ), so if the
original method was invoked e.g. as http://foo.bar:8082/app/A, the
browser will reslove the returned URL to http://foo.bar:8082/app/B.
/about
Parameters:
format - html|json|text
extended - 0|1
Returns information about this instance:
id - ID
service - base URL (hostname)
title - full name
abstract - short description
moreinfo - a web URL with more information about the treebank database
featured - popularity index
/other
Parameters:
format - html|json|text
Returns information about other known PML-TQ services (sharing the
same <pid-dir> and <auth-file>, but typically running on different
ports or using different app or method prefixes):
id - ID
service - base URL (hostname)
port - port
title - full name
abstract - short description
moreinfo - a web URL with more information about the treebank database
access - true if the user is authorized to use the instance
featured - popularity index
/past_queries
Parameters:
format - html|json|text
cb - a string (typically JavaScript function name)
first - first query to return
max - max number of queries to return
Returns a list of users past queries. If format='json', the result is
an array of arrays (pairs), each of which consists of the time they
were last run (in seconds since UNIX epoch) and the query. If cb is
passed, the JSON array is wrapped into a Javacript function whose
name was passed in cb.
If format='text' the queries are returned as plain text, separated
only by two empty lines.
The options first and max can be used to obtain only partial lists.
For format='html', max defaults to 50.
/form
Parameters: none
Returns HTML with an empty PML-TQ query form, introduction and a few
query examples generated for the actual treebank.
/query
Parameters:
format - html|text
query - string query in the PML-TQ syntax
limit - maximum number of results to return for node queries
row_limit - maximum number of results for filter queries
timeout - timeout in seconds
query_submit - name of the submit button (if contains the substring 'w/o',
the query is evaluated ignoring output filters, if any)
For queries returning nodes the output contains for each match a
tuple of so called node handles of the matching nodes is returned.
The tuple is ordered in the depth-first order of nesting of node
selectors in the query. The handles can be passed to methods such as
/node and /svg.
If format=text, the output consists of zero or more lines, each line
consisting of TAB-separated columns. For queries with output filter,
the columns are the values computed by the last filter, for queries
returning nodes they are the node handles (so each line encodes the
tuple of node handles as described above). In this case, the header
'Pmltq-returns-nodes' indicates whether the query returned nodes
(value 1) or output filter results (value 0).
If format=html, the output is a web application page showing the
query and the results. The web page depends on CSS styleheets and
JavaScript code from the /static folder (i.e. it generates /static
callbacks to this service). Most of the web-page functionality is
implemented in the JavaScript file static/js/results.js. Tree results
are encoded as node indexes in a JavaScript variable of the output
web page and the browser performs callback /svg requests to this
service in order to obtain a SVG rendering of the mathing tree.
[Node handles: For ordinary nodes, the handle has the form X/T or
X/T@I where X is an integer (internal database index of the
corresponding record), T is the name of the PML type of the node and
the optional I value is the PML ID of the matched node (if
available). For member objects (matching the member relation) the
handle has the form X//T.]
/query_svg
Parameters:
query - string query in the PML-TQ syntax
Returns an SVG document with the mime-type image/svg+xml rendering a
graphical representation of the input PML-TQ query.
/svg
Parameters:
nodes - a node handle (or a |-separated list of node handles)
tree_no - tree number
Returns an SVG document with the mime-type image/svg+xml rendering a
tree.
If tree_no is less or equal 0 or not specified, the rendered tree is
the tree containing the node corresponding to the given node handle.
If tree_no is a positive integer N, the returned SVG is a rendering
of Nth tree in the document containing the node corresponding to the
given node handle.
Currently, if nodes contains a |-separated list of node handles, only
the first handle in the list is used.
/n2q
Parameters:
format - json|text
ids - a |-separated list of PML node IDs
cb - a string (typically JavaScript function name)
vars - comma separated list of reserved selector names
Locates given nodes by their IDs in the database and suggests a
PML-TQ query that cover this set of nodes as one of its matches (the
query restricts the nodes based on most of their attributes and their
mutual relationships). The returned query is formatted and indented
so that there is e.g. at most one attribute test per line, tests for
technical attributes (such as ID or order) are commented out, etc.
The query also does not use any variable listed in the vars list.
The output for the text format is simply the query. For the json
format it is either a JavaScript string literal with the
'text/x-json' mime-type, or, if the cb parameter was set, the output
has the 'text/javascript' mime-type and consists of the string
literal wrapped into a function call to the function whose name was
passed in cb. For example, if the resulting query was 'a-node $a:=
[]' and 'show' was passed in cb, the the JavaScript code show('a-node
$a:= []').
/data/<path>
Parameters: none
Verifies that <path> is a (relative) path of a PML document in the
database (or related, e.g. a PML schema) and if so, returns the
document indicating 'application/octet-stream' as mime-type.
/static/<path>
Parameters: none
Returns the content of <static-dir>/<path> guessing the mime-type
based on the file extension, where <static-dir> is a pre-configured
directory for static content.
/node
Parameters:
idx - a node handle
format - html|text
Resolves a given node handle (see "query"" in ") into a relative URL
which points to the /data/<path> method and can be used to retrieve
the document containing a given node. Usually, a fragment identifier
is appended to the URL consisting either of the ID of the node or has
the form N.M where N is the tree number and M is the depth-first
order of the node in the tree.
/schema
Parameters:
name - name of the annotation layer (root element)
Returns a PML schema for the particular annotation layer. The schema
(layer) is identified by the root name.
/type
Parameters:
type - PML type name
format - html|text
Returns a PML schema of the annotation layer which declares nodes of
a given type.
/nodetypes
Parameters:
format - html|text
layer - name of the annotation layer (root element)
Returns a list of node types available the given annotation layer or
on all layers if layer is not given. In 'text' format the types are
returned one per line.
/relations
Parameters:
format - html|text
type - node type
category - implementation|pmlrf|both
Returns a list of specific (i.e. implementation-defined or
PMLREF-based or both) PML-TQ relations that can start at a node of
the given type (or any node if type not given).
/relation_target_types
Parameters:
format - html|text
type - node type
category - implementation|pmlrf|both
Returns target-node types for specific (implementation-defined or
PMLREF-based or both) PML-TQ relations that can start at a node of
the given type (or any node if type is not given).
The output for format='text' is one or more line, each consisting of
a TAB-separated triplet ST, REL, TT where ST is the source node type
(same as type if specified), REL is the name of the PML-TQ relation,
and TT is a possible PML node type of a target node that can be in
the relation R with nodes of type ST.
/version
Parameters:
format - html|text
client_version - version string
Checks compatibility of this version to the client version.
For format=text, returns the string COMPATIBLE (in cases that
compatible client version string was passed) or INCOMPATIBLE
(otherwise) and on the next line the version of the underlying
PMLTQ::SQLEvaluator.
For format=html, returns the same information in a small HTML
document.