DOAP: Dave's Own Access Protocol

Errors

If DOAP experiences an error it will throw a DOAP_Error object containing an error code (DOAP_Error.code) and textual description (DOAP_Error.desc).

Additionally JavaScript errors may be encountered in using the XMLHTTP or other functionality and will themselves throw errors. For this reason it's always a good idea to enclose the DOAP call in a try/catch block and deal with errors that occur (as shown in all the examples).

Error codes starting at 100 are client-side errors (e.g. failure to create xmlhttp object or handling error), and codes starting at 200 are server-side generated errors (e.g. incorrect number of parameters).

Additionally user code can generate an error from the server-side as is shown in the following example.

Error generation example (click here to see it run).

Server-Side DOAP Server PHP

<?php
ob_start(); // ensure no messy output from includes
 
// Our function that needs two parameters
function needstwo($one, $two)
{
	return "Yep got two parameters to needstwo()";
}
 
function usererror() // shows how to generate your own DOAP error
{
	global $doap; // must know the name of the DOAP Server object and have it in scope
	$doap->Error(999,"This is a user generated error"); // error and output it
	exit(); // now die to stop any other junk or results getting sent
}
 
require("xmlcreate.inc.php"); // include the xmlCreate library
require("doap.inc.php"); // include the DOAP Server library
 
$doap = new DOAP_Server(); // create a DOAP Server object
 
// register the needstwo function with a minimum and maximum of 2 parameters
// e.g. there must be two parameters
$doap->Register("needstwo",2,2);
 
// register the usererror function with 0 parameters
$doap->Register("usererror",0,0);
 
ob_clean(); // clean any messy output from includes
 
$doap->Process(); // get DOAP Server to process the request
?>

The server code defines two functions - needstwo() which takes two parameters and is registered as such as usererror() that takes no parameters but generates a user generated error using the DOAP_Server::Error method.

Client-Side DOAP Server HTML/JavaScript

<HTML>
<HEAD>
<TITLE>DOAP Example 4: Errors</TITLE>
<!-- Include the DOAP Client JavaScript -->
<SCRIPT TYPE="text/javascript" SRC="doap.js"></SCRIPT>
 
<SCRIPT TYPE="text/javascript">
var doap = new DOAP(); // create the DOAP Client object
doap.url = "example4.php"; // set the DOAP Server URL
 
 
function errorcall( etype ) // call the relevent function with parameters or not
{
	try
	{
		if (etype == "too_few")
		{
			var params = Array(); // parameters are passed in an array
			params.push("A");
			var result = doap.call('needstwo',params); // call needstwo() on server passing params
		}
		else if (etype == "just_right")
		{
			var params = Array(); // parameters are passed in an array
			params.push("A");
			params.push("B");
			var result = doap.call('needstwo',params); // call needstwo() on server passing params
		}
		else if (etype == "too_many")
		{
			var params = Array(); // parameters are passed in an array
			params.push("A");
			params.push("B");
			params.push("C");
			var result = doap.call('needstwo',params); // call needstwo() on server passing params
		}
		else if (etype == "user_error")
		{
			var result = doap.call('usererror'); // call usererror() on server
		}
		else var result = "Huh?"; // unknown etype to call
	}
	catch(e) // catch any errors
	{
		// deal with any errors if it's a DOAP error or any other type of exception
		if(e instanceof DOAP_Error) alert("DOAP Error "+e.code+": "+e.desc);
		else alert("Unknown Error: "+e);
		return; // and exit the function if an error was encountered
	}
	// if we get here output the result
	document.getElementById('results').innerHTML = result;
}
 
</SCRIPT>
</HEAD>
 
<BODY>
<DIV ID="results" CLASS="result_div">Results will appear here BY MAGIC!</DIV>
<BR /><BR />
 
<!-- The links to call needstwo with different numbers of parameters -->
<A HREF="#" onClick="errorcall('too_few');">Call needstwo() with 1 parameter</A><BR />
<A HREF="#" onClick="errorcall('just_right');">Call needstwo() with 2 parameters</A><BR />
<A HREF="#" onClick="errorcall('too_many');">Call needstwo() with 3 parameters</A><BR />
<BR />
 
<!-- And to call usererror() to generate a user made error in code -->
<A HREF="#" onClick="errorcall('user_error');">Call usererror() to throw a user error</A>
<BR /><BR />
 
<!-- And a link to clean the results div back if needed -->
<A HREF="#" onClick="document.getElementById('results').innerHTML='<BR />';">Clear Results DIV</A>
 
</HTML>

The client offers the option to call needstwo() with 1, 2 or 3 parameters. With 1 or 3 errors should be generated at the server and returned to the client. Only 2 parameters should succeed.

The other option is to call user_error which should produce a user-code generated error from the server.

<< Arrays

Contents

Synchronous Requests >>