Syntax:

invoke-ace-webservice &rest args => result*

Arguments and Values:

• args --- a plist of arguments

• url --- a string or PURI:URI object, default is {defconstant +ape-webservice-url+}

• drakma-arguments --- a plist, defaults to '(:method :post)

• results --- results from drakma:http-request

Description:

Most of the keyword arguments are derived from (and share names) with the APE Webservice [1]. Arguments with on|off values are boolean flags, each generalized booleans. Arguments which accept text or URL/URIs accepts strings. The solo argument should be a string designator, and its value is string-downcased before being passed to the webservice. url is the URL to which the request will be sent. The value of drakma-arguments should be a plist, and will be passed to drakma:http-request. drakma-arguments may contain any arguments that drakma:http-request accepts, but invoke-ape-webservice builds and passes a :parameters argument given before drakma-arguments, so the :parameters argument will be ignored.

The results are returned directly from drakma:http-request [2]. The url for the request is the value of +ape-webservice-url+, the method is :post, and the parameters are constructed based on args. All other arguments assume their default values.

Notes:

The cruleml option is supported by the websevice, and the XML Schema specification for APE output [3] includes a ruleml field. However, the APE Webservice Specification [1] does not actually mention the cruleml option. See the the message Attempto mailing list message "RuleML question" [4] for more information.

The value of drakma-arguments has a default value '(:method :post), since the queries, depending on the options used, can grow to be rather large. Thus, when specifying a drakma-arguments argument, it may be wise to include :method :post.

See Also:

• [1] http://attempto.ifi.uzh.ch/site/docs/ape_webservice.html

• [2] http://www.weitz.de/drakma/#http-request

• [3] http://attempto.ifi.uzh.ch/site/docs/XMLSchema/apews_output.xsd

• [4] {https://lists.ifi.uzh.ch/pipermail/attempto/2009-February/000137.html}

Syntax:

ape &rest args &key signal-ape-warnings signal-ape-errors => result

Arguments and Values:

• args --- arguments to invoke-ape-webservice

• signal-warnings-messages, signal-error-messages --- generalized booleans, defaulting to t and nil, respectively

• result --- an ape-result or ape-error

Description:

Ape invokes the APE-webservice using invoke-ape-webservice (to which args are passed directly), but differs from invoke-ape-webservice in that the resulting ape-result or {defclass ape-webservice:ape-error}is parsed into lisp objects, and appropriate conversions to lisp data structures are performed where possible and supported. When the solo parameter is provided, (even when nil) no parsing or conversion is done, and ape behaves as is the same calling invoke-ape-webservice .

When signal-warning-messages is non-nil (the default), each message whose importance is :warning is signalled using WARN. When signal-error-messages is non-nil, each message whose importance is :error is signalled with ERROR. These flags affect only the messages of an ape-result . Every ape-error produced by the webservice is signalled with ERROR.

The conversions currently supported are as follows:

• All ape-result and error XML outputs are cast into corresponding CLOS classes (and all with the same name as their ACE counterpart, with the single exception of error, which becomes ape-error ).

• The messages slot of the ape-result object is a list of messages.

• Floating point values in duration objects are parsed from XML attribute strings.

• Enumerated string values are recast as keyword symbols, usually with the same name (with appropriate case conversions). The various failure strings, however, have a bit more processing. E.g., "fail fetch acetext" become :fetch-acetext.

• The most significant processing to lisp objects is the parsing of the DRSXML output to the drs objects (whose API is exported from the ACE-DRS package).

Notes:

Note that not all messages with type error indicate that call to the webservice was completely unsuccessful. For instance, the sentence "John believes that Mary likes Bill." is valid ACE, but will cause an error message to be generated if cowlfss is also non-nil, since sentence subordination is not supported in OWL. This is the rationale for signalling warnings, but not errors, by default.