Calling a service via JavaScript

So far, information from services has been fetched via the <svc> tag and posted via form submission. There is also the ability of interacting with services from the browser itself via JavaScript.

Similarly to the form submission, if the service is refereced as JavaScript, the service methods can be used. In order to use the services via JavaScript, include the Request.js utility and the full name of the service, including the .js extension:

<script src="/js/org.benow.util.Request.js">;</script>
<script src="/svc/doc.walkthru.AlbumService.js">;</script>

The Request.js script contains required methods. The AlbumSerivce.js is generated and contains helper methods to map requests to the service backend and back. Each method in the service is translated to javascript, and can be accessed from JavaScript similarly as you would from Java.

For example, if the AlbumService.js script were included, JavaScript for calling the getAlbumByKey(Object) method would be included. The method could then be called via javascript:

<input type="button" value="Fetch Album" onclick="getAlbumByKey(123)"/>
<script>
function onGetAlbumByKey(url,http_request) {
  alert('Album: '+http_request.responseText);
}
</script>

When the Fetch Album button is clicked, the album with the key 123 is fetched. On fetch, the onGetAlbumByKey method is called. The parameters are:

url - the url to which the request was made
http_request - the ajax request object, which contains the .requestText and .requestXML values, which represent the value (in XML format) of the result of the service call. If an error occurs, the root element is an <exception> element.

method If you're just using one method from the service, you can import only the used method.

<script src="/js/org.benow.util.Request.js">;</script>
<script src="/svc/doc.walkthru.AlbumService.insertTrack(Object,Track).js">;</script>

Files with the extension .js which are named the same as the page are automatically included. The same goes for css stylesheets. So, for some.page both some.js and some.css would be automatically included. This allows for nice separation between the various pieces that make up the page.

Complex Object Submission

Complex objects (ie not simple object such as integers, strings, dates, urls, etc) can be submitted with javascript by posting xml or a document.

For example, lets say the service method public void createAlbum(@ParamName("album") Album album) was to be called. XML string submission could be used:

function doCreateAlbum() {
  // set the type of object to be created
  var xml='<album type="doc.walkthru.AlbumImpl">';
  var title=document.getElementById('title').value;
  xml+='<title>'+title+'</title>
  xml=+'</album>';
  createAlbum(xml);
}

or via a document:

function doCreateAlbum() {
  var doc=newDocument();
  var albumE=DOM_createElement(doc,'album');
  // set the type of object to be created
  albumE.setAttribute('type','doc.walkthru.AlbumImpl');
  var title=document.getElementById('title').value;
  DOM_createElement(albumE,'title',title);
  createAlbum(doc);
  // or this will work too
  // createAlbum(albumE);
}

Note that for document submission to work, the script /js/org.benow.util.DOM.js must be included (and is the source for the newDocument() and DOM_createElement() utility methods). The 'type' attribute for complex objects must be be included in order for object construction to occur. Additionally, these types must have a zero parameter constructor (of any exposure, including private or protected).

Beware, however. There a some security concerns with complex object submission. Objects will be unmarshalled according to their type. If the service persists these objects, they will be persisted as they arrived. It is possible for a malicious user to post more than is expected, and if not handled by the programmer, then unexpected results could occur, including security problems. Ensure to validate incoming data and nullify any data which may not be safe. As a small safety feature, the system will throw an error if submission of a user (of interface User) is attempted. It is up to you to ensure that a malicious user does not try to claim ownership of other objects, etc.

Complex object submission via XML can be quite useful is creating pages with much functionality. By using dhtml techniques, much information can be gathered, with hierarchies maintained via xml representation.