XHTTP JavaScript Client v1.0
Copyright (c) 2011-2012 James Watts (SOLFENIX)
http://www.solfenix.com
This is FREE software, licensed under the GNU/GPL
http://www.gnu.org/licenses/gpl.html
This software implements the XHTTP protocol
http://www.xhttp.org
The XHTTP JavaScript client allows you to connect to a server which
interprets the Extended Hypertext Transfer Protocol (XHTTP).
To use the XHTTP JavaScript client in your web application first
include it in the HEAD of the document:
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>My Site</title>
<script type="text/javascript" src="path/to/xhttp.js"></script>
</head>
<body>
<!-- your content here -->
</body>
</html>
To create an XHTTP request we'll use the XRequest class. This creates
a request object, using setHost( String host ) for the node to
connect to, setService( String service ) for the service to call,
setAction( String action ) for the action to perform, and
setArguments( Array arguments ) to define the arguments to pass to
the action, for example:
var request = new XRequest();
request.setHost( 'http://www.solfenix.com/xnode?value=33' );
request.setService( 'example;*.*' );
request.setAction( 'foo' );
request.setArguments( [ new XInteger( 'value', 33 ) ] );
When defining the arguments to pass to an action there exist classes
for each data type available, these are:
- **XNull:** Discriminated null value. Defaults to an empty value (no value).
- **XBoolean:** Boolean logical value (1 or 0). Defaults to 0.
- **XInteger:** Whole number. Defaults to 0.
- **XDouble:** Double precision floating point number. Defaults to 0.0.
- **XString:** String of characters. Defaults to an empty value (no value).
- **XArray:** Array of values, storing no keys. Defaults to []. *
- **XStruct:** Associative array or object. Defaults to {}. *
- **XLambda:** Anonymous or named function. Defaults to {}. *
- **XBase64:** Base64-encoded binary data. Defaults to an empty value (no value).
- **XDateTime:** Date and time in ISO-8601 16 format. Defaults to the current date and time.
Each class construct expects 2 arguments, the "name" of the argument,
and the "value".
Creating a request object doesn't send the petition to the server
until you create an XResponse object. The XResponse object can handle
a single XRequest object or an array of multiple XRequest objects.
Each XRequest object has an isReady( void ) method to check that the
request is ready to send and isn't missing require values, such as
the "host" or the "service".
Once processed by the XResponse object, the isComplete( Number index )
method specifies if the response could complete the request
successfully. And finally, the getReturn( Number index ) gets the
value returned by the action, for example:
var response = new XResponse( request );
if ( request.isReady() )
{
if ( response.isComplete() )
{
var result = response.getReturn();
}
}
In the case of handling multiple requests, each method of the
XResponse object expects the index of the array of requests to access
the data of the specific request.
Handling requests and responses can be a tedious process. However,
XHTTP provides the functionality of exposing the schema for a
service. This allows implementations to provide the option to build a
remote API. The XHTTP JavaScript client provides this specific
functionality through the schema( String method, String host, String
service, String action, String version ) method of the XHttp object,
for example:
var example = XHttp.schema( XRequest.GET, 'http://www.solfenix.com/xnode', 'example', '1.*' );
The example object is now an API which models the "example" schema,
so we can now call the "foo" action as a method of this object:
var result = example.foo( new XInteger( 'value', 33 ) );
