The process for receiving data depends on whether the data is valid XML or another format. Receiving XML DataTo receive XML data, call the getResponseXML() method on the Request instance. This method returns a jsx3.xml.Document object, which is an XML document in a format that General Interface can use, as shown in the following example: //initialize and open var reqSocket = jsx3.net.Request.open("GET",jsx3.GO('myURLComponent').getValue(), false); //send the request reqSocket.send(); //get the XML response var repXML = reqSocket.getResponseXML(); To save the response document for repeated access, use the setDocument function to load it into the local data cache as follows: myApp.getCache().setDocument("MyCacheDocument", repXML);
Also note that the Request class has different methods for accessing data. The example shown above is the simplest of all data calls: a synchronous HTTP GET. In fact, requesting and caching data in this manner can be done with only one API call, openDocument as shown in the following example: var repXML = someApp.getCache().openDocument(someURL,someCacheId); The Cache class has different methods for accessing data more efficiently than the {{openDocument}} method just described. For example, the method {{getOrOpenDocument}} will first check the cache for the document before attempting to load it. If the document is large or the server will respond with a known latency, fetch the document asynchronously, using {{getOrOpenAsync}}. This method returns the corresponding document synchronously if it already exists in the cache. If the document does not exist in the cache, then it is loaded asynchronously and the method returns a placeholder document. The namespace URI of this placeholder document is {{jsx3.xml.Cache.XSDNS}} and its root node name is {{loading}}. Because the cache stores this placeholder document until the document finishes loading, subsequent calls to synchronous APIs (such as {{getDocument() and getOrOpenDocument()}}) may also return the placeholder document. It is therefore important to check the namespace of the returned document when any code uses the asynchronous APIs. Once a document finishes loading asynchronously the placeholder document is replaced with the loaded document. This change in value causes the cache to publish a pair of events of action {{Cache.CHANGE}}. If loading the document fails or times out, the placeholder document is instead replaced with another placeholder document. This document also has a URI namespace of {{Cache.XSDNS}}. Its root node name may be either {{error}} or {{timeout}}. If the root node name is {{error}} then the root node has an attribute, also named {{error}}, which contains the XML error message. h4. Handling Failures If the incoming XML can't be parsed by the {{Request}} instance, the {{getResponseXML}} call fails. One possible cause of failure is invalid XML, while another is an unrecognized content type specified in the HTTP header. The server must set this field in the HTTP header to {{text/xml}} or similar. If the {{getResponseXML}} call fails but the content is valid XML, you can still parse it by calling the {{getResponseText()}} method and passing the XML string into a {{jsx3.xml.Document}} instance as follows:{code:lang=javascript}var objXML = new jsx3.xml.Document(); objXML.loadXML(XML_string); if(!objXML.hasError()) alert("success:\n\n" + objXML.getXML()); For more details on the getResponseText() method, see Receiving Non-XML Data. Receiving Non-XML DataTo receive non-XML data, call the getResponseText() method for the Request instance. This method returns the body of the response as a string value, as shown in the following example: var strText = objRequest.getResponseText();
window.alert(strText);
Non-XML data is useful in many situations. For example, non-XML data can be displayed in the application by setting it as the text property of a jsx3.gui.Block object, or it can be reformatted into CDF for use by a Matrix component. Also, if the data is converted to XML, it can be stored in the local data cache to facilitate data access and management. |
Contents
|