ChartDirector Ver 5.0 (PHP Edition)

JsChartViewer.streamUpdate

Usage

streamUpdate(timeout)

Description

Refreshes the <IMG> that the JsChartViewer is bound to.
Unlike JsChartViewer.partialUpdate, this method does not send the JsChartViewer state to the server. It merely sends a new request to the server using the existing URL of the <IMG> tag.
If this method is called periodically (eg. using a Javascript timer), and the server sends the most updated chart for these requests, then the chart will appear to be automatically update.
One can always refresh an <IMG> tag using standard client side Javascript without using JsChartViewer at all. This method offers the following additional features:

- Double buffering
  Instead of directly refreshing the <IMG> tag, this method will create a hidden Javascript Image object using the same URL as the <IMG> tag, and will update that hidden Image object. When the update is completed, it will copy the hidden Image object to the <IMG>.
- Overlapping updating
  Due to the nature of Internet connections, it is sometimes hard to predict the response time for a chart update. For application that needs to update the chart frequently, it may be possible the a new request be sent before an existing request is completed.
  In standard Javascript, if a new update request is sent before an existing request is completed, the existing request will be aborted, and the new request will be used. However, for periodic updates, if new requests are sent faster than the time needed to update the chart (eg. the chart update needs 20 seconds, but new requests are sent every 15 seconds), then all update requests will be aborted by the next update requests, and the chart will not update at all. Furthermore, the network and/or the server will be overwhelmed by these requests.
  In the streamUpdate method, new update requests will be ignored until existing requests are completed, or until a given timeout has occurred. This ensures the chart does get updated.
- Error handling
  In standard Javascript, if an <IMG> tag update request failed, the browser may display a "broken image symbol".
  In the streamUpdate method, if the update request failed, nothing will happen, and the existing chart will still be shown. The system will simply wait for the next update request.
- Cache avoidance
  To avoid caching by the browser and/or intermediate proxy servers, the streamUpdate method will append dummy unique query parameters to the <IMG> URL to ensure each URL is unique, and so avoids the cache.

Arguments

Argument | Default | Description
--- | --- | ---
timeout | 60 | If there is an existing non-completed streamUpdate request, the timeout value determines whether to abort the existing request, or to ignore the current request and continue with the existing request. If the existing request has been pending for longer than the timeout in seconds, it will be aborted, otherwise it will continue.

Return Value

True if the current streamUpdate request is sent out. False if the request is not sent out (due to an existing request that has not timeout).

© 2009 Advanced Software Engineering Limited. All rights reserved.