Streamezzo S.A. - All rights reserved
Copyright 2001-2010
How to manage errors
This tutorial explains how to take care of potential errors that may raise during a Rich Media Application usage.
One should always consider how the application should react to such errors in order to take the appropriate decision, either restoring the application in a relevant state or at least informing explicitely the end-user that something wrong happened.
Principle
Streamezzo provides straightforward facilities to intercept and handle errors either raised by the device system or by the server, then to react accordingly.
There are 4 major categories of errors:
- system errors, i.e. errors raised by the device system itself
- network errors, i.e. errors related to the network communication between client and server
- media errors, i.e. errors that may occur during bitmap / audio / video content download and decoding
- server runtime errors, i.e. errors raised server-side, especially while accessing 3rd party data, such as back-ends
System and Network errors
Intercepting system and network errors is based on registration: the application can register to identified errors and in such case the system will only relay them to the application and will not take care of them (it will not display an error prompt, especially); then the application will be able to identify which error has been raised and decide how it should react / adapt to it (like displaying a specific message within the application or restoring the application in a convenient state).
Of course it is also possible, during the application lifetime, to unregister errors, in case it is no more relevant to handle them at application level.
In order to make it easier to handle globally errors of the same category, it is possible to register not only to a single type of error (error code) but to a family of errors gathering multiple types of errors (error codes) like system, network and script errors.
Media errors
Intercepting bitmap / audio / video related errors is based on listening: the application can declare itself as a listener to media, specifying which error events it is interested into. Once this is done, at anytime such event will be raised, a specific handling can be defined to take care of such error.
Such errors can be for instance an unreachable server, a decoding failure, a RTSP error code...
Server runtime errors
Dealing with errors server-side is a matter of pure J2EE coding; when a RSP processing fails or fails in attempting to retrieve some data or interoperate with a 3rd party service (database, Content Management System (CMS)... or any back-end in general), either an Exception shall be thrown and properly caught, or a specific error code shall be retrieved and taken into consideration.
Managing such errors has mostly nothing specifically related to Streamezzo Rich Media Solution and can be easily compared to Java Server Pages (JSP) technology. One can in addition rely on the provided logging system to track down relevant information (that can be consulted through Streamezzo Rich Media Server administation console) when such errors occur.
Features
System and Network errors
As stated above, it is possible to register / unregister system and/or network errors or a categories of such errors.
- cmd://registerError
- ?code=[myError(s)Code]: a predefined code error or category of code errors (see list below) to register
- &target=[myStartableNodeDEF]: the startable node DEF to start in case the code error is raised
- cmd://unregisterError
- ?code=[myError(s)Code]: a predefined code error or category of code errors (see list below) to unregister
- &target=[myStartableNodeDEF]: the startable node DEF that was started in case the code error is raised
- cmd://unregisterAllErrors: cancels all errors registrations
Available error codes are listed below (error codes catagories are displayed in bold):
| # | Code | Description |
|---|---|---|
| - | error | All errors |
| - | error.system | All system errors |
| 1 | error.system.general | Severe error which has not been categorized |
| 2 | error.system.panic | Fatal error |
| 3 | error.system.resource | Error while trying to access system resource |
| 5 | error.system.argument | Invalid argument |
| 6 | error.system.corrupted | Corrupted data read from an URN This error is raised when a file or server stream is corrupted, but the most frequent use case is when reading a HTTP 200 response from a server with a HTML page giving a visual 404 error. |
| 7 | error.system.notavailable | Unavailable resource |
| 8 | error.system.notsupported | Use of unsupported feature attemp This error is raised when trying to read a non (yet) supported instruction. |
| 9 | error.system.completion | Completion error |
| 10 | error.system.timeout | Timeout error |
| 11 | error.system.malformed | Malformed URI |
| - | error.network | All network errors |
| 4 | error.network.notfound | Non-existing URL opening attempt This error may happen when trying to access unavailble local or remote content. |
| 12 | error.network.dns | Host names resolution error. Since this call is the first network operation when trying to access a remote content, it is raised when there is a 'device level' issue for accessing network: no modem, no SIM card, no APN configured or improper operator agreement. |
| 13 | error.network.request | Request to server sending error |
| 14 | error.network.open | Local or remote resource opening attempt This error is raised when the server sends an explicit '404' error code. |
| 15 | error.network.refused | Server connection error This error is raised when the TCP connection is refused. |
| 21 | error.network.connection | Network connection establishing This error may happen when a wrong APN has been selected or when the device is out of network range. |
| 22 | error.network.cancel | Network connection cancel |
| 22 | error.network.offline | Foreseen network error (e.g. because of offline mode or because there is no SIM card) |
| - | error.network.http | All network HTTP errors |
| 16 | error.network.http.header | Invalid HTTP header while reading from a HTTP server |
| 17 | error.network.http.request | HTTP request error |
| 18 | error.network.http.response | HTTP response error (e.g. no response received or invalid response while reading from a HTTP server) |
| 19 | error.network.http.redirect | Invalid HTTP field for redirection |
| 23 | error.network.http.nosecuresupport | HTTPS is required but is not supported by the device |
| 24 | error.network.http.invalidcertificate | Invalid certificate has been returned by server |
| - | error.script | All InstantScript errors |
| 26 | error.script.unsupported | InstantScript is required but is not supported |
Practically one will have to handle such error cases:
- error.system, in order to cover any error the device system may raise; in such case the end-user is usually informed something went wrong, then the application is quitted
- error.network, in order to cover any error while attempting to connect to a server; in such case the end-user is usually informed, then the application may either offer to reattempt connection or offer offline browsing
- (if relying on secured connection (i.e. HTTPS), one may in addition take care of specifically related error codes, i.e. error.network.http.nosecuresupport and error.network.http.invalidcertificate)
Specific notes:
- Error registration is maintained when going through appended scenes / lost when accessing a non appended scene.
- If a specific error E is included in a given error group G that is listened, if this specific error E is explicitly specified as listened, when E is raised only the behaviour associated to E is triggered, not the behaviour associated to G.
- Depending on the device, some precise error codes may not be raised but the more general error code instead (like error.network.notfound). This is why one usually rely on the general error codes, as mentioned above.
Media errors
As stated above, it is possible to listen to events raised while rendering bitmap, audio or video content.
EventListenerRegister Update grants such ability, taking as parameters:
- source: the id (DEF) of the media to listen to
- events: the list of events to listen too (see list of error events below)
- target: the id (DEF) of a startable node that will be started in case the event is raised
Available error codes are listed below (error codes catagories are displayed in bold):
| Event | Description |
|---|---|
| ImageDecodeFailure | Bitmap could not be decoded |
| ServerUnreachable | Server cannot be reached or closed the connection (DNS/TCP connect failure/TCP close) |
| RTSP_4XX | Client error status code is reported (refer to RFC-2326) |
| RTSP_5XX | Server error status code is reported (refer to RFC-2326) |
| RTPTimeOut | RTP timeout occurred (usually because of a firewall) |
| Error | Error has been encountered by the Audio/Video Player |
Specific notes:
- EventListenerRegister must be defined or else activated after both its source and its target are declared within the scene graph, else it would be ignored and have no effect
Server runtime errors
As stated above, handling such errors server-side is only a standard matter of J2EE coding, nothing is specific to Streamezzo Rich Media Solution.
Anyway an integrated logger is provided in Streamezzo framework in order to able to log relevant information than can then be accessed through Streamezzo Rich Media Server administration console.
This object (ServiceLogger class) can be accessed through stzServer.getLogger() and offers the usual methods per log level: debug < info < warn < error < fatal.
Specific notes:
- Due to streaming - i.e. the RSP generated rich media content is sent progressively while it is being processed - when an Exception is caught inside a scene that is supposed to be stored in client-side cache, one will usually have to cancel the storage in cache as the obtained scene is not relevant for caching. This can be achieved relying on the CancelClientCache update.
- Due to the cacheObject principle - i.e. other scene data that is sent is the same response as the currently processed RSP - when an Exception is thrown within a cacheObject RSP, it must not be caught within the cacheObject RSP itself but forwarded and caught within the calling RSP so it can react appropriately. Otherwise the somehow incorrectly processed cacheObject RSP will be stored in client-side cache anyway which is usually not relevant.
Examples
System and Network errors
The provided sample code below illustrates in a very simple way how to intercept all network related errors and then display a message on screen.
"/>
Media errors
The provided sample code below illustrates in a very simple way how to intercept media related errors and then display a message on screen.
" colorBits="8"
lengthBits="16" resolution="2" idBits="16" scaleBits="15"
encodingType="0"/>
Server runtime errors
The provided sample code below illustrates in a very simple way how to catch an Exception and log information accordingly.
"
colorBits="8" lengthBits="16" resolution="2" idBits="16" scaleBits="15"
encodingType="0"/>
<%
try {
%>
<%
} catch (Exception e) {
stzRequest.getLogger().debug("EXCEPTION: " + e.getMessage());
%>
<%
}
%>
Conclusion
One will usually have to take care of:
- general system error
- general network error
- media errors, especially when rendering audio / video content
- server runtime errors, anytime it is relevant to handle RSP generation failure, especially when accessing a 3rd party back-end
To do so the usually applied good practice for client-side errors consists in having a local scene dedicated to errors management, thus granting the ability to:
- be accessible even in case the network is not available
- gather errors management at a single place
According to the intercepted error, the application behaviour will usually consists in:
- displaying an informative popup to the end-user (providing the relevant level of information to him)
- downgrading the application available features set when applicable (like offering offline browsing only if no network connection is available)
- leaving the application if the error is too critical (when the application cannot be used in such context)
| Attachment | Size |
|---|---|
| Error_registration.swz | 2.48 KB |
| Video_error.swz | 2.42 KB |
| Exception_log.swz | 2.67 KB |
