Samstag, Oktober 13, 2007

Calling web services with structured parameters from JavaScript

In many situations it is better to use structured parameters when calling SOAP based web services then using a long list of simple parameters. The proxy layer of the AjaxEngine now also supports these parameters by converting JavaScript Objects to the XML notation used in the transferred SOAP message.

Parameters

Using methods with structured parameters using JavaScript Objects is directly supported, just pass them with the right properties.
Here is a partial sample for a web service definition in C#:

// Define a point in the 3D space. public class Point3D {
  public double x, y, z;
} // Point3D

[WebMethod(Description = "Calculate the distance of 2 points in the 3D space.")]
// Test function passing structured objects.
public double CalcDistance3D(Point3D p1, Point3D p2) {
  Point3D v = new Point3D();
  v.x = p2.x - p1.x;
  v.y = p2.y - p1.y;
  v.z = p2.z - p1.z;
  double dist = Math.Sqrt((v.x * v.x) + (v.y * v.y) + (v.z * v.z));
  return (dist);
} // CalcDistance3D 

Calling this method from JavaScript by using the generated proxy method is easy by using JavaScript Objects:

var p1 = {x:3, y:2, z:-4};
var p2 = {x:1, y:1, z:1};
var dist = proxies._types.CalcDistance3D(p1, p2);

If you like to use XmlDocuments ???

Structured return values

Methods of web services may also return structured values. Here is a sample of a method for calculating a vector in the 3D space:

[WebMethod(Description = "Calculate the vector between 2 points in the 3D space.")]
// Test function returning a complex object.
public Point3D CalcVector3D(Point3D p1, Point3D p2) {
  Point3D v = new Point3D();
  v.x = p2.x - p1.x;
  v.y = p2.y - p1.y;
  v.z = p2.z - p1.z;
  return (v);
} // CalcVector3D

Structured values that are returned by methods are available as XmlDocuments when you call a method like this. If you prefer to have the value as an JavaScript Object there is a function available in the proxies namespace that you can use:

var p1 = {x:3, y:2, z:-4};
var p2 = {x:1, y:1, z:1};

var xmlVector = proxies._types.CalcVector3D(p1, p2);
var v = proxies.xml2json(xmlVector);
alert(v.x + "/" + v.y + "/" + v.z);

Limitations

Objects used as parameters cannot be too complex. JavaScript Objects that have native values
(not Arrays nor Objects) are supported.
The data must be available in the format that can be de-serialized on the server
so take care of decimal points and date values.

Up to now the only way to use complex parameters with SOAP methods
was to use a server side XmlDocument Object and to extract the given values by using the appropriate methods.

Download

This addition was done in the current version under development. Because ajax.js is almost independent from the other current changes you can download it to existing projects from the sourceforge repository at http://ajaxengine.svn.sourceforge.net/viewvc/ajaxengine/trunk/ajaxcore/ or from the website http://www.mathertel.de/AJAXEngine/ajaxcore/ajax.js.