Copyright ©2006 OpenXUP.org. All Rights Reserved.
The Extensible User Interface Protocol (XUP) is a SOAP-based protocol for communicating user interface events and updates on the web. It lays 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.
Feedback and comments are welcome and may be sent to 
.
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 Messages
6.1
Introduction
6.2
XUP Request
6.2.1
clientInfo
6.2.2
uiModelNamespaces
6.2.3 startup
6.3
XUP Response
6.3.1
serverInfo
6.3.2
session
6.3.3 startupResponse
6.4 Example
7
Event Messages
7.1
Introduction
7.2
XUP Request
7.2.1
event
7.2.2
detail
7.2.3
addUIElement
7.2.4
updateUIElement
7.2.5
moveUIElement
7.2.6 removeUIElement
7.2.7 updateUIAttr
7.2.8
addResources
7.2.9
updateResources
7.2.10
removeResources
7.3
XUP Response
7.3.1
eventResponse
7.3.2
eventResult
7.3.3 addEventSelectors
7.3.4
updateEventSelectors
7.3.5
removeEventSelectors
7.3.6 selector
7.3.7 mask
7.3.8 script
7.3.9
startStatusMonitor
7.3.10
updateStatusMonitor
7.3.11
stopStatusMonitor
7.4 Example
8 Status Messages
8.1 Introduction
8.2 XUP Request
8.2.1 status
8.3 XUP Response
8.3.1
statusResponse
9 Shutdown Messages
9.1 Introduction
9.2 XUP Request
9.2.1
shutdown
9.3 XUP Response
10 Error Handling
10.1
Introduction
10.2
Request Processing Errors
10.2.1 xup:UIError
10.2.1.1
unsupportedEvent
10.2.1.2
unsupportedResource
10.2.1.3
unsupportedUI
10.2.1.4
eventError
10.2.1.5
selectorError
10.2.1.6
resourceError
10.2.1.7
elementError
10.2.1.8
attrError
10.2.1.9
illegalUIValue
10.2.2
Request Processing Error Example
10.3
Response Processing Errors
11
Implementation Considerations
A
References
A.1
Normative References
A.2
Informative References
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, and WML. XUP may be used with any event model (e.g. delegation [DELEGATION], capturing/bubbling [DOM2EVENTS]) with any type of events.
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 component model - a representation of the user interface which the end user perceives and interacts with. The user agent keeps an instance of UI component model for each application which the end user interacts with.
UI event model - a representation of events triggered by user interactions with the UI component 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 component model.
UI model - the combination of UI component model and event model.
resource - content used by applications, e.g. images and files. Resources may be referred to externally or embedded within protocol messages.
Throughout this document, the following namespace prefixes and corresponding namespace identifiers are used:
xup - the XUP namespace (http://www.openxup.org/2004/02/xup)
sul - the SUL (Simple User Interface Language) component namespace (http://www.openxup.org/2004/02/sul)
sev -the SUL event namespace (http://www.openxup.org/2004/04/sev)
sres -the SUL resource namespace (http://www.openxup.org/2004/07/sres)
xsd - the XML schema [XMLSCHEMA1] namespace (http://www.w3.org/2001/XMLSchema)
env - the SOAP envelope namespace (http://www.w3.org/2003/05/soap-envelope)
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
serverInfo
element.
<serverInfo><serverInfo
name = xsd:string
version = xsd:string
> <!-- Content: (##empty) --> </serverInfo>
name - server name.
version - server version number.
References to external documents appear as follows: [REF1] with links to the references section of this document.
XUP is a protocol for delivering events and user interface updates. It is independent of the actual UI component 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 component 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 Simple User Interface Language (SUL) in most examples, as SUL has a rich set of UI components. But the same examples can be replicated in the other UI models as well.
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 selector 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.
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 server. This request includes the name of the application 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 selectors. 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 selectors are used by the user agent to deliver events to the server in subsequent requests.
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 selector in the user agent. Together with the event, a list of UI data is also sent. Those UI data 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 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 selector updates to be returned to the user agent. If some errors occurred, a SOAP fault is returned in place of the UI model and selector updates.
The user agent processes event response by updating its list of event selectors 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.
Due to the nature of HTTP/SOAP request/response model, it is not possible for the server to send asynchronous notification to the user agent. This facility would be needed when reporting server-side events and the status of long time server side operations. Therefore, XUP supports optional status messages between the user agent and server. The user agent may send periodic status requests to the server, and the server may send asynchronous notifications (in the form of UI model updates) in status responses. The frequency of the status messages (and whether to use status messages at all) is up to the XUP application.
Finally, XUP defines an optional shutdown message for the user agent to terminate the session with an XUP application. Alternatively, the user agent may simply close the transport connection and expect the server or application to purge the user session after some time interval. In addition, 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.
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 the changed UI data to the server for further processing. Server sends back UI changes and selector updates after handling the event.
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.
The user agent maintains a list of event selectors which are updated by server through XUP responses. An event is sent to the server when a selector matches with the event in the following manner:
delegation model
capturing/bubbling model
Together with the event, a list of changed UI data is also sent to the server. Those UI data reflect changes made by the end user to the UI model. The user agent must send the event without any UI data if the end user did not change the UI model. The event must not be sent if there are no selectors matching the event. If multiple event selectors match an event, the user agent must send the event to the server multiple times, according to the order of the specified selectors.
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 (i.e. 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.
Finally, event delivery may be synchronous or asynchronous. During a synchronous network event delivery, the user agent must prevent the end user from interacting with the UI model until the event response is received and processed. On the other hand, the user agent must not block user interactions during asynchronous event delivery.
XUP does not define its own transport mechanism. It relies on SOAP and HTTP to exchange messages between user agent and server.
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.
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.
The following sections provide full details of XUP request and response messages during application startup. Each XUP server is identified by a URL. The details of the URL depend on the deployment of the XUP server. A user agent interacts with an XUP application by sending requests (as SOAP messages) to the URL identifying the XUP server.
In the XUP startup request, the SOAP header contains user agent software information, 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.
XUP request header (SOAP header)<env:Header>
<!-- Content: clientInfo?, uiModelNamespaces --> </env:Header>
The request body (SOAP body) contains the startup element,
which specifies the name of the XUP application and optional application
specific parameters.
XUP request body (SOAP body)The clientInfo element specifies the information about the user agent software.
<clientInfo><clientInfo
name = xsd:string
version = xsd:string
screenWidth = xsd:nonNegativeInteger screenHeight = xsd:nonNegativeInteger screenDepth = xsd:nonNegativeInteger
> <!-- Content: property* --> </clientInfo>
name - the name of user agent.
version - user agent version number.
screenWidth (optional) - the width of the screen where the user agent is running. If 0 or unspecified, the application cannot make any assumption about the screen width.
screenHeight (optional) - the height of the screen where the user agent is running. If 0 or unspecified, the application cannot make any assumption about the screen height.
screenDepth (optional) - the depth of the screen where the user agent is running. If 0 or unspecified, the application cannot make any assumption about the screen depth.
The property element specifies
implementation specific information about user
agent and server. Property names and values are out of the scope of this
document.
<property><property
name = xsd:string
> <!-- Content: xsd:string --> </property>
name - the name of the property.
Content - the value of the property.
The uiModelNamespaces element specifies a list of URIs
identifying the UI model namespaces supported by the user agent. The URIs
may include component, event, and resource namespaces.
<uiModelNamespaces>mustUnderstand - this SOAP attribute implies that this header block must be understood and processed by the server.
The uri element specifies a UI model
namespace supported by the user agent. Multiple uri elements
for the same type of namespace are listed in the order of user agent preference.
<uri><uri> <!-- Content: xsd:anyURI --> </uri>
Content - UI model namespace URI.
The startup element specifies the name of the XUP application
and optional application specific parameters.
<startup>application - the name of the XUP application. The format of the name is server implementation dependant.
The parameter element allows user
agent to specify application startup parameters. Parameter names and values are
application dependant.
<parameter><parameter
name = xsd:string
> <!-- Content: xsd:string --> </property>
name - the name of the parameter.
Content - the value of the parameter.
In the XUP startup response, the SOAP header contains the server information and a server generated ID to identify user session.
XUP response header<env:Header> <!-- Content: serverInfo?, session --> </env:Header>
The response body contains the startupResponse element, which
includes initial UI model and event selectors.
XUP response body<env:Body> <!-- Content: startupResponse --> </env:Body>
The server element specifies the information about the server
software.
<server>name - the name of server software.
version - server version number.
The session element is used by the server to return a server
generated session ID to the user agent. The user agent will carry this session
information throughout future communication.
<session><session
env:mustUnderstand = 1
application = xsd:string
sid = xsd:string
> <!-- Content: (##empty) --> </session>
mustUnderstand - this SOAP attribute implies that this header block must be understood and processed by the server.
application - the application name.
sid - session ID value.
The startupResponse element contains an XUP application's
initial UI model, selectors, and optionally resources. The child element of
addUIElement specifies the root of the UI model. The details of
the contained elements are described in the next section.
<startupResponse><startupResponse> <!-- Content: startStatusMonitor?,
addResources?,
addUIElement,
addEventSelectors -->
</startupResponse>The following example shows XUP startup messages based on SUL.
The user agent requests for application "testapp1".
<?xml version="1.0" encoding="utf-8" ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <env:Header> <clientInfo name="XUPClient.NET" version="1.0"
screenWidth="0" screenHeight="0" screenDepth="0"
xmlns="http://www.openxup.org/2004/02/xup" /> <uiModelNamespaces env:mustUnderstand="1"
xmlns="http://www.openxup.org/2004/02/xup">
<uri>http://www.openxup.org/2004/02/sul</uri>
<uri>http://www.openxup.org/2004/04/sev</uri>
<uri>http://www.openxup.org/2004/07/sres</uri>
</uiModelNamespaces>
</env:Header>
<env:Body>
<startup application="testapp1"
xmlns="http://www.openxup.org/2004/02/xup" /> </env:Body> </env:Envelope>
The server returns an ID for the XUP session, "X70B5AC95". The response includes a single root UI element "win1", and an event selector for the window closing event on "win1".
<?xml version="1.0" encoding="utf-8" ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <env:Header> <session env:mustUnderstand="1" application="testapp1" sid="X70B5AC95"
xmlns="http://www.openxup.org/2004/02/xup" /> <serverInfo name="XUPSrv.NET" version="1.0"
xmlns="http://www.openxup.org/2004/02/xup" />
</env:Header>
<env:Body>
<startupResponse xmlns="http://www.openxup.org/2004/02/xup">
<addUIElement position="-1">
<window id="win1" title="Close me ..."
position="width:400;height:200;"
xmlns="http://www.openxup.org/2004/02/sul" />
</addUIElement>
<addEventSelectors>
<selector xmlns:sev="http://www.openxup.org/2004/04/sev"
event="sev:window-closing" id="_S2AE7EB21"
element="win1" async="false" updateUI="true" order="0" />
</addEventSelectors>
</startupResponse>
</env:Body> </env:Envelope>
The following sections provide full details of XUP request and response messages for user interface events.
An XUP event request encapsulates an event and its associated user interface data.
The request header contains the application name and session ID identifying the current session. The value of the session ID comes from the startup server response.
XUP request header (SOAP header)<env:Header>
<!-- Content: session --> </env:Header>
The request body contains a single event element.
XUP request body (SOAP body)The event element specifies the event occurred in user agent
and the UI data and resources changed by the end user.
<event><event
type = xsd:QName
selector = xsd:IDREF
> <!-- Content: detail?,
addResources?, updateResources?, removeResources?,
(addUIElement | updateUIElement | moveUIElement | removeUIElement | updateUIAttr)*
--> </event>
type - event type (qualified by the event namespace).
selector - the ID of the matching event selector.
The detail element may contain any attributes and
sub-elements, which can be used to describe further information
about entities in the UI model. The syntax and semantics of the attributes
and sub-elements are not specified in this document.
Within the event element, 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.
<detail><detail
(any attribute)
> <!-- Content: (##other) --> </detail>
The addUIElement element specifies a UI element to be added to the
UI model.
Only one element may be specified at a time.
<addUIElement><addUIElement
parent = xsd:IDREF
position = xsd:integer
> <!-- Content: (any single-rooted UI element) --> </addUIElement>
parent (optional) - ID of the parent element under which the new UI element will be added. If unspecified, the new UI element will be added under the root of the UI model.
position (optional) - the position under the parent to which the new UI element will be added. If unspecified or less than 0, the new UI element will be appended to the end of the parent's children list.
The updateUIElement specifies a UI element to be updated in the
UI model. Note that XUP does not support elements with mixed content (i.e.
elements with both text and child elements). Therefore, updateUIElement
only updates the text content of the UI element.
<updateUIElement><updateUIElement
element = xsd:IDREF
> <!-- Content: xsd:string --> </updateUIElement>
element - ID of the element to update.
Content (optional) - the new text content of the element. If unspecified, the UI element's new content will be empty.
The moveUIElement element specifies a UI element to be
repositioned under its parent.
<moveUIElement><moveUIElement
element = xsd:IDREF
position = xsd:integer
> <!-- Content: (##empty) --> </moveUIElement>
element - ID of the element to be moved.
position - The new position of the UI component.
The removeUIElement element specifies a UI element to be removed from the
UI model.
<removeUIElement><removeUIElement
element = xsd:IDREF
> <!-- Content: (##empty) --> </removeUIElement>
element - ID of the element to be removed.
The updateUIAttr element specifies a UI attribute to be updated in the
UI model.
<updateUIAttr><updateUIAttr
element = xsd:IDREF
attr = xsd:QName
> <!-- Content: xsd:string --> </updateUIElement>
element - element ID.
attr - attribute name (qualified by the UI model namespace).
Content - new UI attribute value. If unspecified, the attribute's new value will be empty.
The addResources element specifies a list of resources to be
added to the UI model. This document does not define the syntax or semantics of
the resources.
<addResources><addResources> <!-- Content: (##other) --> </addResources>
Content - a list of resources (e.g. images and files) to be added to the UI model.
The updateResources element specifies a list of resources to be
updated in the UI model. This document does not define the syntax or semantics
of the resources.
<updateResources><updateResources> <!-- Content: (##other) --> </updateResources>
Content - a list of resources (e.g. images and files) to be updated in the UI model.
The removeResources element specifies the IDs of resources to
be removed from the UI model.
<removeResources><removeResources resources = xsd:IDREFS > <!-- Content: (##empty) -->
</removeResources>
resources - the IDs of resources to be removed from the UI model.
An XUP event response contains UI, event selector, and resource updates in response to the user agent's event request.
There is no response header.
The response body contains a single eventResponse element
which includes UI model updates, event selector
updates, and resource updates.
XUP response body (SOAP body)<env:Body> <!-- Content: eventResponse --> </env:Body>
The eventResponse element specifies UI, event selector, and
resource updates to be returned to the user agent. User agent must execute
UI updates according to the lexical order of specification of the
addUIElement, updateUIElement, moveUIElement, removeUIElement,
and updateUIAttr elements. The eventResult element
returns event result to the user agent; it can be only used in responses
to synchronous event requests.
<eventResponse><eventResponse> <!-- Content: eventResult?,
(startStatusMonitor | updateStatusMonitor | stopStatusMonitor)?,
addResources?, updateResources?, removeResources?,
addEventSelectors?, updateEventSelectors?, removeEventSelectors?, (addUIElement | updateUIElement | moveUIElement | removeUIElement | updateUIAttr)*
--> </eventResponse>
The eventResult element specifies the event result in response
to a synchronous event request. The element must not be used in responses to
asynchronous event requests. The element may include a detail
element, which contains event result specific to the event type.
<eventResult><eventResult
cancelEffect = xsd:boolean : false
stopFiring = xsd:boolean : false
stopPropagation = xsd:boolean : false
> <!-- Content: detail? --> </eventResult>
cancelEffect (optional) - instructing the user agent to cancel the default UI effect or action caused by this event. For example, a window closing event will normally hide a window. However, if cancelEffect is set to true, the window will remain visible; i.e. the action of hiding the window is cancelled.
stopFiring (optional) - instructing the user agent not to send further requests corresponding to the remaining matching synchronous or asynchronous event selectors.
stopPropagation (optional) - whether the event in the request should stop propagating in the user agent. If the value is true, 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 attribute must not be used in delegation event models.
The addEventSelectors element specifies a list of event
selectors to be added to the UI model of the user agent.
<addEventSelectors><addEventSelectors> <!-- Content: selector+ --> </addEventSelectors>
The updateEventSelectors element specifies a list of event
selectors to be updated in the UI model of the user agent.
<updateEventSelectors><updateEventSelectors> <!-- Content: selector+ --> </updateEventSelectors>
The removeEventSelectors element specifies the IDs of selectors to
be removed from the UI model of the user agent.
<removeEventSelectors><removeEventSelectors selectors = xsd:IDREFS > <!-- Content: (##empty) -->
</removeEventSelectors>
selectors - the IDs of selectors to be removed from the UI model.
The selector element specifies an event selector. The optional
mask child element specifies the conditions that must be met for the user
agent to send the event. The selector element may also include
a script element which contains scripts to be executed in the user agent when a
UI event is fired. Note that the user agent must execute the scripts before
sending the event to server.
<selector><selector
id = xsd:ID
event = xsd:QName
element = xsd:IDREF
source = xsd:IDREF
phase = (capture | default) : default
updateUI = xsd:boolean : true
async = xsd:boolean : false
order = xsd:double : 0.0
> <!-- Content: mask?, script? --> </selector>
id - selector ID.
event - event type (qualified by the event namespace).
element - event target element ID. In the delegation model, this attribute specifies the event source. In the capturing/bubbling model, the selector 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 element 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 selector is activated during capturing phase. If set to default, or unspecified, the selector is activated during bubbling or at the source. This attribute must not be used in delegation event models.
updateUI (optional) - whether user agent should send UI updates to server in the event request.
async (optional) - whether user agent should asynchronously send the matching event to server.
order (optional) - a non-negative number specifying the order of the selector. When multiple selectors match a UI event, user agent must send the event to server multiple times, in an ascending order according to the specified order values of the matching selectors. A selector having the order value 0.0 is the first selector. If two or more selectors matching a UI event have the same order value, the behavior is implementation dependant.
The mask element specifies the conditions (event mask) that
must be met for the user agent to send the event specified by the event
selector. For instance, in a mouse click event, the event mask might indicate
that the shift key must be held down for the mouse event to be sent to the
server. This further reduces network event traffic.
The mask element may contain any event mask data, depending on the event model and event type. This document does not specify the syntax or the semantics of the
mask element.
<mask><mask
(any attribute)
> <!-- Content: (##other) --> </mask>
The script element specifies scripts to be executed in the user
agent when a UI event is fired. User agent must execute the scripts before
sending the event to server.
<script><script
language = xsd:string
> <!-- Content: xsd:string | (CDATA section) | (XML comment) --> </script>
language - the scripting language. For example, JavaScript and VBScript.
Content - scripts to be executed in the user agent. The script text may be a string with XML markups escaped, or it may be contained in a CDATA section or XML comment.
The startStatusMonitor element informs the user agent to start
sending periodic status requests.
<startStatusMonitor><startStatusMonitor
interval = xsd:double
updateUI = xsd:boolean : false
> <!-- Content: (##empty) --> </startStatusMonitor>
interval (optional) - the frequency of status requests in seconds. If unspecified, the default is implementation specific. Sub-second values may be specified.
updateUI (optional) - whether user agent should send UI updates to server in status requests.
The updateStatusMonitor element informs the user agent to
change the way status requests are sent.
<updateStatusMonitor><updateStatusMonitor
interval = xsd:double
updateUI = xsd:boolean : false
> <!-- Content: (##empty) --> </updateStatusMonitor>
interval (optional) - the frequency of status requests in seconds. If unspecified, the default is implementation specific. Sub-second values may be specified.
updateUI (optional) - whether user agent should send UI updates to server in status requests.
The stopStatusMonitor element informs the user agent to stop
sending periodic status requests.
<stopStatusMonitor><stopStatusMonitor> <!-- Content: (##empty) --> </stopStatusMonitor>
The following example shows XUP event messages based on SUL.
The end user is trying to close the window "win1" and the user agent sends a window closing event to the application "testapp1". Note that the event matches the selector "_S2AE7EB21", which comes from the startup response example.
<?xml version="1.0" encoding="utf-8" ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <env:Header> <session env:mustUnderstand="1" application="testapp1" sid="X70B5AC95"
xmlns="http://www.openxup.org/2004/02/xup" /> </env:Header> <env:Body> <event xmlns:sev="http://www.openxup.org/2004/04/sev"
type="sev:window-closing" selector="_S2AE7EB21"
xmlns="http://www.openxup.org/2004/02/xup" />
</env:Body> </env:Envelope>
In the response, the application instructs the user agent to cancel the effect of the window closing event (i.e. "win1" will not be closed). In addition, a message prompt ("_E42EE10B3") is added to the UI model which will display the message "Are you sure?" to the end user. There is also an event selector ("_S61C70A29") for the message prompt. The selector will cause the user agent to send an event to the server when the end user closes the prompt by pressing the OK or Cancel button.
<?xml version="1.0" encoding="utf-8" ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <env:Body> <eventResponse xmlns="http://www.openxup.org/2004/02/xup"> <eventResult cancelEffect="true" stopFiring="false" /> <addEventSelectors> <selector xmlns:sev="http://www.openxup.org/2004/04/sev"
event="sev:dialog-closed" id="_S61C70A29"
element="_E42EE10B3" async="false" updateUI="true" order="0" />
</addEventSelectors>
<addUIElement parent="win1">
<msg-prompt xmlns="http://www.openxup.org/2004/02/sul" id="_E42EE10B3"
button-set="ok-cancel">Are you sure?</msg-prompt>
</addUIElement>
</eventResponse>
</env:Body>
</env:Envelope>
The end user clicks on the OK button of the message prompt and the user
agent sends a dialog closed event to the application "testapp1". In addition,
the message prompt becomes hidden: the updateUIAttr element sets
the
sul:visible attribute of the message prompt to false.
<?xml version="1.0" encoding="utf-8" ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <env:Header> <session env:mustUnderstand="1" application="testapp1" sid="X70B5AC95"
xmlns="http://www.openxup.org/2004/02/xup" /> </env:Header> <env:Body> <event xmlns:sev="http://www.openxup.org/2004/04/sev"
type="sev:dialog-closed" selector="_S61C70A29"
xmlns="http://www.openxup.org/2004/02/xup">
<detail sev:button="ok"
xmlns:sev="http://www.openxup.org/2004/04/sev" />
<updateUIAttr element="_E42EE10B3"
xmlns:sul="http://www.openxup.org/2004/02/sul"
attr="sul:visible">False</updateUIAttr> </event>
</env:Body> </env:Envelope>
In the response, the application instructs the user agent to remove the root of the UI model, "win1". This essentially informs the user agent to shutdown the session to this application.
<?xml version="1.0" encoding="utf-8" ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <env:Body> <eventResponse xmlns="http://www.openxup.org/2004/02/xup"> <removeUIElement element="win1" /> </eventResponse> </env:Body> </env:Envelope>
The following sections provide full details of XUP status request and status response messages.
The user agent may send periodic status requests to the server, and the server
may send asynchronous notifications (in the form of UI model updates) in status
responses. The frequency of the status messages is controlled the XUP
application via the startStatusMonitor, updateStatusMonitor,
and stopStatusMonitor elements.
The request header contains the application name and session ID identifying the current session. The value of the session ID comes from the startup server response.
XUP request header (SOAP header)<env:Header>
<!-- Content: session --> </env:Header>
The request body contains a single status element.
XUP request body (SOAP body)The status element may include UI updates, depending on the
specifications from the startStatusMonitor and updateStatusMonitor
elements in previous responses.
<status><status> <!-- Content: (addUIElement | updateUIElement | moveUIElement | removeUIElement
| updateUIAttr)* --> </status>
An XUP status response contains server-side asynchronous notifications in the form of UI model updates.
There is no response header.
The response body contains a single statusResponse element
which includes UI model and event selector updates.
XUP response body (SOAP body)<env:Body> <!-- Content: statusResponse --> </env:Body>
The statusResponse element contains server-side asynchronous
notifications in the form of UI model updates. In addition, an XUP application
may inform the user agent to stop sending status requests or change the way
status requests are sent.
<statusResponse><statusResponse> <!-- Content: (updateStatusMonitor | stopStatusMonitor)?,
addEventSelectors?, updateEventSelectors?, removeEventSelectors?, (addUIElement | updateUIElement | moveUIElement | removeUIElement | updateUIAttr)*
--> </statusResponse>
The XUP shutdown request is used by the user agent to terminate the session with an XUP application. The shutdown messages are optional, since 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.
The request header contains the application name and session ID identifying the current session. The value of the session ID comes from the startup server response.
XUP request header (SOAP header)<env:Header>
<!-- Content: session --> </env:Header>
The request body contains a single shutdown element.
XUP request body (SOAP body)The shutdown element is an empty element used by the user agent
to terminate the session with an XUP application.
<shutdown><shutdown> <!-- Content: (##empty) --> </shutdown>
The XUP shutdown response is empty.
There is no response header. The response body is empty.
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.
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:VersionMismatch | None | User agent's XUP version is not supported by server. |
| xup:ApplicationNotFound | None or empty | The user agent sends the request to the server, but the server fails to identify the target XUP application specified in the request. |
| xup:UnsupportedUIModel | None or empty | During the startup request, none of the UI models specified in the uiModelNamespaces elements in the request header is supported by the server or the application; during an event request, an UI model namespace (component, event, or resource) specified by the client is not supported by the server or the application. |
| xup:UnknownSessionID | None | The user agent sends an invalid XUP session ID in the request. |
| xup:ClientIPChanged | Empty | The user agent's IP address appears to be different from the previous request. This usually indicates a security problem. |
| xup:ConfigError | Empty | The server malfunctions due to configuration errors. |
| xup:ExtError | Empty | Errors occurred in external component, event, or resource code. |
| xup:UIError | See section on xup:UIError | Various UI and event errors. |
| xup:InternalApplicationError | Empty | The XUP application malfunctions or crashes due to some programming error in the application. |
Note: In the SOAP fault detail column, "none" means the fault detail element does not exist (i.e. errors occured in SOAP header). On the other hand, "empty" means the detail element exists, but its content is empty (i.e. errors occured in SOAP body).
xup:UIError may be used to describe various UI and event errors from the request. The SOAP fault detail element contains the details of
an UI error.
<env:detail><env:detail> <!-- Content: unsupportedEvent? | unsupportedResource? | unsupportedUI? |
eventError? | selectorError? | resourceError? | elementError? | attrError? |
illegalUIValue? --> </env:detail>
The detail element contains several subtypes of errors within xup:UIError. They are not specified as separate SOAP fault codes because SOAP only allows one fault code in each message.
The unsupportedEvent element indicates that the event type in the request is not supported by the server.
<unsupportedEvent><unsupportedEvent/>
The unsupportedResource element indicates that the specified
resource is not supported by the server. Note that whether to report this as an
error depends on the server implementation. For example, some implementation may
simply silently ignore the unsupported resource.
<unsupportedResource><unsupportedResource
resource = xsd:IDREF
<!-- Content: (##empty) --> </unsupportedResource>
The unsupportedUI element specifies unsupported UI elements and attributes in the request. For instance, a particular server implementation may not support
sul:tree, or the "border" attribute of sul:textfield.
Note that whether to report this as an error depends on the server
implementation. For example, some implementation may simply silently ignore the
unsupported UI element or attribute.
<unsupportedUI><unsupportedUI>
element = xsd:IDREF
attr = xsd:QName
<!-- Content: (##empty) --> </unsupportedUI>
element - UI element ID.
attr (optional) - UI attribute name. If specified, this element refers to an attribute; otherwise, this element refers to an element.
The eventError element specifies the event is problematic. For example,
the event detail cannot be successfully parsed. The SOAP faultstring
element could be used to further describe the details of the error.
<eventError><eventError/>
The selectorError element specifies the ID of a problematic
selector. For example, referencing a non-existent selector. The SOAP faultstring
element could be used to further describe the details of the error.
<selectorError><selectorError
selector = xsd:IDREF
> <!-- Content: (##empty) --> </selectorError>
selector - selector ID.
The resourceError element specifies the ID of a problematic
resource. For example, referencing a non-existent resource; adding a resource
which is already in the UI model. The SOAP faultstring element
could be used to further describe the details of the error.
<resourceError><resourceError
resource = xsd:IDREF
> <!-- Content: (##empty) --> </resourceError>
resource - resource ID.
The elementError element specifies the ID of a problematic UI element.
For example, removing a non-existent element; adding to a non-existent parent;
adding an element which is already in the UI model; structural problems such as
an
sul:window in the content of an
addUIElement element being attached as a child to an sul:button.
The SOAP faultstring element could be used to further describe
the details of the error.
<elementError><elementError
element = xsd:IDREF
> <!-- Content: (##empty) --> </elementError>
element - UI element ID.
The attrError element specifies a problematic attribute. For
example, referencing a non-existent attribute. The SOAP faultstring
element could be used to further describe the details of the error.
<attrError><attrError
element = xsd:IDREF
attr = xsd:QName
> <!-- Content: (##empty) --> </attrError>
element - UI element ID.
attr - UI attribute name.
The illegalUIValue element specifies illegal UI element content or attribute value in the request.
A value is illegal if the server implementation does not support it, or if the
value is inappropriate for the current state of the UI element or attribute. For instance, a particular server implementation may not support the value "3d" for the "border"
attribute of sul:textfield. Note that whether to report this as an
error depends on the server implementation. For example, for some UI attributes,
an implementation may simply silently ignore the illegal UI values.
<illegalUIValue><illegalUIValue> element = xsd:IDREF
attr = xsd:QName
<!-- Content: xsd:string -->
</illegalUIValue>
element - UI element name.
attr (optional) - UI attribute name. If specified, this element refers to an attribute; otherwise, this element refers to an element.
Content - the content of the UI element or the value of the UI attribute.
An example
of request processing error is shown below. The error is of type xup:UIError, as indicated in the faultcode
element. The faultstring and detail elements reveal
that the client is trying to remove a non-existent element "buttonZ1".
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
xmlns:xup="http://www.openxup.org/2004/02/xup">
<env:Body>
<env:Fault>
<faultcode>xup:UIError</faultcode>
<faultstring>Removing non-existent element.</faultstring>
<detail>
<xup:elementError element="buttonZ1"/>
</detail>
</env:Fault>
</env:Body> </env:Envelope>
User agent may detect errors when processing server responses. Examples of response processing errors are unsupported event types on selectors, unknown selector, resource, UI element, 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.
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.
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 selectors attached to the UI elements in the response. User agent should automatically remove any event selectors 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
updateUIElement and removeUIElement. If an element's ID is not specified by the XUP application, the server should
automatically generate an ID for the element.