4.2. Framework Components Manual

4.2. Framework Components Manual
Prev	Chapter 4. Software Reference	Next

The following sections provide a detailed technical description or reference manual of all the components in the QALL-ME Framework. This will encompass a description of web service (WS) interfaces and decisions with regard to the implementation of the framework architecture. If you are seeking for conceptual information, i.e., information on the framework architecture itself, then you should read section 2.3: “System Architecture” instead. If you are looking for information on particular WS demo implementations – which are not part of the core framework –, then section 4.4: “Demo Components Description” might be the place to go.

In addition to this manual you can find the machine readable WSDL interface descriptions for all WSs of the QALL-ME Framework in the source tree of the project. If you are still in doubt about a certain interface issue after studying this manual, then these WSDL documents should provide the ultimate reference. Each WS description is available as a commented WSDL file under src/main/net/sf/qallme/res/wsdl/. See section 4.1 for information on where to get the framework sources.

4.2.1. General Remarks

This section contains general remarks which are largely valid for all WS components that are described in the following sections. Exceptions to these remarks are noted in the respective component descriptions.

Notification of Problems

All web methods of all WSs in the QALL-ME Framework can throw an InternalServiceFault. Such an error is thrown if the normal functioning of the web service failed in a way which is usually not considered to be recoverable by the caller. A reason for this error may be that some required resource is not available; the caller usually has no means to resolve such a problem. On the other hand, if the problematic resource has been introduced by the caller, then an InternalServiceFault might not be the best fault to throw; in this case the web method which has detected the problem shall rather issue an IllegalArgumentFault (if possible).

Whereever a web method in the QALL-ME Framework gets arguments that somehow could be problematic for the further successful execution of the web method, we have foreseen IllegalArgumentFaults. An IllegalArgumentFault should be thrown when a provided argument is invalid in the current context but the successful execution of the web method could be assured, if the caller would provide a valid argument instead.

Annotations

All question annotations in the QALL-ME Framework are made using <annotation> tags within <AnnotatedSentence> elements. Annotated text of a single annotation is always contiguous; multiple annotations can not overlap. A sample annotation might look like this:

<AnnotatedSentence xmlns="http://qallme.sf.net/xsd/qallmeshared.xsd"
	>Wo kann ich <annotation canonicalForm="&lt;TIMEX2 VAL=&quot;2007-03-18&quot;>heute&lt;/TIMEX2>" type="TIMEX2"
	>heute</annotation> in <annotation type="DESTINATION"
	>Schmelz</annotation> den Film <annotation canonicalForm="Saw III" type="MOVIE"
	>Saw 3</annotation> sehen?</AnnotatedSentence>

As can be seen from the example, an <annotation> element always spans the piece of text which is annotated. There is always a type attribute which specifies the type of the annotation, such as the type of an annotated entity or the type of an annotated term. The optional canonicalForm attribute specifies a canonical form for the annotated text fragment, e.g., the canonical form of an annotated entity in the answer database. This is especially useful for term annotations and temporal expression annotations where the annotated text must be normalized to a language independent form. If the attribute is missing, then the annotated text itself is considered to be the canonical form.

Temporal anchoring of questions (cf. section 2.1.4) in the current implementation of the QALL-ME Framework is done using “extended” TIMEX2 annotations. These annotations are standard TIMEX2 annotations with the a single extension for the annotation of time ranges. A time range is always considered to have a start time point and an end time point. Those two points are two separate TIMEX2 annotations. The extension to the TIMEX2 standard is now a new attribute function which must be used on <TIMEX2> elements of time ranges – and only on these. There must be one function attribute with value “FROM” and one with value “TO” denoting the start and end time points of the time range respectively.

In <AnnotatedSentence> elements TIMEX2 <annotation> tags always have the type “TIMEX2”. The canonicalForm attribute contains the actual TIMEX2 annotation in the form of plain XML (cf. example above).

Miscellaneous

Setter methods, i.e., web methods that only set some property of a WS in the QALL-ME Framework, usually return a dummy value only. These dummy values can always safely be ignored.