Using XML: A PHP Developer's Primer, Part 4, Section 2 - Page 2

A few points to note from the script shown on the previous page:

When comparing the XML-RPC version of the validation script to the Ajax version, the code structure is somewhat more logical and easier to follow. It is no longer up to the developer to interpret, validate and parse the request--this is now handled by the XML_RPC_Server object.

In the original email validation application, the client side work was done by an Ajax engine. This Ajax engine will be replaced with an RPC engine which uses the AJ-RPC client to make the RPC calls to our server. Technically, the client side portion of the application will still use Ajax to communicate with the server, however this task has now been delegated to the AJ-RPC client.

The AJ-RPC client has a similar interface to the PEAR XML-RPC client. First an instance of the XMLRPCClient needs to be created and initialized with the URL of the RPC endpoint (n.b: Javascript will only allow communication with a server that resides on the same domain as the page making the request):

var client = new XMLRPCClient('rpc_server.php');

Methods can be added to the client in several ways. The easiest way is to call the aqquireFunctions() function. This causes the XMLRPCClient object to make a call to the system.listMethods function, which is provided by default on all XML-RPC servers. This method returns a list of all functions provided by the server:

if (! client.aqquireFunctions()) { // incase the call to system.listMethods fails
    client.addFunction('strlen'); // add a function by name
   
    var strlen = new XMLRPCFunction('strlen');
    client.addFunction(strlen); // add a XMLRPCFunction object
}

Functions can also be added to the client manually using the addFunction function. Once a function has been added to the client, it can be called as a function of the client, and its parameters passed as usual:

try {
    var len = client.strlen('i am a string');
} catch (response) {
    /* function returned some kind of fault */
    var code = response.getFaultCode();
    var description = response.getFaultDescription();
}

The code above demonstrates how to call a function synchronously. Synchronous calls should only be used during page load; a slow response from the RPC server will block all other scripts and events on the page. When called synchronously, fault responses are thrown as exceptions.

To call an RPC asynchronously, the onresponse event handler of the XMLRPCClient object or individual XMLRPCFunction must be set to a callable function. This function will receive a single argument: an XML_RPC_Response object:

client.onresponse = function(response) // set a response handler for all functions
{
    var functionName = response.getCaller().gtFunctionName(); // get the name of the function that made the call
}

client.getFunction('strlen').onresponse = function(response) // set a response handler for an individual function
{
    if(! response.isFault()) {
        var returnVal = response.getReturnValue().getValue();
    }
}

client.strlen(); // the function will now be called asynchronously

The client-side part of the email validation application works in a similar way as the Ajax version and calls all the RPC methods asynchronously. I have therefore detailed only the relevant changes. The entire script can be found in the ZIP file accompanying this article.

The init() function which initializes the environment now creates an instance of the XMLRPC client and assigns the onresponse event handlers to the RPCs which are to be called. If the XMLRPCClient object cannot create an instance of an XMLHTTPRequest object, it throws an exception. This is caught by the init function and causes it to stop executing.

Javascript:


/* initializes the environment and sets up all variables - called on the onload event of the document body */
function init()
{
    /* close the document output*/
    document.close();

    try {
        emailValidator = new XMLRPCClient('email_validate.php');
    } catch (e){
        return;
    }

   
    emailValidator.aqquireFunctions();

    emailValidator.getFunction('emailValidator_validate').onresponse = validateCallback;
    emailValidator.getFunction('emailValidator_verify').onresponse = verifyCallback;

    /* initialize global variables */
    theForm = document.getElementById('formEmail');
    btnSubmit = document.getElementById('btnSubmit');
    txtEmail =  document.getElementById('txtEmail')
    verify =  document.getElementById('verify')
    verifyMsg =  document.getElementById('verifyMsg');
    txtVerify =  document.getElementById('txtVerify');
    btnVerify = document.getElementById('btnVerify');
    emailMsg =  document.getElementById('emailMsg');
   
    /* disable the submit button */
    btnSubmit.setAttribute('disabled', 'disabled');
   
    txtEmail = document.getElementById('txtEmail');

    /* set the onchange event of the email input box to the validateAddress() function */
    txtEmail.onchange = validateAddress;
}

The validateAddress function is executed when the text contained in the email address field is changed. It executes the emailVlaidate.validate RPC. The response is handled by the validateCallback function which first checks that the response is not a fault. It then loads the two items in the return value: the validation result and the email ID into two variables.

Javascript:

function validateAddress()
{
    var email = theForm.email.value;
    var id = parseInt(theForm.email_id.value);

    startupState(); // set initial state

    if (email != ' ') {
        // execute RPC - if an email ID is present, send that too
        if (id) {
            emailValidator.emailValidator_validate(email, id);
        } else {
            emailValidator.emailValidator_validate(email);    
        }
    } else {
        return;
    }
}

function validateCallback(response)
{
    if (response.isFault()) { // if a fualt occured - something strange happened; disable
        btnSubmit.removeAttribute('disabled');
        txtEmail.onchange = null;
        verify.style.display = 'none';

        return;    
    }

    var emailID = response.getReturnValue().getValue().email_id;
    var validated = response.getReturnValue().getValue().validated;

    if (validated) {
        emailMsg.style.display = 'none';
        
        verify.style.display = 'inline';
        verifyMsg.innerHTML = '<b>An Email containing your verification code has been sent to this address. Please Enter it before continuing.</b>';
        theForm.email_id.value = emailID;
    } else {
        verify.style.display = 'none';
        emailMsg.innerHTML = '<b>You have entered an invalid email address. Please correct it before continuing.</b>';
        emailMsg.style.display = 'block';
    }
} 

The checking of the verification code is handled by the verifyAddress and verifyCallback functions. The verifyAddress function is executed when the verify button on the form is pressed. It executes the emailValidator.verify RPC which it passes the email ID and verification code typed by the user. The response is received by the verifyCallback function. Notice here how the fault code is checked, as the RPC may return one of several possible faults:

Javascript:

function verifyAddress()
{
    var v_code = theForm.v_code.value;
    var id = parseInt(theForm.email_id.value);

    if (v_code == ' ') {
        alert('No Verification Code Entered');
        theForm.v_code.focus();
        return;
    }

    emailValidator.emailValidator_verify(id, v_code);
}

function verifyCallback(response)
{
    if (response.isFault()) {
        switch (response.getFaultCode()) {
            case -102: // email ID is invalid - clear and revalidate
                theForm.email_id.value ='';
            case -101: // email is not validated
                validateAddress();
                break;
            default:
                btnSubmit.removeAttribute('disabled');
                txtEmail.onchange = null;
                verify.style.display = 'none';    
        }

        return;    
    }

    var v_code = theForm.v_code.value;

    if(response.getReturnValue().getValue()) { // successful verification
        btnVerify.setAttribute('disabled', 'disabled');
        txtVerify.setAttribute('disabled', 'disabled');

        btnVerify.innerHTML = '<i>Verified</i>';
        verifyMsg.innerHTML = '';
        
        btnSubmit.removeAttribute('disabled');
        return new XML_RPC_Response(new XML_RPC_Value(''), '-101', 'Email not validated.');
        verifyMsg.innerHTML = '<b><i>' + theForm.email.value + '</i></b>';
        theForm.email.value = '';
    } else {
        verifyMsg.innerHTML = '<b>Verification Failed</b>';
    }
}

 

Again, drawing comparison between the original Ajax validation engine and the RPC version, you'll notice that the code is a lot cleaner and easier to understand.

XML-RPC simplifies the creation of distributed applications by providing a standard interface by which developers can use to call procedures on remote machines. The very concept of RPC and similar technologies fits in with one of the core objectives of all modern day programming languages: Code Reuse. Why create your own search facility, when Google does it better? Why implement your own blogging system, when several sites provide it for you? The adoption of these XML-based services including RSS, ATOM and RPC by large corporations such as Google and Microsoft is testament to the fact the web is evolving.

Before using XML-RPC, it is worth noting that it is not without it drawbacks:

• Calling an RPC is resource intensive, as the client / server needs to encode/decode the method call and all of its parameters. The calls should be kept to a minimum and where possible the responses should be cached and reused.
• RPCs are often sent across unreliable networks, therefore a response may be slow and in some cases is not guaranteed. You must consider how long you / your users are prepared to wait and implement an appropriate time-out policy, falling back on cached responses where the remote endpoint is unavailable.
• Like mentioned previously. RPC alone does not provide or support the object orientated methodologies used in many modern day programming languages. Where object orientated RPCs are essential, you should consider using SOAP or WSDL.

Our next article is going to delve deeper in the world of RPC by taking a look at how SOAP and WSDL are used to completely automate RPCs at the two endpoints and how they serve to describe complex data types and the operations that can be carried out on them.

Useful Links

• XML-RPC Specification

• PEAR XML-RPC Documentation

• Flickr API Documentation

• Google API

• SOAP Specification