/**
 * Objects made from this class handle messaging between client 
 * and server for the Gigapan Explorer Application.  Within the confines
 * of the client part of the application, this class represents the
 * Model in the Model-View-Controller architecture.
 * <br><br>
 * <a href="mailto:ehudsons@andrew.cmu.edu">Ellen Hudson-Snyder</a>, 
 * <a href="mailto:evedar@andrew.cmu.edu">Elvin Vedar</a>,
 * <a href="mailto:cbalz@andrew.cmu.edu">Christopher M. Balz</a>.
 * <br><br>CVS Version Info:<br>
 *  $Id: Messenger.js,v 1.11 2005/11/06 08:32:27 cbalz Exp $  
 * <br><br>
 * @emits-event <code>onafterreceive</code>.
 * @listens-to-event <code>onreadystatechange</code> from the 
 *                   <code>this.objCrossBrowserXmlHttpRequest.objXmlHttpRequest</code> xml-http communications 
 *                   object.
 * @class-prop   <code>string</code> <code>STR_HTTP_404</code> The http file-not-found error code.
 * @object-prop  <code>string</code> <code>strId</code>  The i.d. of this object.
 * @object-prop  <code>string</code> <code>objType</code>  The type of object that this class creates.
 * @object-prop  <code>AbstractXMLHttpRequest</code> 
 *               <code>objCrossBrowserXmlHttpRequest</code>  A reference to the object that handles the xml 
 *               request communications over http.  Its concrete
 *               type depends upon whether the Gigapan Explorer application is running on a web browser
 *               from Microsoft (tm) or not.
 * @object-prop  <code>Gigapan</code> <code>objParent</code>  The parent of a given object created from this class.
 * @object-prop  <code>Object</code> <code>objMessage</code>  A xml document, in object tree form,
 *                                   that is a message either from the 
 *                                   server or to be delivered to the server.
 * @author Team GigaToasted (Fall-2005-CMU-NASA/Google-Practicum Subteam) 
 * @version 1.0
 */


Messenger.STR_HTTP_404 = "404";

/**
 * Create a <code>Messenger</code> object.
 * @param objParent  <code>Object</code>  The parent, if any, of this object.
 */
function Messenger(objParent) {
    this.strId = "messenger";
    this.objType = "communications_object";
    this.objParent = objParent;

    this.objCrossBrowserXmlHttpRequest = null; 
    this.objMessage = null; 

    this.send = Messenger_send;
    this.receiveEvent = Messenger_receiveEvent;
    this.onAfterReceive = Messenger_onAfterReceive;
    this.getXmlResponse = Messenger_getXmlResponse;
    this.getResponseStatus = Messenger_getResponseStatus;

    // Register Events:
    self.gloScope.registerEvent(this.strId, this, "CrossBrowserXMLHttpRequest", "onreadystatechange");
}


/**
 * This method sends a message.  Specifically, it creates a new wrapper object 
 * for a browser-native xml-http object and then sends an asynchronous xml request over http.
 * @param pStrRequestUri  <code>string</code> A url pointing to the intended recipient of the message.
 * @param pObjMessage <code>Object</code>  OPTIONAL An xml document.
 */
function Messenger_send(pStrRequestUri, pObjMessage) {   
    if (arguments.length < 2) {
        pObjMessage = null;
    }
    this.objCrossBrowserXmlHttpRequest = self.Environment.getNewXmlHttpRequest(pStrRequestUri);
    this.objCrossBrowserXmlHttpRequest.send(pObjMessage);
}
    

/**
 * This method returns the xml object contained in a response to a
 * successful xml-http request.
 * @returns <code>Object</code>  An xml object conformant to w3c dom standards.
 */
function Messenger_getXmlResponse() {   
    return this.objCrossBrowserXmlHttpRequest.objXmlHttpRequest.responseXML;
}


/**
 * This method returns the status code of the response to an xml-http request.
 * @returns <code>integer</code>  An http status code.
 */
function Messenger_getResponseStatus() {   
    return this.objCrossBrowserXmlHttpRequest.objXmlHttpRequest.status;
}


/**
 * This method is an event handler that emits the <code>onafterreceive</code> event.
 */
function Messenger_onAfterReceive() {
    if (this.objParent.booTestMessaging) {
        alert("Messenger received a message via xml-http: \n\n" + 
              "Message Status: " + this.getResponseStatus() + "\n" + 
              "Message Status text is: " + this.objCrossBrowserXmlHttpRequest.objXmlHttpRequest.statusText);        
        alert("Message Response Text is: \n" + this.objCrossBrowserXmlHttpRequest.objXmlHttpRequest.responseText + "\n");
    }
    
    if (this.getResponseStatus() == Messenger.STR_HTTP_404) {
        alert("Error: The xml file requested, at: \n " +
              "   " + this.objCrossBrowserXmlHttpRequest.strRequestUri +
              "\n cannot be found.  This may be because the server is " +
              "down or is experiencing technical difficulties.  " + self.gloScope.objStrings.strCopyAlert + 
              "\n\nIf the server has no problems: " + self.gloScope.objStrings.strConfigErrorRemedy);
        return false;
    }
    
    self.Environment.handleEvent(this.strId, 'onafterreceive', this.objCrossBrowserXmlHttpRequest);
}


/**
 * This method receives any events that this object listens to and 
 * routes them to the proper methods. 
 * @param pStrEventSourceElementId <code>string</code> The i.d. of the document object model from which the event sprang.
 * @param pStrEventType  <code>string</code> The event type of the object (e.g., 'onclick', etc).
 * @param pObjEvent  <code>Object</code> The event object itself.
 */
function Messenger_receiveEvent(pStrEventSourceElementId, pStrEventType, pObjEvent) { 
    if (pStrEventType == "onreadystatechange") {
        if (pStrEventSourceElementId == "CrossBrowserXMLHttpRequest") {
            this.onAfterReceive();
        }
    }
}