Sys.Net.XmlHttpExecutor executeRequest Method

Executes a Web request as specified in the associated WebRequest instance.

MyExecutor.executeRequest;

Exceptions

Exception type	Condition
Sys.InvalidOperationException	The executeRequest method was called again after the request started. -or- The executor is not associated with an instance of the WebRequest class.

Remarks

To make a Web request, you do not call the executeRequest method directly. Instead, you call the WebRequest.invoke method or the WebRequestManager.executeRequest method. The executeRequest method is intended for future expansion or for use with custom executors.

Note

If you call executor's executeRequest method directly, the WebRequestManager instance will not manage the Web request. Therefore, any handlers that are added by calling the add_completedRequest or add_invokingRequest methods of the WebRequestManager class are not called.

When you call the executeRequest method, the executor constructs and sends an HTTP request by using the HTTP verb, HTTP headers, and request body specified for the associated WebRequest instance. The executor sends the HTTP request by using the browser's XMLHTTP object. For more information, see About Native XMLHTTP.

If the Content-Type header of the associated request object is not set, the executor sets it to application/x-www-form-urlencoded for a POST HTTP request, which is the default setting. If the request body is not set and a request body is required by the browser, the executor automatically sets the body to an empty string (""). This forces the browser to send a Content-Length header. The executor makes sure that the Web request's completed event handler is called as necessary.

After executeRequest is called, the executor can be in one of the following states:

• Started. After the executor has successfully submitted the call to the XMLHTTP object in the browser, the XmlHttpExecutor.started property is set to true. When an executor is active, it remains so for the lifetime of the instance.

• Complete. If the XMLHTTP call succeeds, the XmlHttpExecutor.started and XmlHttpExecutor.responseAvailable properties are set to true.

  A network request is considered completed if the browser's XMLHTTP object returns control to the executor's internal completion handler. However, the status code, status text, or response text might indicate that an error occurred during the request. It is up to the calling code to inspect the response information and determine whether the request returned valid data. For example, it is the responsibility of the element that handles Web services to inspect this information and to determine whether an error occurred when the service was called.

• Timed-out. If the associated request had a non-zero time-out value, and the time-out elapses without another completion event occurring, the executor sets its state to timed-out. This indicates that the network call did not complete in time, and that the executor was not aborted. The executor instance's started and timedOut properties are set to true.

  Note

  If the request's time-out was set to zero and the XMLHTTP request times out, the executor sets its state to completed. Then it raises the completed event of the request object. This means that the started and responseAvailable properties of the executor instance return true. It is the responsibility of the calling code to inspect the status code of the executor to verify that valid data is available, even if the request completed.

If no event handlers exist, when the executor reaches a completion state (complete or timed out), it performs internal cleanups and silently returns.

Note

You cannot call executeRequest multiple times after the started property is set to true. However, if the XMLHTTP object throws an exception after it calls the executeRequest method, you can try to fix the problem and then call executeRequest again.

Example

The following example shows how to make a Web request by using the executeRequest function. This code is part of a complete example found in the Sys.Net.XmlHttpExecutor class overview.

// This function executes a Web request.
function ExecuteWebRequest()
{
    // Create the WebRequest object.
    wRequest =  new Sys.Net.WebRequest();

    // Set the request Url.  
    wRequest.set_url("getTarget.htm");


    // Set the Completed event handler, for processing return data
    wRequest.add_completed(OnCompleted);

      // Clear the results area.
    resultElementId.innerHTML = "";

    // To use executeRequest you must instantiate the
    // executor, assign it to the Web request instance,
    // then call the executeRequest function.
    // Note: Normally to make a Web request you use
    // the invoke method of the WebRequest instance.
    var executor = new Sys.Net.XMLHttpExecutor();
    wRequest.set_executor(executor); 
    executor.executeRequest();

    var started = executor.get_started();

    alert("Executor started: " + started);
}

See Also

Reference

Sys.Net.WebRequestManager Class

Sys.Net.WebRequestExecutor Class

Sys.Net.XMLHttpExecutor Class

Other Resources

About Native XMLHTTP