W3C

XUP - Extensible User Interface Protocol

W3C Note 28 May 2002

This version:
http://www.w3.org/TR/2002/NOTE-xup-20020528/
Latest version:
http://www.w3.org/TR/xup/
Previous version:
None
Editors:
Jin Yu, MartSoft Corporation, jyu@martsoft.com
Jun Chen, MartSoft Corporation, jun_chen@martsoft.com

Abstract

The Extensible User Interface Protocol (XUP) is a SOAP-based protocol for communicating user interface events and updates on the web. It paves a foundation for developing and consuming highly interactive web applications and services. XUP may be used with any user interface model or any event model with an XML-based representation.

Status of this document

This document is a Note that is the result of an acknowledged Member Submission, made available by the W3C for discussion only. Please read the Submission request and W3C Staff Comment on this request. Publication of this Note by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by the Note. The list of acknowledged W3C Submissions is available at the W3C Web site.

Feedback and comments are welcome and may be sent to xup@martsoft.com.

Table of contents

1 Introduction
    1.1 Terminology
    1.2 Documentation Convention
2 User Interface Model
3 Protocol Overview
4 Network Event Delivery
    4.1 Introduction
    4.2 Event Models
    4.3 Event Dispatch
5 Transport Layer
    5.1 Introduction
    5.2 Relationship to SOAP
    5.3 Relationship to HTTP
6 Startup
    6.1 Introduction
    6.2 XUP Request
        6.2.1 userAgent
        6.2.2 uiModelNamespace
    6.3 XUP Response
        6.3.1 server
        6.3.2 sessionID
7 Normal Operation
    7.1 Introduction
    7.2 XUP Request
        7.2.1 sessionID
        7.2.2 event
        7.2.3 detail
        7.2.4 uiElement
        7.2.5 uiAttr
        7.2.6 XUP Request Example
    7.3 XUP Response
        7.3.1 uiModel
        7.3.2 addUIElement
        7.3.3 updateUIElement
        7.3.4 updateUIAttr
        7.3.5 removeUIElement
        7.3.6 updateListeners
        7.3.7 add
        7.3.8 listener
        7.3.9 uiRef
        7.3.10 remove
        7.3.11 stopPropagation
        7.3.12 XUP Response Example
8 Error Handling
    8.1 Introduction
    8.2 Request Processing Errors
        8.2.1 xup:UIErrors
            8.2.1.1 unsupportedEvent
            8.2.1.2 eventHandlerNotFound
            8.2.1.3 unknownRefs
            8.2.1.4 elementRef
            8.2.1.5 listenerRef
            8.2.1.6 attrRef
            8.2.1.7 unsupportedUI
            8.2.1.8 illegalUIValues
            8.2.1.9 illegalUIStructure
        8.2.2 Request Processing Error Example
    8.3 Response Processing Errors
9 Implementation Considerations

Appendices

A XML Schema Reference
B References
    B.1 Normative References
    B.2 Informative References


1 Introduction

The Extensible User Interface Protocol (XUP) is an XML-based protocol for communicating events and user interface changes on the web. Its goal is to provide a framework for developing and using highly interactive web applications.

XUP provides a model that bridges between the traditional desktop based and web page based user interface paradigms. With XUP, events are delivered from user agent to server as SOAP [SOAP12] messages. Programmers implement event handlers on the server side. They no longer need to process form data as URL-encoded strings. User interface changes are delivered from server to user agent as incremental updates, so end users will no longer experience slow page refreshes, and network bandwidth is conserved. 

The traditional desktop-based model offers rich and powerful user interface controls, but it requires client-side software administration. The web page based model has no client software administration cost, as it has a universal client--the web browser, but it lacks sophisticated user interface controls required by highly interactive web applications. XUP provides a foundation for a user interface programming model that combines the advantages of both the desktop and web page based models. XUP offers the benefit of zero client administration cost as well as better, richer, and more powerful user interactivities. The XUP based model complements, rather than replaces, the traditional desktop or web page based models. The desktop model is more appropriate for graphics-intensive applications, such as movie players and video games, and the web page based model is more suitable for information browsing, such as browsing news web sites.

XUP does not dictate a specific user interface model. It only assumes an XML-based user interface representation. Examples of such models include XUL [XUL], XHTML [XHTML10], and WML [WML20]. XUP may be used with any event model (e.g. delegation [DELEGATION], capturing/bubbling [DOM2EVENTS]) with any type of events.

1.1 Terminology

The key words may, must, and should in this document are to be interpreted as described in RFC 2119 [RFC2119].

An implementation is not compliant if it fails to satisfy one or more of the must level requirements for the protocols it implements. An implementation that satisfies all the must level and all the should level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the must level requirements but not all the should level requirements for its protocols is said to be "conditionally compliant."

This specification uses a number of terms to refer to the roles played by participants in, and objects of, the XUP communication.

user agent - a program which sends requests and processes responses on behalf of the end user.
server - a program that accepts connections in order to service requests by sending back responses.
application
- a program that resides in the server and provides desired functionalities to the end user through the user agent.
UI model - a representation of the user interface which the end user perceives and interacts with. The user agent keeps an instance of UI model for each application which the end user interacts with.
event model - a representation of events triggered by user interactions with the UI model. The event model defines how events are fired, what types of events are fired, and from which UI elements the events are fired in the UI model. The event model is often part of the UI model.

1.2 Documentation Convention

Throughout this document, the following namespace prefixes and corresponding namespace identifiers are used:

xup - the XUP namespace (http://www.w3.org/2002/03/xup)
xul - the XML User Interface Language (XUL) namespace (http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul)
xsd
- the XML schema [XMLSCHEMA1] namespace (http://www.w3.org/2001/XMLSchema)
env - the SOAP envelope namespace (http://www.w3.org/2001/12/soap-envelope)
ev - a fictional event namespace (http://example_event.org).

This is only a convention. Any namespace prefix may be used in practice.

The following typographical conventions are used to present technical material in this document.

The XML representation of various elements within XUP are presented as follows: Listed are the element name, names of all attributes, allowed values of attributes appearing after a "=" character, default values of attributes after a ":" character, and allowed content. One or more headings below the listing provide additional explanatory information. The following block illustrates an example of XML representation for the userAgent element.

XML Representation: <userAgent>
<userAgent
  name = xsd:string
  version = xsd:string
>
  <!-- Content: (##empty) -->
</userAgent>

name - user agent name.
version - user agent version number.

References to external documents appear as follows: [REF1] with links to the references section of this document.

2 User Interface Model

XUP is a protocol for delivering events and user interface updates. It is independent of the actual UI or event model. It places no restriction on the UI component set, or the attributes or events associated with each component. Furthermore, it supports both delegation and capturing/bubbling event models.

XUP can work with any UI models with XML-based representations. A UI model is described by a tree of XML elements, with UI components (e.g. panels, buttons) mapping to elements and the properties (e.g. color, size) of the components mapping to attributes. Throughout this document, we will use the terms UI element and UI attribute to refer to UI components and their properties.

Examples of XML-based UI models include XUL, Proto [PROTO], XHTML, and WML. This specification uses XUL in most examples, as XUL has a rich set of UI components. But the same examples can be replicated in the other UI models as well.

3 Protocol Overview

This section provides an overview of the various elements of XUP and the interactions among them.

An XUP user agent communicates with an XUP server by sending events encapsulated in XUP requests. The server then handles the events and returns UI and listener updates in XUP responses.

An end user interacts with an XUP application by operating a user agent which sends events to the XUP server hosting the XUP application. XUP applications are developed by programmers to provide desired application functionalities for end users. An XUP server may host one or more XUP applications which may be running concurrently. Similarly, an end user may use a user agent to interact with more than one application from one or more servers at the same time.

Each XUP application is identified by a URL. The format of the URL is server implementation specific. For example, query strings can be used to identify different XUP applications within a server. The following diagram illustrates XUP message exchanges between a user agent and a server. The user agent starts an application by sending a request to the URL identifying the application. This request includes user agent software information and a list of UI model namespaces supported by the user agent. The server then responds by sending a session ID used for identifying the user agent in subsequent request, the initial UI model, and an initial list of event listeners. The server side maintains a user session for each user agent, identified by a session ID. This document does not specify how the server or the application should maintain user sessions, nor the contents of user sessions. The initial UI model's namespace must be in the list of UI model namespaces supported by the user agent. The user agent interprets this UI model and renders its initial UI accordingly. The event listeners are used by the user agent to deliver events to the server in subsequent requests.

XUP exchange between a user agent on the left and a server on the right.
The user agent contains a UI model and a set of event listeners. The server contains multiple applications where each application has a set of event handlers.
The XUP communication between the user agent and the server includes a initial startup message and multiple subsequent messages.
In the startup message, the user agent sends user agent info, supported UI model namespsaces. The server responds with server info, session ID, initial UI models and listeners.
In subsequent messages, the user agent sends event and UI data (due to end-user changes). The server responds with updates to UI model and listeners, or fault.

After the startup phase, the end user interacts with the application by manipulating the UI model, which triggers events to be sent to the server. An event is sent to the server only when it matches with an event listener in the user agent. Together with the event, a list of UI data is also sent. Those UI data are referenced in event listener specifications in server responses. They often reflect changes made by the end user to the UI model, such as text entered in a text box and a check box been unchecked.

Upon receiving an event request from the user agent, the server locates the XUP application by the request URL and calls the event handlers registered by the application for the event. The UI data sent with the event are also available to the event handlers. Note that there is only one event in each request, but multiple event handlers within an application may be invoked to handle that event. Event handlers execute the necessary application logics and generate UI model updates and listener updates to be returned to the user agent. If some errors occurred, a SOAP fault is returned in place of the UI model and listener updates.

The user agent processes response by updating its list of event listeners and rendering UI changes. The UI model changes include both UI element level and attribute level changes, and the UI elements could be simple UI controls or complex UI containers. This approach allows applications to perform both macro and micro UI updates, eliminating end users' visual discomfort with frequent page refreshes as in HTML-based applications.

XUP does not define a specific mechanism for the user agent to terminate the session with an XUP application. The user agent may simply close the transport connection and expect the server or application to purge the user session after some time interval. Alternatively, a particular event on a UI element may be interpreted by the application as a termination notice. For example, a click event on a button labeled "quit" may be used by the application to terminate the user session.

4 Network Event Delivery

4.1 Introduction

In XUP, events are triggered by user interactions on the UI model in the user agent. Once an event is fired, the user agent sends a request encapsulating the full event detail and its associated UI data to the server for further processing.  Server sends back UI changes and listener updates after handling the event.

4.2 Event Models

XUP supports both delegation (e.g. Java Swing) and capturing/bubbling (e.g. DOM) event models. The protocol itself does not specify any event details, such as what types of events may occur on which UI elements, or the syntax and semantics of any particular event.

4.3 Event Dispatch

The user agent maintains a list of event listeners which are updated by server through XUP responses. An event is sent to the server when a listener matches with the event in the following manner:

delegation model

capturing/bubbling model

Together with the event, a list of UI data is sent, as referenced by the event listeners that match the event. Within each event listener specification, there are a list of UI element and attribute references which indicate the UI data to be sent to the server when an event is fired. Typically, the list of references points to the UI elements or attributes changeable by the end user, such as text boxes and check boxes. If multiple event listeners match an event, the user agent must send the event to the server only once, with the UI data referenced by the multiple listeners merged together. The event must not be sent if there are no listeners matching the event. The user agent must send the event without any UI data if the matching listener does not reference any UI data.

After the server receives the event, it calls one or more event handlers registered by the XUP application. The event handlers process the event and perform any necessary computation for the application. For capturing/bubbling event models, the application may also indicate in the response whether to stop the propagation of the event in the user agent. By default, events propagate in the user agent according to their types (e.g. some types of events bubble, others don't) defined in the event model.

Because events are dispatched over the network, to conserve network bandwidth, the user agent should not send certain types of high-frequency events, such as mouse movement and key press.

5 Transport Layer

5.1 Introduction

XUP does not define its own transport mechanism. It relies on SOAP and HTTP to exchange messages between user agent and server.

5.2 Relationship to SOAP

An XUP request is encapsulated in a SOAP envelope. The header blocks of the SOAP envelop form the XUP request header, and the body blocks of the SOAP envelope form the XUP request body. Similarly, an XUP response is also encapsulated in a SOAP envelope. The header blocks of the SOAP envelope form the XUP response header, and the body blocks of the SOAP envelope form the XUP response body. If error occurs when processing a request, an XUP server must generate a SOAP fault and return it in the response body. 

5.3 Relationship to HTTP

To efficiently utilize network resources, an implementation should take advantage of HTTP persistent connection when necessary. As an example, a sequence of capturing/bubbling events caused by a single user action should be communicated via a persistent connection. On the other hand, most infrequent event requests due to end user interactions should be sent in multiple non-persistent connections so that server does not need to keep long persistent connections.

Since XUP supports persistent, non-persistent, and mixed operations, when a user agent interacts with an XUP application, a user session needs be maintained for each user agent in the server. The user session is identified by a session ID which must be carried in the header of every XUP request to identify the user agent.

6 Startup

6.1 Introduction

The following sections provide full details of XUP request and response messages during application startup. Each XUP application is identified by a URL. The details of the URL depends on XUP server implementations. For example, a particular XUP server implementation may use query strings to identify the XUP applications hosted in the server. A user agent interacts with an XUP application by sending requests (as SOAP messages) to the URL identifying the XUP application.

6.2 XUP Request

In the XUP startup request, the SOAP header contains user agent software name and version, and a list of UI models supported by the user agent. The XUP protocol version supported by the user agent is specified as the namespace URI of the first header block in the request.

XML Representation: XUP request header (SOAP header)
<env:Header>
  <!-- Content: userAgent?, uiModelNamespace+ -->
</env:Header>

The request body (SOAP body) is empty.

XML Representation: XUP request body (SOAP body)
<env:Body/>

6.2.1 userAgent

The userAgent element specifies the name and version number of the user agent software.

XML Representation: <userAgent>
<userAgent
  name = xsd:string
  version = xsd:string
>
  <!-- Content: (##empty) -->
</userAgent>

name - the name of user agent.
version - user agent version number.

6.2.2 uiModelNamespace

The uiModelNamespace element specifies a UI model namespace supported by the user agent.  Multiple uiModelNamespace elements are listed in the order of user agent preference in the request header.

XML Representation: <uiModelNamespace>
<uiModelNamespace
  env:mustUnderstand = 1
>
  <!-- Content: xsd:anyURI -->
</uiModelNamespace>

mustUnderstand - this SOAP attribute implies that this header block must be understood and processed by the server.
Content - UI model namespace URI.

6.3 XUP Response

In the XUP startup response, the SOAP header contains server information and an XUP session ID.

XML Representation: XUP response header
<env:Header>
  <!-- Content: server?, sessionID -->
</env:Header>

The response body contains the initial UI model and event listeners. The namespace of the first element under updateUIElement (inside uiModel) specifies the UI model used by the XUP application. The element details are described in section 7 .

XML Representation: XUP response body
<env:Body>
  <!-- Content: uiModel, updateListeners -->
</env:Body>

6.3.1 server

The server element specifies the server software's name and version.

XML Representation: <server>
<server
  name = xsd:string
  version = xsd:string
>
  <!-- Content: (##empty) -->
</server>

name - the name of server software.
version - server version number.

6.3.2 sessionID

The sessionID element specifies the session ID to be carried by the user agent throughout future communication.

XML Representation: <sessionID>
<sessionID>
  <!-- Content: xsd:string -->
</sessionID>

Content - session ID value.

7 Normal Operation

7.1 Introduction

The following sections provide full details of XUP request and response messages during normal operations. Normal operations cover all messages after the startup messages described in the previous section.

7.2 XUP Request

During normal operations, an XUP request encapsulates an event and its associated user interface data.

The request header contains the session ID identifying the current session.

XML Representation: XUP request header (SOAP header)
<env:Header>
  <!-- Content: sessionID -->
</env:Header>

The request body contains a single event element.

XML Representation: XUP request body (SOAP body)
<env:Body>
  <!-- Content: event -->
</env:Body>

7.2.1 sessionID

Every request in normal operations must include a session ID as a SOAP header block. The value of the session ID element comes from the startup server response.

7.2.2 event

The event element specifies the event occurred in user agent and UI data to be passed to the server.

XML Representation: <event>
<event
  type = xsd:QName
  element = xsd:IDREF
  source = xsd:IDREF
  phase = (capture | default) : default
>
  <!-- Content: detail?, (uiElement | uiAttr)* -->
</event>

type - event type.
element - event target element ID.
source (optional) - event source element ID.  This attribute must not be used in delegation event models. However, it is required in capturing/bubbling model.
phase (optional) - event occurrence phase. If set to capture, the event is activated during capturing phase. If set to default, or unspecified, the event is activated during bubbling phase or at the source. This attribute must not be used in delegation event models.

7.2.3 detail

The detail element may contain any event data, depending on the event model and event type. For instance, in a mouse click event, event details include which button was pressed and the pointer position. This document does not specify the syntax or the semantics of the detail element.

XML Representation: <detail>
<detail
  (any attribute)
>
  <!-- Content: (##other) -->
</detail>

7.2.4 uiElement

The uiElement contains a single-rooted element in the UI model.

XML Representation: <uiElement>
<uiElement
  element = xsd:IDREF
>
  <!-- Content: (any single-rooted UI element) -->
</uiElement>

element - UI element ID. It overrides the ID of the top-level element in the content.

7.2.5 uiAttr

The uiAttr element specifies the value of one UI element attribute.

XML Representation: <uiAttr>
<uiAttr
  element = xsd:IDREF
  attr = xsd:QName
>
  <!-- Content: xsd:string -->
</uiAttr>

element - UI element name.
attr - the UI element's attribute name. 
Content - UI attribute value.

7.2.6 XUP Request Example

The following example shows an XUP request based on XUL. The session ID of the XUP session is 4124. The user agent sends a mouse clicking event on the "detailBtn" element. The event occurs on button number 0 (the left button), at window position 20 pixels from the left and 40 pixels form the top. In addition to the mouse event, the "outerBox" element and the "selected" attribute of "radioMale" element are sent in the request.

Example: XUP request in a SOAP envelope
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"
              xmlns:xup="http://www.w3.org/2002/03/xup">
  <env:Header>
    <xup:sessionID env:mustUnderstand="1">4124</xup:sessionID>
  </env:Header>
  <env:Body>
    <xup:event type="ev:click" element="detailBtn" xmlns:ev="http://example_event.org">
      <detail>
        <ev:mouseClick button="0" clientX="20" clientY="40"/>
      </detail>
      <uiElement element="outerBox">
        <xul:box id="outerBox"
         xmlns:xul="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
          <textbox id="name" value="Joe Blow"/>
          <textbox id="company" value="ACME Corp."/>
        </xul:box>
      </uiElement>
      <uiAttr element="radioMale" attr="xul:selected">true</uiAttr>
    </xup:event>
  </env:Body>
</env:Envelope>

7.3 XUP Response

An XUP response contains UI updates and event listener updates in response to the user agent's event request.

There is no response header.

The response body contains UI model updates, event listener updates, and whether to stop event propagation in user agent (only in event capturing/bubbling model).

XML Representation: XUP response body (SOAP body)
<env:Body>
  <!-- Content: uiModel?, updateListeners?, stopPropagation? -->
</env:Body>

7.3.1 uiModel

The uiModel element specifies UI updates to the user agent. User agent must execute UI updates according to the lexical order of specification in the uiModel element.

XML Representation: <uiModel>
<uiModel>
  <!-- Content: (addUIElement | updateUIElement | updateUIAttr | removeUIElement)+ -->
</uiModel>

7.3.2 addUIElement

The addUIElement element specifies a UI element to be added to the user agent. Only one element may be specified at a time.

XML Representation: <addUIElement>
<addUIElement
  parent = xsd:IDREF
  before = xsd:IDREF
  after = xsd:IDREF
>
  <!-- Content: (any single-rooted UI element) -->
</addUIElement>

parent (optional) - ID of the parent element under which the new UI element will be added. If the parent has child elements, the new UI element will be appended to the end of the children list.
before (optional) - ID of the element before which the new UI element will be added.
after (optional) - ID of the element after which the new UI element will be added.
The above three attributes are mutually exclusive. One and only one attribute out of the three must be used in a particular instance of the addUIElement element.

7.3.3 updateUIElement

The updateUIElement specifies a UI element to be updated in the user agent. The full UI tree rooted at the specified element is replaced by the new content.

XML Representation: <updateUIElement>
<updateUIElement
  element = xsd:IDREF
>
  <!-- Content: (any single-rooted UI element) -->
</updateUIElement>

element (optional) - ID of the element to update. It overrides ID of the top-level element in the content. If the attribute is not specified, the full UI model will be replaced by the content. During application startup, this attribute must be unspecified to initialize the user agent's UI model.

7.3.4 updateUIAttr

The updateUIAttr specifies a UI attribute to be updated in the user agent.

XML Representation: <updateUIAttr>
<updateUIAttr
  element = xsd:IDREF
  attr = xsd:QName
>
  <!-- Content: xsd:string -->
</updateUIElement>

element - element ID.
attr - attribute name.
Content - new UI attribute value. If the content is empty, the attribute is set to its default value in the UI model.

7.3.5 removeUIElement

The removeUIElement element specifies a UI element to be removed from the user agent.

XML Representation: <removeUIElement>
<removeUIElement
  element = xsd:IDREF
>
  <!-- Content: (##empty) -->
</removeUIElement>

element - ID of the element to be removed.

7.3.6 updateListeners

The updateListeners element specifies updates to event listeners in the user agent. Listener updates consist of both listener additions and listener removals. The user agent must execute the updates according to the lexical order of specification in this element.

XML Representation: <updateListeners>
<updateListeners>
  <!-- Content: (add | remove)+ -->
</updateListeners>

7.3.7 add

The add element specifies addition of a listener.

XML Representation: <add>
<add>
  <!-- Content: listener -->
</add>

7.3.8 listener

The listener element specifies an event listener. It includes the event type and references to selected UI elements and attributes to be sent to the server when the event is triggered.

XML Representation: <listener>
<listener
  id = xsd:ID
  event = xsd:QName
  element = xsd:IDREF
  source = xsd:IDREF
  phase = (capture | default) : default
>
  <!-- Content: uiRef* -->
</listener>

id - listener ID.
event
- event type.
element - event target element ID. In the delegation model, this attribute specifies the event source. In the capturing/bubbling model, the listener is activated when an event is fired from the element specified by this attribute or one of the element's descendants.
source (optional) - event source ID.  If unspecified, then the source could be the target element itself or one of its descendants. This attribute must not be used in delegation event models.
phase (optional) - event occurrence phase. If set to capture, the listener is activated during capturing phase. If set to default, or unspecified, the listener is activated during bubbling or at the source. This attribute must not be used in delegation event models.

7.3.9 uiRef

The uiRef element specifies a list of UI elements or attributes through an XPath [XPATH10] expression. When used inside the listener element, it indicates what UI elements or attributes the user agent should send to the server when the corresponding event is triggered. If a selection is a UI element, the entire UI tree starting at the element is sent to the server in the request.

XML Representation: <uiRef>
<uiRef>
  <!-- Content: XPath expression -->
</uiRef>

Content - UI elements or attributes selection expressed in XPath.

User agent should reevaluate the uiRef XPath expression when sending an event request.

7.3.10 remove

The remove element specifies a listener to be removed from the user agent.

XML Representation: <remove>
<remove
  listener = xsd:IDREF
>
  <!-- Content: (##empty) -->
</remove>

listener - listener ID.

7.3.11 stopPropagation

The stopPropagation element specifies whether the event in the request should stop propagating in the user agent. If unspecified, the event will propagate according to its type (e.g. some types of events bubble, others don't). It is only applicable to event models which support event capturing/bubbling. The element must not be used in delegation event models.

XML Representation: <stopPropagation>
<stopPropagation/>

7.3.12 XUP Response Example

The following example shows an XUP response based on XUL. The response contains the following UI model updates:

In addition, the response contains the addition of listener "shortListener" and the removal of listener "detailListener". Finally, the server stops any further event propagation in the user agent.

Example: XUP response in a SOAP envelope
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"
              xmlns:xup="http://www.w3.org/2002/03/xup">
  <env:Body>
    <xup:uiModel>
      <addUIElement after="name">
        <xul:label xmlns:xul="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
                   id="SSNLabel" value="Social Security Number"/>
      </addUIElement>
      <addUIElement after="SSNLabel">
        <xul:textbox xmlns:xul="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
                     id="SSN" value="123-45-6789"/>
      </addUIElement>
      <removeUIElement element="detailBtn"/>
    </xup:uiModel>
    <xup:updateListeners>
      <add>
        <listener id="shortListener" event="ev:click" element="shortBtn"
          xmlns:ev="http://example_event.org">
          <uiRef>/window/box/textbox/@value</uiRef>
        </listener>
      </add>
      <remove listener="detailListener"/>
    </xup:updateListeners>
    <xup:stopPropagation/>
  </env:Body>
</env:Envelope>

8 Error Handling

8.1 Introduction

This section describes XUP errors. XUP errors may occur on the server side while processing user agent requests or on the user agent side while processing server responses.

8.2 Request Processing Errors

Request processing errors are reported by the server while attempting to understand and process a user agent request. Server sends back errors as SOAP faults in responses.

The following table lists all request processing errors by SOAP fault code and fault detail.

SOAP fault code SOAP fault detail fault description
xup:ApplicationNotFound None The user agent sends the request to the server by pointing to a URL, but the server fails to identify the target XUP application from the URL.
xup:VersionMismatch None User agent's XUP version is not supported by server.
xup:UnsupportedUIModel None None of the UI models specified in the uiModelNamespace elements in the request header is supported by the server.
xup:InternalApplicationError None or empty The XUP application malfunctions or crashes due to some programming error in the application.
xup:UnknownSessionID None Invalid XUP session ID.
xup:UIErrors See section on xup:UIErrors Various UI and event errors.

Note: In the SOAP fault detail column, "none" means the fault detail element does not exist. On the other hand, "empty" means the detail element exists, but its content is empty.

8.2.1 xup:UIErrors

xup:UIErrors may be used to describe various UI and event errors from the request. The SOAP fault detail element contains the details of one or more errors.

XML Representation: <detail>
<detail>
  <!-- Content: unsupportedEvent?, eventHandlerNotFound?, unknownRefs?, 
                unsupportedUI?, illegalUIValues?, illegalUIStructure? -->
</detail>

The detail element contains several subtypes of errors within xup:UIErrors. They are not specified as separate SOAP fault codes because SOAP only allows one fault code in each message, and it is desirable for the server to send multiple related UI and event errors to the user agent in the response.

8.2.1.1 unsupportedEvent

The unsupportedEvent element indicates that the event type in the request is not supported by the server.

XML Representation: <unsupportedEvent>
<unsupportedEvent/>
8.2.1.2 eventHandlerNotFound

The eventHandlerNotFound element indicates that the XUP application does not have an event handler for the event.

XML Representation: <eventHandlerNotFound>
<eventHandlerNotFound/>
8.2.1.3 unknownRefs

The unknownRefs element specifies unknown element, listener, and attribute references in the user agent request.

XML Representation: <unknownRefs>
<unknownRefs>
  <!-- Content: elementRef?, listenerRef?, attrRef* -->
</unknownRefs>
8.2.1.4 elementRef

The elementRef element specifies a list of element references.

XML Representation: <elementRef>
<elementRef
  elements = xsd:IDREFS
>
  <!-- Content: (##empty) -->
</elementRef>

elements - white-space separated list of element ID's.

8.2.1.5 listenerRef

The listenerRef element specifies a list of listener references.

XML Representation: <listenerRef>
<listenerRef
  listeners = xsd:IDREFS
>
  <!-- Content: (##empty) -->
</listenerRef>

listeners - white-space separated list of listener ID's.

8.2.1.6 attrRef

The attrRef element specifies an attribute reference.

XML Representation: <attrRef>
<attrRef
  element = xsd:IDREF
  attr = xsd:QName
>
  <!-- Content: (##empty) -->
</attrRef>

element - element ID.
attr - attribute name.

8.2.1.7 unsupportedUI

The unsupportedUI element specifies unsupported UI elements and attributes in the request. For instance, a particular server implementation may not support xul:tree, or the "orient" attribute of xul:toolbar.

XML Representation: <unsupportedUI>
<unsupportedUI>
  <!-- Content: elementRef?, attrRef* -->
</unsupportedUI>
8.2.1.8 illegalUIValues

The illegalUIValues element specifies illegal UI element content or attribute values in the request. For instance, a particular server implementation may not support the value "vertical" for the "orient" attribute of xul:toolbar.

XML Representation: <illegalUIValues>
<illegalUIValues>
  <!-- Content: (uiElement | uiAttr)* -->
</illegalUIValues>
8.2.1.9 illegalUIStructure

The illegalUIStructure element references a list of UI elements with illegal structures. The structural problems may be internal to an element enclosed in a uiElement within the request, or the problems may occur when the element is attached to its parent. An example structural problem is an xul:window in the content of a uiElement being attached as a child to an xul:box.

XML Representation: <illegalUIStructure>
<illegalUIStructure
  elements = xsd:IDREFS
>
  <!-- Content: (##empty) -->
</illegalUIStructure>

elements - a list of element ID's, from the "element" attributes of the uiElement elements in the request.

8.2.2 Request Processing Error Example

An example of request processing error is shown below. The error is of type xup:UIErrors, as indicated in the faultcode element. The detail reveals that there are two unknown elements "buttonZ1" and "labelZZ", and an unsupported element "XMLEditor1".

Example: XUP error in a SOAP envelope
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"
              xmlns:xup="http://www.w3.org/2002/03/xup">
  <env:Body>
    <env:Fault>
      <faultcode>xup:UIErrors</faultcode>
      <faultstring>User interface errors</faultstring>
      <detail>
        <xup:unknownRefs>
          <elementRef elements="buttonZ1 labelZZ"/>
        </xup:unknownRefs>
        <xup:unsupportedUI>
          <elementRef elements="XMLEditor1"/>
        </xup:unsupportedUI>
      </detail>
    </env:Fault>
  </env:Body>
</env:Envelope>

8.3 Response Processing Errors

User agent may detect errors when processing server responses. Examples of response processing errors are unsupported event types on listeners, unknown listeners, UI elements, or attribute references, unsupported UI elements or attributes, illegal UI values, and illegal UI structure. Due to transport protocol limitations, these errors cannot be sent back to the server. User agent implementations may prompt end users, silently ignore the errors, or abort.

9 Implementation Considerations

Implementations should take advantage of HTTP headers to signal language and character set preferences.

To save network resources, the user agent should send UI data which have been changed by the end user since their last transmission. Furthermore, the user agent should not send duplicated UI data to server within a request. UI data duplications could occur when one UI element is a descendant of another UI element, both of which are referenced by the event listener. When multiple listeners match an event, duplications could also occur since UI data referenced by those listeners are merged together.

XUP server must be prepared to handle concurrent event requests from one user agent targeted at the same XUP application. User agent must be able to issue concurrent event requests targeted at one XUP application in order to support end user multi-tasking.

When removing UI elements, server should not issue removal of any event listeners attached to the UI elements in the response. User agent should automatically remove any event listeners when the UI elements to which they are attached are removed.

Server should help applications maintain a UI model for each user session. This allows an application's event handlers to have full access to the UI tree. Furthermore, it enables the server to detect UI errors caused by the XUP application so that the errors are handled by the application locally and not propagated to the user agent.

All UI elements should have unique ID's to accommodate IDREF-based operations such as addUIElement and removeUIElement. If an element's ID is not specified by the XUP application, the server should automatically generate an ID for the element.


A XML Schema Reference

The XML schema specification of XUP can be found here: xup.xsd.

B References

B.1 Normative references

[RFC2119]
"Key words for use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997.
[SOAP12]
"SOAP Version 1.2 Part 1: Messaging Framework", M. Gudgin, M. Hadley, J. Moreau, H. Nielsen, December 2001.
[XML10]
"Extensible Markup Language (XML) 1.0 (Second Edition)", T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, October 2000.
[XMLSCHEMA1]
"XML Schema Part 1: Structures", H. Thompson, D. Beech, M. Maloney, N. Mendelsohn, May 2001.
[XPATH10]
"XML Path Language (XPath) Version 1.0", J. Clark, S. DeRose, November 1999.

B.2 Informative references

[DELEGATION]
"Java(TM) AWT: Delegation Event Model", Sun Microsystems Inc., April 1999.
[DOM2EVENTS]
"Document Object Model (DOM) Level 2 Events Specification", T. Pixley, November 2000.
[PROTO]
"XML Application - Prototype", P. Morel, April 1999.
[WML20]
"Wireless Markup Language Version 2.0", WAP Forum, September 2001.
[XHTML10]
"XHTML 1.0: The Extensible HyperText Markup Language - A Reformulation of HTML 4 in XML 1.0", S. Pemberton, et al., January 2000.
[XUL]
"XUL Programmer's Reference", The Mozilla Organization, April 2001.